Настройка проверки подлинности OAuth 2.0

Подключаемый модуль может получить доступ к серверу или API протокола контекста модели (MCP) с помощью маркера носителя, полученного в ходе набора кода авторизации OAuth 2.0, при этом поддержка ключа доказательства для обмена кодом (PKCE) включена по умолчанию. В этом потоке Microsoft 365 Copilot открывает интерфейс входа, поставщик OAuth возвращает ответ авторизации Microsoft Teams, а Teams обменивает код авторизации на токены.

В этом руководстве по умолчанию используются подключаемые модули MCP. Те же шаги применяются к плагинам API, созданным на основе документа OpenAPI, если не указано иное.

Настройте проверку подлинности OAuth 2.0 в три этапа: зарегистрируйте клиента OAuth у поставщика удостоверений, настройте URI перенаправления и создайте конфигурацию OAuth 2.0.

Шаг 1. Регистрация клиента OAuth у поставщика удостоверений

Зарегистрируйте приложение у поставщика OAuth 2.0 (поставщика удостоверений), чтобы получить идентификатор клиента , а для конфиденциального (веб-) клиента — секрет клиента. Укажите эти значения при создании конфигурации OAuth 2.0 на шаге 3.

Для MCP-сервера, требующего авторизации, установите type для свойства объекта проверки подлинности среды выполнения значение OAuthPluginVault. None и ApiKeyPluginVault не применяются к серверу MCP, требующему авторизации. В манифесте хранится только идентификатор конфигурации проверки подлинности — в него не записывается идентификатор клиента, секрет клиента или маркер. Чтобы зарегистрировать клиента динамически, а не статически, сохраните type как OAuthPluginVault и создайте конфигурацию проверки подлинности с помощью динамической регистрации клиента (DCR), что недоступно для сервера, защищенного Microsoft Entra ID.

Примечание.

Эти значения применяются к манифесту подключаемого модуля. Если вместо этого вы зарегистрируете свой сервер MCP в качестве соединителя агента в agentConnectors узле манифеста приложения Microsoft 365, используйте OAuthPluginVault или DynamicClientRegistration там. Не используйте AzureKeyVault: он существует только в схеме devPreview , поэтому пакет, использующий нумерованную версию схемы, не проходит проверку. Дополнительные сведения см. в статье Регистрация серверов MCP в качестве соединителей агентов.

Шаг 2. Настройка URI перенаправления

Добавьте следующий URI перенаправления (также называемый URL-адресом обратного вызова авторизации) к регистрации поставщика OAuth:

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

Это URL-адрес, с которого ваш поставщик OAuth отправляет ответ авторизации после входа пользователя. Teams получает ответ по этому URL-адресу обратного вызова и обменивает код авторизации на маркеры. Если вы не зарегистрируете этот URI перенаправления у своего поставщика, вход в систему завершится сбоем. URI перенаправления одинаков для всех плагинов и поставщиков — вы не настраиваете его для каждого приложения.

Шаг 3. Создание конфигурации проверки подлинности OAuth 2.0

Проверка подлинности OAuth 2.0 основана на конфигурации проверки подлинности (конфигурации проверки подлинности) — записи, хранящейся в хранилище токенов Microsoft Enterprise, которую Microsoft 365 Copilot использует для получения и обновления маркеров для подключаемого модуля MCP. Конфигурацию проверки подлинности можно создать тремя способами. Рекомендуемые подходы - набор средств агентов Microsoft 365 и навык разработчика декларативного агента - создание конфигурации проверки подлинности и автоматическое обновление манифеста подключаемого модуля. Затем вы можете использовать портал разработчика Teams для управления конфигурацией проверки подлинности и ее уточнения.

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

При создании агента с подключаемым модулем MCP (если сервер требует проверки подлинности) или создании подключаемого модуля API из существующего документа OpenAPI в наборе инструментов агентов Microsoft 365 этот набор запрашивает идентификатор клиента OAuth, секрет клиента и области. Agents Toolkit извлекает конечные точки авторизации, маркера и обновления из известной конечной точки сервера MCP (или из документа OpenAPI для подключаемых модулей API), создает конфигурацию проверки подлинности в хранилище маркеров Enterprise и автоматически обновляет объект проверки подлинности во время выполнения в манифесте подключаемого модуля.

Примечание.

Для подключаемых модулей API необходимо определить свойство securitySchemes в документе OpenAPI, чтобы Agents Toolkit мог прочитать сведения об OAuth. Дополнительные сведения см. в разделе OAuth 2.0.

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

PKCE включен по умолчанию, так как многие организации блокируют секреты клиентов. Установите isPKCEEnabled значение false "В m365agents.yml" в проекте агента перед подготовкой агента только в том случае, если ваш поставщик OAuth не поддерживает PKCE.

isPKCEEnabled: false

Чтобы полностью избежать секретов клиента, зарегистрируйте публичный клиент у своего провайдера - одностраничную платформу приложений, а не веб-платформу - и позвольте PKCE обеспечить обмен кодом.

Использование навыка разработчика декларативного агента

Навык разработчика декларативных агентов (declarative-agent-developer) — это навык агента в Microsoft Work IQ , который объединяет знания, необходимые для создания декларативных агентов. Вместо выполнения команд или редактирования манифестов вы описываете то, что вы хотите, Copilot или GitHub CLI на естественном языке, и навык формирует декларативный агент, добавляет подключаемый модуль MCP и обрабатывает настройку проверки подлинности за вас. Навык поддерживает только плагины MCP. В OAuth 2.0 он поддерживает как статическую регистрацию, так и динамическую регистрацию клиента (DCR): он создает конфигурацию проверки подлинности в хранилище маркеров Enterprise и обновляет манифест подключаемого модуля без ручных действий.

Совет

Видеоруководство по использованию навыка разработчика декларативного агента см. в разделе "Создание декларативных агентов с помощью навыка разработчика декларативного агента".

Использование портала разработчика Teams

Регистрация на портале разработчика Teams необязательна, если вы используете набор средств агентов или навык разработчика декларативного агента. Используйте его, если вы хотите создать конфигурацию проверки подлинности вручную или, что более распространено, для управления конфигурацией проверки подлинности, созданной набором средств агентов или уже созданным навыком. На портале вы можете ограничить конфигурацию проверки подлинности определенным приложением Teams или организацией Microsoft 365 и изменить другие свойства.

Регистрация клиента OAuth на портале разработчика Teams подключает конфигурацию подключаемого модуля агента к регистрации поставщика OAuth, выдающего маркеры для сервера MCP или API. Значения в этой регистрации должны соответствовать поставщику OAuth, манифесту подключаемого модуля и защищенной конечной точке API. Несовпадающие базовые URL-адреса, ограничения приложений или идентификаторы конфигурации проверки подлинности могут помешать пользователям войти в систему или заблокировать обмен токенами.

Предупреждение

Ограничьте регистрацию любым приложением Teams. Регистрация, ограниченная определенным приложением Teams, привязывается к этому идентификатору приложения Teams. Microsoft 365 Copilot не разрешает этот идентификатор при вызове сервера MCP, поэтому подготовка завершается успешно, а затем каждый вызов средства возвращает 404 ошибку.

  1. Откройте портал разработки Teams. Выберите Инструменты ->Регистрация клиента OAuth.

  2. Если у вас нет существующих регистраций, выберите Зарегистрировать клиента. Если у вас уже есть регистрации, выберите Новая регистрация клиента OAuth.

  3. Заполните следующие поля.

    • Регистрационное имя: Понятное имя для вашей регистрации.
    • Базовый URL-адрес: базовый URL-адрес вашего API. Это значение должно соответствовать URL-адресу в url свойстве объекта спецификации сервера MCP в манифесте плагинов для плагинов на основе MCP или записи в массивеservers в вашем документе OpenAPI для плагинов API.
    • Ограничение использования по организации: выберите, какие организации Microsoft 365 могут использовать эту регистрацию OAuth для доступа к конечным точкам API. Использовать "Моя организация" только для разработки или тестирования в одном клиенте. Используйте любую организацию Microsoft 365 , если подключаемый модуль должен работать с разными клиентами.
    • Ограничение использования по приложениям: выберите любое приложение Teams. Не привязывайте регистрацию к существующему идентификатору приложения Teams для сервера MCP. Если вместо этого подготовить конфигурацию проверки подлинности с помощью набора средств агентов Microsoft 365, эквивалентным параметром oauth/register в действии в m365agents.yml будет applicableToApps: AnyApp. Оставьте appId поле в этом действии, даже если AnyApp делает его инертным, так как драйвер подготовки проверяется appId безусловно, а его удаление нарушает подготовку.
    • Идентификатор клиента: идентификатор клиента или идентификатор приложения, выданный поставщиком OAuth 2.0.
    • Секрет клиента: секрет клиента, выданный поставщиком OAuth 2.0.
    • Конечная точка авторизации: URL-адрес поставщика OAuth 2.0, который приложения используют для запроса кода авторизации.
    • Конечная точка маркера: URL-адрес поставщика OAuth 2.0, который приложения используют для активации кода для маркера доступа.
    • Обновление конечной точки: URL-адрес поставщика OAuth 2.0, который приложения используют для обновления маркера доступа.
    • Область: разрешения, которые подключаемый модуль запрашивает у поставщика OAuth. Используйте значения областей, требуемые вашим поставщиком и API. Если ваш поставщик использует платформу удостоверений Майкрософт и вашему подключаемому модулю требуются маркеры обновления, включите offline_access его в любые делегированные области для API.
    • Включить ключ подтверждения для обмена кодом (PKCE): оставьте этот параметр включенным. Он включен по умолчанию; отключайте его, только если ваш поставщик OAuth не поддерживает PKCE.

  4. Выберите Сохранить.

  5. По завершении регистрации создается конфигурация проверки подлинности и создается идентификатор конфигурации проверки подлинности (в настоящее время он называется идентификатором регистрации клиента OAuth на портале разработки Teams).

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

При создании конфигурации проверки подлинности вручную на портале разработки Teams задайте type свойству объекта проверки подлинности среды выполнения значение OAuthPluginVault, а затем reference_id значение идентификатор конфигурации проверки подлинности. Набор средств агентов и навык разработчика декларативного агента делают это за вас.

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

Рекомендации по Microsoft Entra ID

При защите сервера MCP с помощью Microsoft Entra ID применяются три ограничения, которые невозможно обойти при использовании инструментов.

  • Динамическая регистрация клиентов недоступна. Microsoft Entra ID не публикует конечную точку регистрации RFC 7591, поэтому динамической регистрации клиентов не против чего регистрироваться. Зарегистрируйте клиент OAuth статически, выполнив действия, описанные в этой статье.
  • Узел agentConnectors не имеет типа авторизации Microsoft Entra. В отличие от composeExtensions, agentConnectors узел в манифесте приложения Microsoft 365 не microsoftEntra имеет типа авторизации. Серверу MCP, защищенному Microsoft Entra ID, всегда требуется приложение, которое вы регистрируете в Microsoft Entra ID, а также конфигурация проверки подлинности OAuth, даже если сервер работает со сторонним API Майкрософт.
  • Согласие области не проверяется при подготовке. Подготовка не проверка, можно ли дать согласие на запрашиваемый область. область, для которого нельзя было дать согласие с условиями, а затем он завершается сбоем с утверждением администратора. При этом приложение ресурсов может быть невидимым как для вас, так и для администратора клиента. Перед началом подготовки убедитесь, что администратор согласился с область.

Управление конфигурацией проверки подлинности

Действие oauth/register в m365agents.yml только создает конфигурацию проверки подлинности или пропускает ее создание — оно никогда не перезаписывает существующую запись.

  • Если configurationId уже есть значение, действие ничего не делает.
  • Если configurationId указывает на удаленную регистрацию, действие предупреждает вас и ничего не делает.
  • Чтобы изменить значения в существующей регистрации, используйте oauth/update действие.
  • Чтобы удалить регистрацию, используйте портал разработки Teams. Это единственное место, где вы можете удалить ключ.

Выйти

Примечание.

Пользователи могут выйти из агента в разделе Chat параметров>агентов в Microsoft 365 Copilot. Это действие очищает сохраненный маркер OAuth.

Связанные материалы

  • Last updated on