Настройка проверки подлинности для подключаемых модулей API в агентах

Статья
01/10/2025

Вы можете настроить проверку подлинности для подключаемых модулей API в агентах, работающих в Microsoft 365 Copilot, с помощью любой из четырех поддерживаемых схем проверки подлинности, чтобы легко подключиться к серверным API:

Поток кода авторизации OAuth 2.0
проверка подлинности Microsoft Entra ID единого входа
Проверка подлинности с помощью ключа API
Без проверки подлинности (анонимная)

Поток кода авторизации OAuth 2.0

Подключаемый модуль может получить доступ к API с помощью маркера носителя, полученного с помощью потока кода авторизации OAuth 2.0, с необязательной поддержкой ключа proof для Code Exchange (PKCE).

Прежде чем начать, необходимо зарегистрироваться у поставщика OAuth 2.0, чтобы получить идентификатор и секрет клиента. Если поставщик OAuth требует указать разрешенные URI перенаправления во время регистрации приложения, обязательно включите https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect в список.

Важно!

Поддержка подключаемых модулей API для OAuth 2.0 имеет следующие ограничения.

Подключаемые модули API поддерживают только поток кода авторизации для OAuth 2.0.
Серверы OAuth 2.0, возвращающие 307 Temporary Redirect коды состояния HTTP из конечной точки маркера, не поддерживаются.

Эту схему можно определить в свойстве securitySchemes документа OpenAPI. Дополнительные сведения см. в разделе OAuth 2.0.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

Чтобы включить проверку подлинности OAuth 2.0, необходимо зарегистрировать клиент OAuth на портале разработчика Teams. Вы можете зарегистрировать клиент OAuth с помощью Набора средств Teams в Visual Studio Code или вручную зарегистрируясь на портале разработчика Teams.

Регистрация клиента OAuth с помощью Набора средств Teams

Teams Toolkit регистрирует клиент OAuth и обновляет пакет приложения при создании агента с подключаемым модулем API из существующего документа OpenAPI. Свойство должно быть определено в документе securitySchemes OpenAPI.

Если поставщик OAuth поддерживает PKCE, раскомментируйте следующую строку кода в teamsapp.yml в проекте агента перед подготовкой агента.

# isPKCEEnabled: true

Регистрация клиента OAuth на портале разработчика Teams

Откройте портал разработчика Teams. Выберите Сервис ->Регистрация клиента OAuth.
Если у вас нет существующих регистраций, выберите Зарегистрировать клиента. Если у вас есть существующие регистрации, выберите Создать регистрацию клиента OAuth.
Заполните следующие поля.
- Имя регистрации: понятное имя для регистрации.
- Базовый URL-адрес: базовый URL-адрес API. Это значение должно соответствовать записи в массивеservers в документе OpenAPI.
- Идентификатор клиента: идентификатор клиента или идентификатор приложения, выданный поставщиком OAuth 2.0.
- Секрет клиента: секрет клиента, выданный поставщиком OAuth 2.0.
- Конечная точка авторизации: URL-адрес поставщика OAuth 2.0, который приложения используют для запроса кода авторизации.
- Конечная точка маркера: URL-адрес поставщика OAuth 2.0, который приложения используют для активации кода для маркера доступа.
- Конечная точка обновления: URL-адрес поставщика OAuth 2.0, который приложения используют для обновления маркера доступа.
- Область: область разрешений, определенный API, который разрешает доступ.
- Включить ключ проверки подлинности для Code Exchange (PKCE): включите этот параметр, если поставщик OAuth поддерживает PKCE.
Выберите Сохранить.
После завершения регистрации создается идентификатор регистрации клиента OAuth.

Добавление идентификатора регистрации клиента в манифест подключаемого модуля

Чтобы использовать проверку подлинности OAuth 2.0 для подключаемого модуля API, задайте type для свойства объекта OAuthPluginVaultпроверки подлинности среды выполнения значение , а для — reference_id идентификатор регистрации клиента на портале разработчика Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth registration ID"
},

проверка подлинности единого входа Microsoft Entra ID

Microsoft Entra ID проверка подлинности единого входа обеспечивает простую интеграцию единого входа, позволяя пользователям проходить проверку подлинности с помощью имеющихся учетных данных Microsoft Entra ID. Такая интеграция упрощает управление доступом и обеспечивает безопасные подключения к API без дополнительных учетных данных. Api должен использовать Microsoft Entra ID для управления доступом.

Регистрация клиента единого входа на портале разработчика Teams

Откройте портал разработчика Teams. Выберите Сервис ->Microsoft Entra регистрация идентификатора клиента единого входа.
Если у вас нет регистраций, выберите Зарегистрировать идентификатор клиента. Если у вас есть существующие регистрации, выберите Новая регистрация клиента.
Заполните следующие поля.
- Имя регистрации: понятное имя для регистрации.
- Базовый URL-адрес: базовый URL-адрес API. Это значение должно соответствовать записи в массивеservers в документе OpenAPI.
- Ограничение использования по организациям. Выберите, какая организация Microsoft 365 имеет доступ к вашему приложению для доступа к конечным точкам API.
- Ограничение использования по приложениям. Выберите Любое приложение Teams , если вы не знаете свой окончательный идентификатор приложения. После публикации приложения привяжите эту регистрацию к опубликованному идентификатору приложения.
- Идентификатор клиента: идентификатор клиента приложения, зарегистрированного в Microsoft Entra.
Выберите Сохранить.
После завершения регистрации создается идентификатор регистрации Microsoft Entra единого входа и универсальный код ресурса (URI) идентификатора приложения.

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

Откройте Центр администрирования Microsoft Entra. Обновите Microsoft Entra регистрации приложения, который защищает API, с помощью URI идентификатора приложения, созданного порталом разработчика Teams. Если у вас есть существующий универсальный код ресурса (URI) идентификатора приложения, сопоставленный с регистрацией приложения, можно использовать редактор манифеста, чтобы добавить еще один универсальный код ресурса (URI) в раздел identifierUris .
```
"identifierUris": [
  "<<URI1>>"
  "<<URI2>>"
]
```
Примечание.

Добавление нескольких URI не поддерживается в пользовательском интерфейсе Центр администрирования Microsoft Entra. Пользовательский интерфейс отображает только первый URI в списке. Добавление нескольких URI не влияет на существующие URI и области, даже если они отображаются по-разному в пользовательском интерфейсе.
Выберите пункт Проверка подлинности в разделе Управление. Добавьте https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect в URI перенаправления на веб-платформе .
Выберите пункт Предоставление API в разделе Управление. Выберите Добавить клиентское приложение и добавьте идентификатор клиента корпоративного хранилища маркеров Майкрософт. ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b

Добавление идентификатора регистрации единого входа в манифест подключаемого модуля

type Задайте для свойства объекта OAuthPluginVaultпроверки подлинности среды выполнения значение , а для — reference_idидентификатор регистрации Microsoft Entra единого входа на портале разработчика Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

Добавление новой аудитории маркеров в API

Обновите API, чтобы разрешить новый URI идентификатора в качестве аудитории маркеров. Если API проверяет идентификатор клиентского приложения, убедитесь, что идентификатор клиента хранилища корпоративных токенов Майкрософт (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) добавлен в качестве разрешенного клиентского приложения.

Совет

Если ваш API использует поток on-behalf-of для получения доступа к другому веб-API, требующего от пользователя предоставления согласия, верните ошибку 401 Unauthorized , из-за чего агент запросит пользователя на вход для предоставления согласия.

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

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

В качестве маркера носителя в заголовке Authorization
Как значение в пользовательском заголовке
Как параметр запроса

Добавление ключа API в документ OpenAPI

Microsoft 365 Copilot определяет способ отправки ключа API на securitySchemes основе записи в документе OpenAPI.

Токен носителя

Если API принимает ключ API в качестве маркера носителя, включите проверку подлинности bearer в документе OpenAPI. Дополнительные сведения см. в разделе Проверка подлинности носителя.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Пользовательский заголовок

Если API принимает ключ API в пользовательском заголовке, включите проверку подлинности ключа API в документе OpenAPI, указав in свойству значение header , а свойству name — имя заголовка. Дополнительные сведения см. в разделе Ключи API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Параметр запроса

Если API принимает ключ API в параметре запроса, включите проверку подлинности ключа API в документе OpenAPI, in указав свойству значение query , а свойству name — имя параметра запроса. Дополнительные сведения см. в разделе Ключи API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

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

Чтобы включить проверку подлинности по ключу API, необходимо зарегистрировать ключ API на портале разработчика Teams. Ключ API можно зарегистрировать в Наборе средств Teams в Visual Studio Code или вручную на портале разработчика Teams.

Регистрация ключа API с помощью набора средств Teams

Teams Toolkit регистрирует ключ API и обновляет пакет приложения при создании агента с подключаемым модулем API из существующего документа OpenAPI. Свойство должно быть определено в документе securitySchemes OpenAPI.

Примечание.

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

Регистрация ключа API на портале разработчика Teams

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

Добавление идентификатора регистрации ключа API в манифест подключаемого модуля

В файле манифеста подключаемого модуля задайте type для свойства объекта ApiKeyPluginVaultпроверки подлинности среды выполнения значение , а для — reference_id идентификатор регистрации ключа API на портале разработчика Teams.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

Без проверки подлинности (анонимная)

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

"auth": {
  "type": "None"
},

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