Зарегистрируйте надстройку Office, которая использует единый вход (SSO) с помощью платформа удостоверений Майкрософт

  • Статья

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

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

Информация Примеры Заполнитель
Понятное для пользователя имя надстройки. (Уникальность рекомендуется, но не обязательна.) Contoso Marketing Excel Add-in (Prod) <add-in-name>
Идентификатор приложения, который Azure создает для вас в процессе регистрации. c6c1f32b-5e55-4997-881a-753cc1d563b7 <app-id>
Полное доменное имя надстройки (за исключением протокола). Необходимо использовать собственный домен. По этой причине нельзя использовать определенные известные домены, такие как azurewebsites.net или cloudapp.net. Домен должен быть таким же, как и все поддомены, как используется в URL-адресах в <разделе Ресурсы> манифеста надстройки. localhost:6789, addins.contoso.com <fully-qualified-domain-name>
Разрешения для платформа удостоверений Майкрософт и Microsoft Graph, необходимые вашей надстройке. (Разрешение profile требуется всегда.) profile, Files.Read.All Н/Д

Предостережение

Конфиденциальная информация. URI идентификатора приложения (<fully-qualified-domain-name>) регистрируется в процессе проверки подлинности при активации надстройки с использованием единого входа в Office, работающей в Microsoft Teams. Универсальный код ресурса (URI) не должен содержать конфиденциальную информацию.

Регистрация надстройки с помощью платформа удостоверений Майкрософт

Необходимо создать регистрацию приложения в Azure, представляющего веб-сервер. Это обеспечивает поддержку проверки подлинности, чтобы в коде клиента в JavaScript можно было выдавать правильные маркеры доступа. Эта регистрация поддерживает как единый вход в клиенте, так и резервную проверку подлинности с помощью библиотеки проверки подлинности Майкрософт (MSAL).

  1. Войдите в портал Azure с учетными данными администратора в клиенте Microsoft 365. Например, MyName@contoso.onmicrosoft.com.

  2. Выберите Регистрация приложений. Если значок не отображается, найдите "регистрация приложения" в строке поиска.

    Домашняя страница портал Azure.

    Появится страница регистрации приложений.

  3. Выберите Новая регистрация.

    Новая регистрация на панели Регистрация приложений.

    Появится страница Регистрация приложения.

  4. На страницеЗарегистрировать приложение задайте необходимые значения следующим образом.

    • Введите имя<add-in-name>.
    • Задайте для значения Поддерживаемые типы учетных записейзначение Учетные записи в любом каталоге организации (любой каталог Azure AD — мультитенантный) и личных учетных записей Майкрософт (например, Skype, Xbox).
    • Задайте URI перенаправления, чтобы использовать одностраничное приложение платформы (SPA), а URI — .https://<fully-qualified-domain-name>/dialog.html

    Зарегистрируйте область приложения с именем и поддерживаемой учетной записью.

  5. Нажмите Зарегистрировать. Появится сообщение о том, что регистрация приложения создана.

    Сообщение о том, что регистрация приложения создана.

  6. Скопируйте и сохраните значения идентификатора приложения (клиента) и идентификатора каталога (клиента). Они понадобятся вам позже.

    Область регистрации приложений для Contoso с идентификатором клиента и идентификатором каталога.

Добавление секрета клиента

Секрет клиента, который иногда называется паролем приложения, — это строковое значение, которое приложение может использовать вместо сертификата для идентификации себя.

  1. В области слева выберите Сертификаты & секреты. Затем на вкладке Секреты клиента выберите Новый секрет клиента.

    Область

    Откроется панель Добавление секрета клиента .

  2. Добавьте описание секрета клиента.

  3. Выберите срок действия секрета или укажите пользовательское время существования.

    • Время существования секрета клиента ограничено двумя годами (24 месяцами) или менее. Нельзя указать пользовательское время существования, превышающее 24 месяца.
    • Корпорация Майкрософт рекомендует установить срок действия менее 12 месяцев.

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

  4. Нажмите Добавить. Создается новый секрет, а значение временно отображается.

Важно!

Запишите значение секрета для использования в коде клиентского приложения. Это значение секрета больше не отображается после выхода из этой области.

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

  1. В области слева выберите Предоставить API.

    Откроется панель Предоставление API .

    Область Предоставления API для регистрации приложения.

  2. Выберите Задать , чтобы создать универсальный код ресурса (URI) идентификатора приложения.

    Кнопка

    Раздел для задания URI идентификатора приложения отображается с созданным URI идентификатора приложения в формате api://<app-id>.

  3. Обновите URI идентификатора приложения на api://<fully-qualified-domain-name>/<app-id>.

    Измените область URI идентификатора приложения, указав для порта localhost значение 44355.

    • URI идентификатора приложения предварительно заполняется идентификатором приложения (GUID) в форматеapi://<app-id>.
    • Формат URI идентификатора приложения должен иметь следующий формат: api://<fully-qualified-domain-name>/<app-id>
    • Вставьте между fully-qualified-domain-nameapi:// и <app-id> (который является GUID). Например, api://contoso.com/<app-id>.
    • Если вы используете localhost, формат должен иметь формат api://localhost:<port>/<app-id>. Например, api://localhost:3000/c6c1f32b-5e55-4997-881a-753cc1d563b7.

    Дополнительные сведения о URI идентификатора приложения см. в разделе Идентификатор манифеста приложения.

    Примечание.

    Если возникает ошибка с сообщением о том, что домен уже занят, но при этом вы являетесь его владельцем, следуйте процедуре в статье Краткое руководство. Добавление имени личного домена в Azure Active Directory, чтобы зарегистрировать его, а затем повторите этот шаг. (Эта ошибка также может возникнуть, если вы не выполнили вход с учетными данными администратора в клиенте Microsoft 365. См. шаг 2. Выйдите и снова войдите с учетными данными администратора и повторите процесс из шага 3.)

Добавление область

  1. На странице Предоставление API выберите Добавить область.

    Нажмите кнопку Добавить область.

    Откроется панель Добавление область.

  2. В области Добавление область укажите атрибуты область. В следующей таблице показаны примеры значений для надстройки и Outlook, для которых требуются profileразрешения , openid, Files.ReadWriteи Mail.Read . Измените текст в соответствии с разрешениями, которые требуются надстройке.

    Поле Описание Values
    Имя области Имя область. Общее соглашение об именовании область — .resource.operation.constraint Для единого входа необходимо задать значение access_as_user.
    Кто может согласиться Определяет, требуется ли согласие администратора или пользователи могут предоставить согласие без одобрения администратора. Для изучения единого входа и примеров рекомендуется задать для этого параметра значение Администраторы и пользователи.

    Выберите Администраторы только для более привилегированных разрешений.
    отображаемое имя согласия Администратор Краткое описание назначения область, видимое только администраторам. Read/write permissions to user files. Read permissions to user mail and profiles.
    описание согласия Администратор Более подробное описание разрешения, предоставленного область, которое видят только администраторы. Allow Office to have read/write permissions to all user files and read permissions to all user mail. Office can call the app's web APIs as the current user.
    Отображаемое имя согласия пользователя Краткое описание назначения область. Отображается для пользователей только в том случае, если для администраторов и пользователей задан параметр Кто может предоставить согласие. Read/write permissions to your files. Read permissions to your mail and profile.
    Описание согласия пользователя Более подробное описание разрешения, предоставляемого область. Отображается для пользователей только в том случае, если для администраторов и пользователей задан параметр Кто может предоставить согласие. Allow Office to have read/write permissions to your files, and read permissions to your mail and profile.

  3. Задайте для параметра Состояниезначение Включено, а затем выберите Добавить область.

    Задайте для параметра Состояние включено и нажмите кнопку Добавить область.

    Новый область, который вы определили, отображается на панели.

    Новая область отображается на панели Предоставление API.

    Примечание.

    Доменная часть имени области, отображаемая непосредственно под текстовым полем, должна автоматически соответствовать URI идентификатора приложения, заданного на предыдущем шаге, с добавлением /access_as_user в конце, например: api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  4. Выберите Добавить клиентское приложение.

    Выберите Добавить клиентское приложение.

    Откроется панель Добавление клиентского приложения .

  5. В поле Идентификатор клиента введите ea5a67f6-b6f3-4338-b240-c655ddc3cc8e. Это значение предварительно разрешает все конечные точки приложений Microsoft Office. Если вы также хотите предварительно авторизовать Office при использовании в Microsoft Teams, добавьте 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Microsoft Teams desktop и Teams mobile) и 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams в Интернете).

    Примечание.

    Идентификатор ea5a67f6-b6f3-4338-b240-c655ddc3cc8e предварительно авторизует Office на всех следующих платформах. Кроме того, можно ввести соответствующее подмножество следующих идентификаторов, если по какой-либо причине вы хотите запретить авторизацию Office на некоторых платформах. В этом случае оставьте идентификаторы платформ, с которых вы хотите удержать авторизацию. Пользователи надстройки на этих платформах не смогут вызывать веб-API, но другие функции надстройки по-прежнему будут работать.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office).
    • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office в Интернете).
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook в Интернете).

  6. В разделе Авторизованные области установите api://<fully-qualified-domain-name>/<app-id>/access_as_user флажок.

  7. Нажмите кнопку Добавить приложение.

    Панель Добавление клиентского приложения.

Добавление разрешений Microsoft Graph

  1. В области слева выберите Разрешения API.

    Область разрешений API.

    Откроется область разрешений API .

  2. Выберите Добавить разрешение.

    Добавление разрешения на область разрешений API.

    Откроется область Запрашивать разрешения API .

  3. Выберите Microsoft Graph.

    Панель Запрашивать разрешения API с помощью кнопки Microsoft Graph.

  4. Выберите Делегированные разрешения.

    Панель Запрашивать разрешения API с делегированными разрешениями.

  5. В поле поиска Выбор разрешений найдите разрешения, необходимые надстройке. Например, для надстройки Outlook можно использовать profile, , openidFiles.ReadWriteи Mail.Read.

    Примечание.

    Разрешение User.Read может быть уже указано по умолчанию. Рекомендуется запрашивать только необходимые разрешения, поэтому рекомендуется снять флажок для этого разрешения, если надстройка не нуждается в нем.

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

    Область Запрашивать разрешения API с выбранными разрешениями.

  7. Выберите Предоставить согласие администратора для [имя клиента]. Выберите Да , чтобы появилось подтверждение.

Настройка версии маркера доступа

Необходимо определить версию маркера доступа, приемлемую для вашего приложения. Эта конфигурация выполняется в манифесте приложения Azure Active Directory.

Определение версии маркера доступа

Версия маркера доступа может измениться, если вы выбрали тип учетной записи, отличной от Учетные записи в любом каталоге организации (любой каталог Azure AD — мультитенантный), и личные учетные записи Майкрософт (например, Skype, Xbox). Выполните следующие действия, чтобы убедиться, что версия маркера доступа правильна для использования единого входа Office.

  1. В левой области выберите Манифест.

    Выберите Манифест Azure.

    Откроется манифест приложения Azure Active Directory.

  2. Введите 2 в качестве значения свойства accessTokenAcceptedVersion.

    Значение для принятой версии маркера доступа.

  3. Нажмите кнопку Сохранить.

    В браузере появится сообщение об успешном обновлении манифеста.

    Сообщение об обновлении манифеста.

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