Приложения Azure AD для надстроек Office и единого входа

  • 8 мин

Средства разработчика, предоставляемые корпорацией Майкрософт для создания надстроек Office с ASP.NET или Node.js включены служебные программы для регистрации требуемого Microsoft Entra приложения. Инструмент configure-sso упрощает не только процесс регистрации приложения, но и настройку рабочей станции разработчика.

В этом уроке вы узнаете, как создать регистрацию приложения Microsoft Entra для надстройки Office, которая реализует единый вход (SSO). Вы также изучите некоторые рекомендации корпорации Майкрософт по созданию надстроек Office, которые реализуют единый вход.

Регистрация приложения Microsoft Entra для единого входа надстроек Office

Давайте рассмотрим требования к регистрации приложения Microsoft Entra, используемого надстройкой Office, которая реализует единый вход.

регистрация приложения Microsoft Entra

Первым шагом является регистрация приложения Microsoft Entra в Центре администрирования Microsoft Entra (https://aad.portal.azure.com).

При регистрации приложения убедитесь, что поддерживаемые типы учетных записей должны быть учетными записями в любом каталоге организации (любой каталог Microsoft Entra — Мультитенантный) приложения.

Важно!

Приложения надстроек Office не могут быть приложениями с одним клиентом. Они должны быть мультитенантными.

Проверка подлинности

Далее необходимо настроить параметры проверки подлинности для приложения.

В вашем приложении должно быть не менее двух перечисленных URI перенаправления:

  • страница надстройки, например URL-адрес HTML-страницы области задач
  • резервная страница, например fallbackauthdialog.html

Следует включить параметры маркера неявного общего и гибридного потоков, так как надстройки Office обычно являются клиентскими приложениями:

  • Маркеры доступа (используются для неявных потоков)
  • Маркеры ИД (используются для неявных и гибридных потоков)

Снимок экрана: параметры проверки подлинности приложения.

Разрешения API

Еще одной важной частью приложения Microsoft Entra являются разрешения, необходимые для работы.

Каждому приложению необходимо предоставить разрешения OpenID openid и profile. Для некоторых библиотек требуются дополнительные разрешения. Например, библиотека проверки подлинности Microsoft для .NET требует разрешение office_access.

Если надстройке необходимы какие-либо разрешения для Microsoft Graph, их также следует добавить здесь.

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

Снимок экрана: добавленные разрешения.

Предоставление API

Приложение должно предоставлять собственные разрешения для Microsoft Entra id и клиентов Office. На экране Предоставление API задайте URI идентификатора приложения. По умолчанию это значение api://<APP_ID>, но его следует обновить, включив в него домен, в котором размещена база кода надстройки.

Включите URL-адрес перед частью URI <APP_ID>. Пример: api://addin.contoso.com/<APP_UD>. Этот домен должен соответствовать домену, в котором обслуживаются все ресурсы, определенные в файле manifest.xml надстройки.

Следующим шагом является предоставление разрешения, также называемого областью. Область access_as_user будет использоваться клиентами Office для указания, что они могут действовать от имени вошедшего в систему пользователя при предоставлении маркера начальной загрузки в Microsoft Graph при запуске потока OAuth2 On-Behalf-Of.

Наконец, необходимо предоставить это разрешение всем клиентским приложениям Office. Это позволяет приложению доверять всем клиентским приложениям Office для получения разрешения access_as_user.

Каждый тип клиента Office представлен уникальным ИД. Убедитесь, что вы включили следующее приложение. При этом убедитесь, что вы включаете разрешение access_as_user.

  • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Microsoft Office)

Снимок экрана: ИД и авторизованные клиенты, которым предоставлен доступ к API надстройки.

Важно!

Служба ea5a67f6-b6f3-4338-b240-c655ddc3cc8e представляет собой групповую авторизацию, которая включает в себя все остальные узлы Office, поэтому вы можете просто включить эту службу вместо перечисления каждого из следующих отдельных приложений:

  • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
  • 57fb890c-0dab-4253-a5e0-7188c88b2bb4 (Office в Интернете)
  • 08e18876-6177-487e-b8b5-cf950c1e598c (Office в Интернете)
  • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook в Интернете)
  • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office в Интернете)

Последняя служба, указанная выше, 93d53678-613d-4013-afc1-62e9e444a0a5 — это новая служба единого входа, представленная в январе 2022 г.

Рекомендации по разработке надстройки Office с единым входом

Корпорация Майкрософт рекомендует следующее при создании надстроек Office, которые реализуют единый вход.

Используйте allowConsentPrompt, если вам нужен только профиль пользователя

В некоторых случаях надстройка Office может использовать единый вход только для получения доступа к профилю пользователя. В таких случаях рассмотрите возможность переопределения поведения по умолчанию в процессе входа, передав параметр { allowConsentPrompt: true } при вызове getAccessToken() в пакете SDK Office.js.

Значение по умолчанию для этого свойства — false. Это свойство позволяет Office получать маркер доступа автоматически или посредством интерактивного согласия, если оно требуется. Если для свойства установлено значение false, то Office получит описательное сообщение об ошибке, если ему не удастся получить маркер из-за того, что пользователь не дал согласие.

Однако если установлено значение true, Office отобразит интерактивное согласие после того, как ему не удастся автоматически получить маркер доступа.

Важно!

Помните, что Office может запрашивать у пользователя согласие только на разрешение OpenID profile, но не на какие-либо разрешения Microsoft Graph.

Реализация резервного метода авторизации

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

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

Реализация подхода "завершение работы при первой ошибке" к авторизации

Повторяя предыдущий раздел, вспомните, что вы узнали на последнем уроке. Когда Office запрашивает маркер начальной загрузки, он может включать параметр авторизации { forGraphAccess: true } при вызове getAccessToken() в пакете SDK Office.js.

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

Предварительная авторизация всех клиентов Office с помощью надстройки

Как показано в этом уроке, вы можете предварительно авторизовать Microsoft Entra регистрации приложений, используемых надстройкой Office, чтобы доверять всем клиентским приложениям Office. К ним относятся все классические, мобильные и веб-клиенты Office.

Это гарантирует, что надстройка будет работать в максимальном количестве сценариев.