Обзор проверки подлинности и авторизации в надстройках Office

  • Статья

Надстройки Office по умолчанию разрешают анонимный доступ, но вы можете потребовать, чтобы пользователи входили в систему для того, чтобы использовать вашу надстройку с помощью учетной записи Microsoft, Microsoft 365 для образования или рабочей либо другой общей учетной записи. Эта задача называется проверкой подлинности пользователей, так как она позволяет надстройке определить пользователя.

Ваша надстройка также может получить согласие пользователя на доступ к данным Microsoft Graph (например, к его профилю Microsoft 365, файлам OneDrive и данным SharePoint) или к данным из других внешних источников, таких как Google, Facebook, LinkedIn, SalesForce и GitHub. Эта задача называется авторизацией надстройки (или приложения), так как авторизована именно надстройка , а не пользователь.

Ключевые ресурсы для проверки подлинности и авторизации

В этой документации объясняется, как создавать и настраивать надстройки Office для успешной реализации проверки подлинности и авторизации. Однако многие упомянутые концепции и технологии безопасности не являются частью этой документации. Например, здесь не объясняются общие концепции безопасности, такие как потоки OAuth, кэширование токенов или управление удостоверениями. В этой документации также не описаны сведения, относящиеся к Microsoft Azure или платформа удостоверений Майкрософт. Мы рекомендуем использовать следующие ресурсы, если вам нужно больше информации в этих областях.

Сценарии единого входа

Использование единого входа (SSO) удобно для пользователей, поскольку им нужно войти в Office только один раз. Им не нужно входить в надстройку отдельно. Единый вход поддерживается не во всех версиях Office, поэтому вам по-прежнему потребуется реализовать альтернативный подход к входу с помощью платформа удостоверений Майкрософт. Дополнительные сведения о поддерживаемых версиях Office см. в статье Наборы требований API удостоверений

Получение удостоверений пользователя с помощью единого входа

Часто надстройка требует только удостоверение пользователя. Например, можно просто персонализировать надстройку и отобразить имя пользователя в области задач. Или может потребоваться уникальный ИД, чтобы сопоставить пользователя с его данными в базе данных. Для этого достаточно получить маркер доступа для пользователя из Office.

Чтобы получить удостоверение пользователя с помощью единого входа, вызовите метод getAccessToken. Метод возвращает маркер доступа, который также является маркером удостоверения, содержащим несколько утверждений, уникальных для текущего пользователя, выполнившего вход, в том числе preferred_username, name, sub и oid. Дополнительные сведения об этих свойствах см. в статье Маркеры ИД платформы удостоверений Майкрософт. Пример маркера, возвращаемого методом getAccessToken, см. в статье Пример маркера доступа.

Если пользователь не вошел в систему, Office откроет диалоговое окно и с помощью платформа удостоверений Майкрософт попросит пользователя войти в систему. Затем метод возвращает маркер доступа или выдает ошибку, если пользователь не может войти в систему.

В случае, когда вам необходимо хранить данные для пользователя, см. статью Маркеры ИД платформы удостоверений Майкрософт, чтобы ознакомиться с дополнительными сведениями о том, как получить значение из маркера для уникальной идентификации пользователя. Используйте это значение для поиска пользователя в таблице или базе данных пользователей, которую вы поддерживаете. Используйте базу данных для хранения сведений, относящихся к пользователям, например параметров пользователя или состояния учетной записи пользователя. Так как вы используете единый вход, пользователи не входят в надстройку отдельно, поэтому вам не нужно хранить пароль для пользователя.

Прежде чем приступить к реализации проверки подлинности пользователей с помощью единого входа, убедитесь, что вы хорошо знакомы со статьей Включение единого входа для надстроек Office.

Доступ к веб-API с помощью единого входа

Если в надстройке есть серверные API, требующие авторизованных пользователей, вызовите метод getAccessToken, чтобы получить маркер доступа. Маркер доступа предоставляет доступ к вашему веб-серверу (настроен с помощью регистрации приложения Microsoft Azure). При вызове API на веб-сервере вы также передаете маркер доступа для авторизации пользователя.

Следующий код показывает, как создать HTTPS-запрос GET к API веб-сервера надстройки для получения некоторых данных. Код выполняется на стороне клиента, например в области задач. Сначала он получает маркер доступа, вызывая getAccessToken. Затем создается вызов AJAX с правильным заголовком авторизации и URL-адресом для серверного API.

function getOneDriveFileNames() {

    let accessToken = await Office.auth.getAccessToken();

    $.ajax({
        url: "/api/data",
        headers: { "Authorization": "Bearer " + accessToken },
        type: "GET"
    })
        .done(function (result) {
            //... work with data from the result...
        });
}

В следующем коде показан пример обработчика /api/data для вызова REST из предыдущего примера кода. Код представляет собой код ASP.NET, запущенный на веб-сервере. Атрибут [Authorize] потребует, чтобы от клиента был передан действительный маркер доступа, или он вернет клиенту ошибку.

    [Authorize]
    // GET api/data
    public async Task<HttpResponseMessage> Get()
    {
        //... obtain and return data to the client-side code...
    }

Доступ к Microsoft Graph с помощью единого входа

В некоторых сценариях требуется не только удостоверение пользователя, но и доступ к ресурсам Microsoft Graph от имени пользователя. Например, вам может потребоваться отправить электронное сообщение или создать чат в Teams от имени пользователя. Эти действия и многое другое можно выполнить с помощью Microsoft Graph. Выполните следующие действия:

  1. Получите маркер доступа для текущего пользователя с помощью единого входа, вызвав метод getAccessToken. Если пользователь не вошел в систему, Office откроет диалоговое окно и войдет в систему с помощью платформа удостоверений Майкрософт. После входа пользователя метод возвращает маркер доступа,
  2. Передайте маркер доступа в код на стороне сервера.
  3. На стороне сервера используйте поток On-Behalf-Of OAuth 2.0, чтобы обменять маркер доступа на новый, содержащий необходимое делегированное удостоверение пользователя и разрешения для вызова Microsoft Graph.

Примечание.

Для обеспечения наилучшей безопасности во избежание утечки маркера доступа, всегда запускайте поток OBO на стороне сервера. Вызовите API Microsoft Graph со своего сервера, а не клиента. Не возвращайте маркер доступа в код на стороне клиента.

Прежде чем приступить к реализации единого входа для доступа к Microsoft Graph в надстройке, убедитесь, что вы хорошо знакомы со следующими статьями.

Вы также должны прочитать хотя бы одну из следующих статей, в которые показано, как создать надстройку Office для использования единого входа и доступа к Microsoft Graph. Даже если вы не выполняете описанные действия, они содержат важную информацию о реализации единого входа и потока OBO.

Сценарии без единого входа

В некоторых сценариях вы можете не использовать единый вход. Например, может потребоваться проверка подлинности с помощью другого поставщика удостоверений, а не с помощью платформы удостоверений Майкрософт. Кроме того, единый вход поддерживается не во всех сценариях. Например, более старые версии Office не поддерживают единый вход. В этом случае необходимо вернуться к альтернативной системе проверки подлинности для надстройки.

Проверка подлинности на платформе удостоверений Майкрософт

Ваша надстройка может выполнять вход для пользователей с помощью платформы удостоверений Майкрософт в качестве поставщика проверки подлинности. После входа пользователя вы можете использовать платформа удостоверений Майкрософт для авторизации надстройки в Microsoft Graph или других службах, управляемых корпорацией Майкрософт. Используйте этот метод входа в качестве альтернативного, если единый вход через Office недоступен. Кроме того, существуют сценарии, в которых вы хотите, чтобы пользователи входить в надстройку отдельно, даже если единый вход доступен. например, если вы хотите, чтобы они имели возможность входа в надстройку с идентификатором, отличным от идентификатора, с которым они в настоящее время вошли в Office.

Важно отметить, что платформа удостоверений Майкрософт не разрешает открывать страницу входа в iframe. Когда надстройка Office запущена в Office в Интернете, область задач является iframe. Это означает, что вам потребуется открыть страницу входа, используя диалоговое окно, открытое с помощью Dialog API для Office. Это влияет на способ использования библиотек помощника проверки подлинности. Дополнительные сведения см. в статье Проверка подлинности с помощью Dialog API для Office.

Сведения о реализации проверки подлинности с помощью платформы удостоверений Майкрософт см. в статье Общие сведения о платформе удостоверений Майкрософт версии 2.0. Документация содержит множество учебных пособий и руководств, а также ссылки на соответствующие примеры и библиотеки. Как описано в статье Проверка подлинности с помощью Dialog API для Office, вам может потребоваться изменить код из примеров, чтобы запустить его в диалоговом окне Office.

Доступ к Microsoft Graph без единого входа

Вы можете получить для надстройки разрешение на доступ к данным Microsoft Graph, получив маркер доступа к Microsoft Graph из платформы удостоверений Майкрософт. Это можно сделать, не полагаясь на единый вход через Office (или если единый вход завершился сбоем или не поддерживается). Дополнительные сведения см. в статье Доступ к Microsoft Graph без единого входа, содержащей подробности и ссылки на примеры.

Доступ к сторонним источникам данных (отличным от Майкрософт)

С помощью популярных веб-служб, в том числе Google, Facebook, LinkedIn, SalesForce и GitHub, разработчики могут предоставлять пользователям доступ к их учетным записям в других приложениях. Благодаря этому вы можете включать эти службы в свои надстройки Office. Обзор способов, доступных вашей надстройке для выполнения этих действий, см. в статье Авторизация внешних служб в надстройке Office.

Важно!

Прежде чем приступить к написанию кода, узнайте, позволяет ли источник данных открывать страницу входа в iframe. Когда надстройка Office запущена в Office в Интернете, область задач является iframe. Если источник данных не позволяет открывать страницу входа в iframe, необходимо открыть страницу входа в диалоговом окне, открывшемся с помощью API диалогового окна Office. Дополнительные сведения см. в статье Проверка подлинности с помощью Dialog API для Office.

См. также