Поделиться через

Авторизация в Microsoft Graph с помощью единого входа

  • Статья

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

Архитектура надстройки для единого входа и Microsoft Graph

Помимо страниц и кода JavaScript веб-приложения, в надстройке также должны размещаться (с тем же полным доменном именем) один или несколько веб-API, которые будут получать маркер доступа и отправлять запросы к Microsoft Graph.

Манифест надстройки содержит <элемент WebApplicationInfo> , который предоставляет важные сведения о регистрации приложений Azure в Office, включая разрешения для Microsoft Graph, необходимые надстройке.

Принцип работы во время выполнения

На следующей схеме показаны шаги, необходимые для входа и доступа к Microsoft Graph. Весь процесс использует маркеры доступа OAuth 2.0 и JWT.

Схема процесса единого входа.

  1. Клиентский код надстройки вызывает API Office.js getAccessToken. При этом узел Office получает маркер доступа для надстройки.

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

  2. Узел Office запрашивает маркер доступа на платформе удостоверений Майкрософт.

  3. Платформа удостоверений Майкрософт возвращает маркер доступа A в узел Office. Маркер доступа A предоставляет доступ только к собственным API-интерфейсам надстройки на стороне сервера. Он не предоставляет доступ к Microsoft Graph.

  4. Узел Office возвращает маркер доступа A в клиентский код надстройки. Теперь клиентский код может выполнять вызовы API на стороне сервера с проверкой подлинности.

  5. Клиентский код выполняет HTTP-запрос к веб-API на стороне сервера, требующий проверки подлинности. Он включает маркер доступа A в качестве подтверждения авторизации. Серверный код проверяет маркер доступа A.

  6. Код на стороне сервера использует поток OAuth 2.0 On-Behalf-Of (OBO) для запроса нового маркера доступа с разрешениями для Microsoft Graph.

  7. Платформа удостоверений Майкрософт возвращает новый маркер доступа B с разрешениями для Microsoft Graph (и маркером обновления, если надстройка запрашивает разрешение offline_access ). При необходимости сервер может кэшировать маркер доступа B.

  8. Серверный код отправляет запрос к API Microsoft Graph и включает маркер доступа B с разрешениями на Microsoft Graph.

  9. Microsoft Graph возвращает данные обратно в код на стороне сервера.

  10. Серверный код возвращает данные обратно в код на стороне клиента.

При последующих запросах клиентский код всегда передает маркер доступа A при выполнении вызовов кода на стороне сервера с проверкой подлинности. Код на стороне сервера может кэшировать маркер B , чтобы не запрашивать его повторно при будущих вызовах API.

Разработка надстройки с единым входом для Microsoft Graph

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

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

  • Проверяйте маркер доступа A каждый раз, когда он передается из клиентского кода. Дополнительные сведения см. в разделе Проверка маркера доступа;
  • Инициируйте поток OAuth 2.0 On-Behalf-Of (OBO) с помощью вызова платформы удостоверений Майкрософт, которая включает маркер доступа, некоторые метаданные о пользователе и учетные данные надстройки (ее идентификатор и секрет). Дополнительные сведения о потоке OBO см. в статьях Платформа удостоверений Майкрософт и поток OAuth 2.0 On-Behalf-Of.
  • При необходимости после завершения потока кэшируйте возвращенный маркер доступа B с разрешениями на Microsoft Graph. Это рекомендуется делать, если надстройка выполняет несколько вызовов в Microsoft Graph. Дополнительные сведения см. в статье Получение и кэширование маркеров с помощью библиотеки проверки подлинности Майкрософт (MSAL).
  • Создайте один или несколько методов веб-API, которые получают данные Microsoft Graph путем передачи маркера доступа B (возможно, кэшированного) в Microsoft Graph.

Подробные пошаговые инструкции и сценарии см. в следующих статьях:

Распространение надстроек с поддержкой единого входа в Microsoft AppSource

Когда администратор Microsoft 365 получает надстройку из AppSource, он может распространить ее через интегрированные приложения и предоставить надстройке согласие на доступ к областям Microsoft Graph. Однако пользователь также может получить надстройку непосредственно из AppSource. В этом случае пользователь должен предоставить согласие на надстройку. Это может создать потенциальную проблему с производительностью, для которой мы предоставили решение.

Если код передает allowConsentPrompt параметр в вызове getAccessToken, например OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, office может заставить пользователя предоставить согласие, если платформа удостоверений Майкрософт сообщает Office, что согласие еще не предоставлено надстройке. Однако по соображениям безопасности Office может только запрашивать у пользователя согласие на использование области Microsoft Graph profile . Office не может запрашивать согласие для других областей Microsoft Graph, даже User.Read. Это означает, что если пользователь предоставляет согласие на запрос, Office возвращает маркер доступа. Но попытка обменять маркер доступа на новый маркер доступа с дополнительными областями Microsoft Graph завершается ошибкой AADSTS65001, что означает, что согласие (для областей Microsoft Graph) не предоставлено.

Примечание.

Запрос согласия с { allowConsentPrompt: true } может по-прежнему завершиться ошибкой profile даже для области, если администратор отключил согласие пользователя. Дополнительные сведения см. в разделе Настройка согласия конечных пользователей для приложений с помощью Azure Active Directory.

Код может и должен обработать эту ошибку, вернувшись к альтернативной системе проверки подлинности, которая запрашивает у пользователя согласие на использование областей Microsoft Graph. Примеры кода см. в разделах Создание надстройки Office Node.js с использованием единого входа и Создание надстройки Office ASP.NET, использующего единый вход , и примеры, на которые они ссылаются. Весь процесс требует нескольких кругового пути на платформу удостоверений Майкрософт. Чтобы избежать такого снижения производительности, включите forMSGraphAccess параметр в вызов getAccessToken; например, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Это сигнализирует Office о том, что надстройка нуждается в областях Microsoft Graph. Office попросит платформу удостоверений Майкрософт убедиться, что надстройке уже предоставлено согласие на области Microsoft Graph. Если это так, возвращается маркер доступа. Если это не так, вызов возвращает ошибку getAccessToken 13012. Код может обработать эту ошибку, немедленно вернувшись к альтернативной системе проверки подлинности без обреченной попытки обмена маркерами с платформой удостоверений Майкрософт.

Рекомендуется всегда передавать в forMSGraphAccessgetAccessToken , когда надстройка будет распространяться в AppSource и требует областей Microsoft Graph.

Сведения об едином входе в надстройке Outlook

Если вы разрабатываете надстройку Outlook, которая использует единый вход, и загружаете ее неопубликованное приложение для тестирования, Office всегда будет возвращать ошибку getAccessToken 13012 при forMSGraphAccess передаче в , даже если было предоставлено согласие администратора. По этой причине при разработке надстройки forMSGraphAccess Outlook следует закомментировать параметр. Обязательно раскомментируйте параметр при развертывании в рабочей среде. Фиктивный код 13012 происходит только при загрузке неопубликованных приложений в Outlook.

Для надстроек Outlook обязательно включите современную проверку подлинности для клиента Microsoft 365. Сведения о том, как это сделать, см. в статье Включение или отключение современной проверки подлинности для Outlook в Exchange Online.

Google Chrome работает над тем, чтобы предоставить пользователям больший контроль над их просмотром. Пользователи смогут блокировать сторонние файлы cookie в браузере Chrome. Это помешает вашей надстройке использовать такие файлы cookie. Это может вызвать проблемы, когда надстройка проверяет подлинность пользователя, например несколько запросов на вход или ошибки.

Улучшенные возможности проверки подлинности см. в статье Использование состояния устройства для улучшения единого входа в браузерах с заблокированными сторонними файлами cookie.

Дополнительные сведения о выпуске Google Chrome см. в статье Новый путь для песочницы конфиденциальности в Интернете.

См. также