Проверка подлинности с помощью ключа API

Статья
10/28/2024

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

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

Базовый URL-адрес. Teams передает секрет конечным точкам URL-адресов, которые начинаются со значения в этом поле.
Целевой клиент: ограничение доступа API к клиенту Microsoft 365 или любому клиенту.
Идентификатор приложения. Чтобы ограничить доступ к ключу для определенного приложения или любого приложения.
Ключ API: проверка подлинности доступа к приложению.

Вы можете зарегистрировать ключ API на портале разработчика для Teams и создать идентификатор регистрации ключа API. Обновите манифест приложения с apiSecretServiceAuthConfiguration помощью объекта со свойством apiSecretRegistrationId . Это свойство должно содержать идентификатор регистрации ключа API, возвращаемый при отправке ключа API через портал разработчика для Teams.

Примечание.

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

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

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

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

Регистрация ключа API

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

Перейдите в раздел Сервис>регистрация ключа API.
Выберите + Создать ключ API.
На странице регистрации ключа API выберите + Добавить секрет. Откроется диалоговое окно Добавление ключа API .
Введите значение ключа и нажмите кнопку Сохранить.

Примечание.

Вы можете поддерживать до двух ключей API. Если вам нужно заменить один, это можно сделать без прерывания работы службы, так как Teams использует другой настроенный ключ во время процесса обновления.
В разделе Имя ключа API добавьте понятное имя для ключа API. Например, ключ API для расширения сообщений Contoso.
В разделе Базовый URL-адрес укажите общий базовый URL-адрес для всех конечных точек API, которые должны быть вызваны. Этот URL-адрес должен начинаться с https, включать полное доменное имя и при необходимости путь. Teams передает ключ в конечную точку URL-адреса, которая начинается со значения в этом поле. Например, https://api.yelp.com.

Базовый URL-адрес гарантирует, что ключ остается безопасным и не будет утечки в случайные конечные точки, даже если другое приложение незаконно получает идентификатор регистрации ключа API и включает его в свое приложение. Если URL-адрес, зарегистрированный в конфигурации ключа API, не является префиксом для целевых конечных точек, определенных в спецификации OpenAPI, вызов удаляется.
В разделе Целевой клиент выберите любой из следующих вариантов:
- Домашний клиент. Ключ API работает только в том клиенте, в котором он зарегистрирован.
- Любой клиент. Ключ API можно использовать в любом клиенте.
В разделе Целевое приложение Teams выберите одно из следующих элементов:
- Существующее приложение Teams. Параметр существующего приложения Teams привязывает идентификатор регистрации ключа API к конкретному приложению Teams.
- Любое приложение Teams: ключ API можно использовать с любым приложением Teams.
Создается идентификатор регистрации ключа API .
На портале разработчика для Teams выберите Приложения и выберите приложение, в которое нужно добавить ключ API.
Перейдите в раздел Функции> приложенияРасширение сообщений.
В разделе Проверка подлинности выберите Ключ API и добавьте идентификатор регистрации ключа API.
Выберите Сохранить.

Идентификатор регистрации ключа API обновляется как значение свойства в манифесте apiSecretRegistrationId приложения. Вы можете проверить идентификатор регистрации ключа API в манифесте приложения на портале разработчика для Teams.

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

apiSecretServiceAuthConfiguration Добавьте объект со свойством apiSecretRegistrationId , который содержит идентификатор ссылки при отправке ключа API через портал разработчика для Teams. Дополнительные сведения см. в разделе composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Лучшие методики

Ключ API:
- Ключ API должен содержать не менее 10 символов и не более 2048 символов.
- После обновления ключа API его отражение в системе занимает до одного часа.
Базовый URL-адрес:
- Базовый URL-адрес должен начинаться с https , чтобы обеспечить безопасную связь.
- Чтобы указать точный домен, необходимо указать полное имя узла.
- Можно добавить необязательный путь для определения конкретной точки входа для API.
Эта структура имеет решающее значение для безопасности ключей API, так как Teams отправляет ключ API в конечные точки, которые начинаются с указанного базового URL-адреса.
Целевой клиент. При разработке приложения в клиенте Microsoft 365 вы сначала протестируете его как пользовательское приложение, созданное для вашей организации (бизнес-приложение) или пользовательское приложение. На этом этапе необходимо зарегистрировать ключ API в домашнем клиенте в качестве целевого клиента, чтобы ключ оставался монопольным для вашего клиента.

После завершения тестирования и готовности к отправке манифеста приложения в Центр партнеров для Магазина Teams необходимо переключить целевой параметр клиента на Любой клиент. Это изменение позволяет использовать идентификатор регистрации ключа API в разных клиентах после того, как приложение станет доступно в Магазине Teams.
Идентификатор приложения Teams. При разработке приложения в клиенте Microsoft 365 и запуске его тестирования в качестве настраиваемого приложения, созданного для вашей организации или пользовательского приложения, необходимо задать идентификатор регистрации ключа API с идентификатором приложения Teams в качестве любого приложения Teams. Эта конфигурация позволяет использовать ключ с любым приложением Teams, отправленным в качестве пользовательского приложения, и пользовательскими приложениями, созданными для вашей организации (бизнес-приложениями), для создания идентификаторов после их отправки. На этом этапе у вас не будет идентификатора приложения.

Безопасность ключа по-прежнему поддерживается с помощью домашнего клиента и базового URL-адреса. Когда вы будете готовы к выпуску приложения в мире, необходимо изменить параметр идентификатора приложения Teams на Существующее приложение Teams и ввести идентификатор приложения Teams. Наконец, отправьте манифест приложения в Центр партнеров для включения в Магазин Teams. Регистрация ключа API теперь привязана к конкретному приложению Teams и не может использоваться с другими пользователями.

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

Проверка подлинности с помощью ключа API

Регистрация ключа API

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

Лучшие методики

См. также

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