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

Совет

Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.

Единый вход (SSO) в Microsoft Entra позволяет пользователям проходить проверку подлинности с помощью существующих учетных данных Microsoft Entra ID. Эта интеграция упрощает управление доступом и обеспечивает безопасное подключение к серверам или API (Model Context Protocol) без необходимости использования дополнительных учетных данных. Ваш MCP-сервер или API должен использовать Entra ID для управления доступом.

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

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

Шаг 1. Зарегистрируйте приложение Entra для защиты сервера MCP

Ваш MCP-сервер или API должен быть защищен регистрацией приложения Entra. Если у вас его еще нет, зарегистрируйте приложение в Центре администрирования Microsoft Entra. Обратите внимание на идентификатор клиента приложения — укажите его при создании конфигурации проверки подлинности на шаге 2.

Шаг 2. Создайте конфигурацию проверки подлинности единого входа Entra

Проверка подлинности единого входа Entra основана на конфигурации проверки подлинности (конфигурации проверки подлинности) — записи, хранящейся в хранилище токенов Microsoft Enterprise, которую Microsoft 365 Copilot использует для получения маркеров для подключаемого модуля MCP. Начните с WIQD для поддерживаемого проекта pro-code. В качестве альтернативы остаются доступны процедуры для инструментов "Набор средств", "Навыки разработчика" и "Портал для разработчиков" в Teams.

Независимо от того, как вы ее создаете, конфигурация проверки подлинности имеет идентификатор конфигурации проверки подлинности и URI идентификатора приложения. URI идентификатора приложения используется нашагах 3 и 4.

Важно

Независимо от способа создания конфигурации проверки подлинности необходимо выполнить шаги 3 и 4.

Для действия MCP используйте wiqd agent add action с --mcp-server-urlпомощью , --mcp-auth-type entra-ssoи --mcp-client-id установите идентификатор клиента приложения Entra из шага 1. Для действия OpenAPI используйте --openapi-auth-identity-provider microsoft-entra и --openapi-auth-client-id. Другие необходимые параметры действий см. в руководстве по командам действий WIQD .

Для существующего манифеста подключаемого модуля используйте wiqd agent add auth с --plugin-manifest, --auth-name, и --auth-type microsoft-entra. Укажите параметры поставщика удостоверений, задокументированные для этой команды, включая --oauth-client-id. Завершите рабочий процесс подготовки проекта, получите URI идентификатора приложения конфигурации проверки подлинности и перейдите к шагам 3 и 4.

Использование набора средств агентов Microsoft 365

При создании агента с помощью подключаемого модуля MCP в наборе средств Microsoft 365 Agents этот набор запрашивает тип проверки подлинности при добавлении подключаемого модуля сервера MCP. Выберите единый вход Microsoft Entra и укажите идентификатор клиента приложения Entra из шага 1. Agents Toolkit создает конфигурацию проверки подлинности в хранилище маркеров Enterprise, создает идентификатор конфигурации проверки подлинности и автоматически обновляет объект проверки подлинности во время выполнения в манифесте подключаемого модуля.

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

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

Совет

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

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

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

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

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

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

    • Регистрационное имя: Понятное имя для вашей регистрации.
    • Базовый URL-адрес: базовый URL-адрес вашего API. Это значение должно соответствовать URL-адресу в url свойстве объекта спецификации сервера MCP в манифесте плагинов для плагинов на основе MCP или записи в массивеservers в вашем документе OpenAPI для плагинов API.
    • Ограничение использования по организациям: выберите, какая организация Microsoft 365 имеет доступ к вашему приложению для доступа к конечным точкам API.
    • Ограничение использования по приложениям: выберите любое приложение Teams , если вы не знаете окончательный идентификатор приложения. После публикации приложения привяжите его к опубликованному идентификатору приложения.
    • Идентификатор клиента: идентификатор клиента приложения, зарегистрированного в Entra.
    • Область: разрешения, которые подключаемый модуль запрашивает у Entra. Как и в случае с OAuth 2.0, используйте значения областей, необходимые для приложения и API Entra.
  4. Нажмите кнопку Сохранить.

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

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

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

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

Шаг 3. Обновите регистрацию приложения Entra

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

  1. Откройте Центр администрирования Microsoft Entra. Обновите регистрацию приложения Entra, которое защищает ваш MCP-сервер или API, с помощью URI идентификатора приложения из регистрации единого входа. Если у вас есть существующий URI идентификатора приложения, сопоставленный с регистрацией приложения, с помощью редактора манифестов добавьте еще один URI в раздел identifierUris .

    "identifierUris": [
      "<<URI1>>",
      "<<URI2>>"
    ]
    

    Примечание

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

  2. В разделе "Управление" выберите "Проверка подлинности". Добавление https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect к URI перенаправления на веб-платформе .

  3. Выберите Предоставление доступа к API в разделе Управление. Выберите Добавление клиентского приложения и добавьте идентификатор клиента хранилища маркеров Microsoft Enterprise, ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b.

Шаг 4. Добавление новой аудитории токенов в API

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

Совет

Если ваш MCP-сервер или API использует поток от имени пользователя для получения доступа к другому веб-API, который требует от пользователя предоставления согласия, возвратите ошибку 401 Unauthorized , чтобы агент предложил пользователю войти в систему, чтобы предоставить согласие.