Включение единого входа для расширений сообщений на основе API

Статья
10/28/2024

Метод проверки подлинности единого входа (SSO) для расширения сообщений на основе API использует удостоверение Пользователя приложения в Teams, чтобы предоставить ему доступ к вашему приложению. Пользователю, выполнившему вход в Teams, не нужно повторно входить в приложение в среде Teams. Microsoft Entra единый вход позволяет приложению автоматически получать маркер пользователя, выданный для ресурса Microsoft Entra. Затем приложение может пройти проверку подлинности этого маркера и получить сведения профиля пользователя без согласия пользователя.

Предварительные условия

Перед началом работы убедитесь, что у вас есть следующее:

Учетная запись Azure с активной подпиской.
Базовое знакомство с разработкой приложений Microsoft Entra ID и Teams.

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

Пользователь вызывает приложение расширения сообщений на основе API в Teams и вызывает команду, требующую проверки подлинности.
Приложение отправляет запрос в серверную службу Teams с идентификатором приложения и необходимым область (access_as_user).
Серверная служба Teams проверяет, согласился ли пользователь на приложение и область. Если нет, отобразится экран согласия для пользователя.
Если пользователь дает согласие, Microsoft Entra создает маркер доступа для пользователя и приложения и отправляет его приложению в заголовке авторизации запроса.
Приложение проверяет маркер и извлекает из маркера сведения о пользователе, такие как имя, адрес электронной почты и идентификатор объекта.
После успешной проверки подлинности пользователю предоставляется доступ к расширению сообщений на основе API.

Чтобы включить проверку подлинности единого входа для расширения сообщений на основе API, выполните следующие действия.

Зарегистрируйте новое приложение в Microsoft Entra ID.
Настройте область для маркера доступа.
Маркер проверки подлинности.
Обновление манифеста приложения.

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

Откройте портал Azure в веб-браузере.
Выберите значок регистрации приложений.

Появится страница регистрации приложений.
Выберите значок + Новая регистрация.

Появится страница Регистрация приложения.
Введите имя своего приложения, которое вы хотите отобразить для пользователя приложения. Вы можете изменить имя на более позднем этапе, если захотите.

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

Параметры для поддерживаемых типов учетных записей

Параметр	Выберите это, чтобы...
Только учетные записи в этом каталоге организации (только Майкрософт — один клиент)	Создайте приложение для использования только пользователями (или гостями) в вашем клиенте. Это приложение, часто называемое пользовательским приложением, созданным для вашей организации (LOB), является приложением с одним клиентом в платформа удостоверений Майкрософт.
Учетные записи в любом каталоге организации (любой клиент Microsoft Entra ID — мультитенантный клиент)	Разрешите пользователям в любом клиенте Microsoft Entra использовать ваше приложение. Этот вариант подходит, например, если вы создаете приложение SaaS и планируете сделать его доступным для нескольких организаций. Этот тип приложения называется мультитенантным приложением в платформа удостоверений Майкрософт.
Учетные записи в любом каталоге организации (любой клиент Microsoft Entra ID — мультитенантный) и личные учетные записи Майкрософт (например, Skype, Xbox)	Нацелить на самый широкий круг клиентов. Выбрав этот параметр, вы регистрируете мультитенантное приложение, которое может поддерживать пользователей приложений с личными учетными записями Майкрософт.
Только личные учетные записи Майкрософт	Создавайте приложение только для пользователей, у которых есть личные учетные записи Microsoft.

Примечание.

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

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

Отобразится страница с идентификатором приложения и другими сведениями о приложении.
Запишите и сохраните идентификатор приложения из идентификатора приложения (клиента), чтобы позже обновить манифест приложения.

Приложение зарегистрировано в Microsoft Entra ID. Теперь у вас есть идентификатор приложения расширения сообщений на основе API.

Настройка области для маркера доступа

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

Чтобы настроить область и авторизовать доверенные клиентские приложения, необходимо:

Добавление URI идентификатора приложения. Настройте параметры область (разрешения) для приложения. Предоставление веб-API и настройка URI идентификатора приложения.
Настройка область API. Определите область для API и пользователей, которые могут дать согласие на область. Вы можете позволить только администраторам давать согласие на более привилегированные разрешения.
Настройка авторизованного клиентского приложения. Создайте авторизованные идентификаторы клиентов для приложений, которые требуется предварительно авторизовать. Это позволяет пользователю приложения получать доступ к настроенным вами областям приложения (разрешениям) без дополнительного согласия. Предварительная проверка подлинности только тех клиентских приложений, которым вы доверяете, так как пользователи приложения не имеют возможности отклонить согласие.

URI кода надстройки

Выберите Управление>Предоставить API на панели слева.

Появится страница Предоставление API.
Выберите Добавить , чтобы создать URI идентификатора api://{AppID}приложения в виде .

Откроется раздел для настройки URI идентификатора приложения.
Введите URI идентификатора приложения в формате, описанном здесь.
- URI идентификатора приложения заполняется идентификатором приложения (GUID) в формате api://{AppID}.
- Формат URI идентификатора приложения должен иметь следующий формат: api://fully-qualified-domain-name.com/{AppID}.
- Вставьте между fully-qualified-domain-name.com и {AppID}api:// (то есть GUID). Например, api://example.com/{AppID}.
Важно!
- Если вы создаете автономного бота, введите URI идентификатора приложения как api://botid-{YourBotId}. Здесь {YourBotId} — это ваш Microsoft Entra идентификатор приложения.
- Если вы создаете приложение с помощью бота, расширения сообщений и вкладки, введите URI идентификатора приложения как api://fully-qualified-domain-name.com/botid-{YourClientId}, где {YourClientId} — это идентификатор приложения бота.
- Если вы создаете приложение с расширением для сообщений или возможностями вкладки без бота, введите URI идентификатора приложения как api://fully-qualified-domain-name.com/{YourClientId}, где {YourClientId} — это ваш Microsoft Entra идентификатор приложения.
- URI идентификатора приложения для приложения с несколькими возможностями. Если вы создаете расширение сообщений на основе API, введите URI идентификатора приложения в качестве api://fully-qualified-domain-name.com/{YourClientId}, где {YourClientId} — это идентификатор Microsoft Entra приложения.
- Формат доменного имени. Используйте только строчные буквы для доменного имени.
Выберите Сохранить.

В браузере появится сообщение о том, что URI идентификатора приложения был обновлен.

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

Настройка область API

Примечание.

Расширение сообщений на основе API поддерживает только область access_as_user.
API получает маркер доступа Microsoft Entra с область, зарегистрированным access_as_user в портал Azure. Однако маркер не авторизован для вызова других подчиненных API, таких как Microsoft Graph.

Выберите + Добавить область в разделе Области, определенные этим API.

Появится страница Добавление области.
Введите данные для конфигурации области действия.
1. Введите имя области. Это поле является обязательным.
2. Выберите пользователя, который может дать согласие на эту область. Параметр по умолчанию — Только для администраторов.
3. Введите отображаемое имя согласия администратора. Это поле является обязательным.
4. Введите описание для согласия администратора. Это поле является обязательным.
5. Введите отображаемое имя согласия пользователя.
6. Введите описание для описания согласия пользователя.
7. Выберите параметр Включено для состояния.
8. Нажмите Добавить область.
В браузере появится сообщение о том, что область добавлена.

Новая область, которую вы определили, отобразится на странице.

Настройка авторизованного клиентского приложения

Перейдите на страницу Предоставление API в раздел Авторизованное клиентское приложение и выберите + Добавить клиентское приложение.

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

Введите соответствующий идентификатор клиента Microsoft 365 для приложений, которые вы хотите авторизовать для веб-приложения приложения.

Снимок экрана: параметр Идентификатор клиента и Авторизованные области для добавления клиентского приложения в приложение в портал Azure. Добавление клиентского приложения

Примечание.

Идентификаторы клиентов Microsoft 365 для мобильных, настольных и веб-приложений для Teams — это фактические идентификаторы, которые необходимо добавить.

Выберите один из следующих идентификаторов клиентов:

Использовать идентификатор клиента	Для авторизации...
1fec8e78-bce4-4aaf-ab1b-5451cc387264	Мобильное или классическое приложение Teams
5e3ce6c0-2b1f-4285-8d4b-75ee78787346	Веб-приложение Teams

Выберите URI идентификатора приложения, созданный для приложения в авторизованных областях, чтобы добавить область в предоставленный веб-API.
Нажмите кнопку Добавить приложение.

В браузере появится сообщение о том, что авторизованное клиентское приложение добавлено.

На странице отображается идентификатор клиента авторизованного приложения.

Примечание.

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

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

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

Когда расширение сообщения вызывает API во время проверки подлинности, оно получает запрос с маркером доступа пользователя. Затем расширение сообщений добавляет маркер в заголовок авторизации исходящего HTTP-запроса. Формат заголовка — Authorization: Bearer <token_value>. Например, когда расширение сообщений выполняет вызов API к службе, требующей проверки подлинности. Расширение создает HTTP-запрос следующим образом:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

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

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

В следующем примере показан веб-токен JSON (JWT) с заголовком и ответом:

Токен версии 2
Токен версии 1

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

{
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "api://00000002-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/{tenantid}/",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "acr": "1",
  "aio": "AXQAi/8IAAAA",
  "amr": ["pwd"],
  "appid": "c44b4083-3bb0-49c1-b47d-974e53cbdf3c",
  "appidacr": "0",
  "ipaddr": "192.168.1.1",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "scp": "access_as_user",
  "sub": "AAAAAAAAAAAAAAAAAAAAAIkzqFVrSaSaFHy782bbtaQ",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  }

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

Обновление манифеста приложения

Обновите следующие свойства в файле манифеста приложения:

webApplicationInfo webApplicationInfo: свойство используется для включения единого входа в приложение, чтобы помочь пользователям приложения легко получить доступ к приложению расширения сообщений на основе API. URI идентификатора приложения, зарегистрированный в Microsoft Entra ID, настраивается с помощью область предоставленного API. Дополнительные сведения см. в webApplicationInfo.
microsoftEntraConfiguration: включает проверку подлинности единого входа для приложения. supportsSingleSignOn Настройте свойство для для true поддержки единого входа и уменьшения необходимости в нескольких проверках подлинности. Если свойство имеет значение false или остается пустым, пользователь не сможет отправить приложение в Teams, и приложение не пройдет проверку.

Чтобы настроить манифест приложения, выполните следующие действия.

Откройте приложение расширения сообщений на основе API.
Откройте папку манифеста приложения.
Примечание.
- Папка манифеста приложения должна находиться в корневой папке приложения. Дополнительные сведения см. в статье Создание пакета приложения Microsoft Teams.
- Дополнительные сведения о создании manifest.json см. в статье Схема манифеста приложения.
Откройте файл manifest.json.
Добавьте следующий фрагмент кода в webApplicationInfo раздел файла манифеста приложения:
```
"webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
```
где
- {Microsoft Entra AppId}— это идентификатор приложения, созданный при регистрации приложения в Microsoft Entra ID. Это GUID.
- api://subdomain.example.com/{Microsoft Entra AppId}— это URI идентификатора приложения, зарегистрированный при создании область в Microsoft Entra ID.
Добавьте следующий фрагмент кода в composeExtensions раздел файла манифеста приложения:
```
"authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},
```
Сохраните файл манифеста приложения.

Поздравляем! Вы включили единый вход для расширений сообщений на основе API.

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

Включение единого входа для расширений сообщений на основе API

Предварительные условия

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

Настройка области для маркера доступа

URI кода надстройки

Настройка область API

Настройка авторизованного клиентского приложения

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

Обновление манифеста приложения

См. также

Дополнительные ресурсы