Настройка проверки подлинности для средств протокола контекста модели (MCP)

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

В этой статье вы:

Необходимые условия

Прежде чем начать, вам потребуется:

• Доступ к порталу Foundry и проекту. Если у вас нет проекта, см. статью "Создание проектов" в Foundry.
• Разрешения для создания подключений проекта и настройки агентов. Дополнительные сведения см. в разделе "Управление доступом на основе ролей" на портале Foundry.
• URL-адрес конечной точки удаленного сервера MCP, к которому требуется подключиться.
• Учетные данные выбранного метода проверки подлинности:
  • Проверка подлинности на основе ключей: ключ API, личный маркер доступа (PAT) или другой маркер.
  • Microsoft Entra аутентификация: назначение ролей для идентификации агента или управляемой идентификации проекта в основной службе.
  • Сквозная идентификация OAuth: управляемая конфигурация OAuth или регистрация приложения OAuth (пользовательское OAuth).

Выбор метода проверки подлинности

Как правило, существуют два сценария проверки подлинности:

• Общая проверка подлинности. Каждый пользователь агента использует то же удостоверение для проверки подлинности на сервере MCP. Контекст пользователя не сохраняется.
• Индивидуальная проверка подлинности: каждый пользователь аутентифицируется с использованием своей учетной записи, чтобы его пользовательский контекст сохранялся.

Чтобы выбрать метод, используйте следующее руководство.

Поддерживаемые методы проверки подлинности

Проверка подлинности на основе ключей

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

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

При подключении сервера MCP к агенту на портале Foundry, система автоматически создаёт для вас подключение к проекту. Укажите имя учетных данных и значение учетных данных. Например, если вы подключаетесь к серверу MCP GitHub, можно указать следующее:

• Имя учетных данных: Authorization
• Значение учетных данных: Bearer <your-personal-access-token>

Когда агент вызывает сервер MCP, служба агента извлекает учетные данные из подключения к проекту и передает их серверу MCP.

Для обеспечения безопасности:

• Используйте учетные данные с минимальными привилегиями, если это возможно.
• Регулярно поворачивайте маркеры.
• Ограничение доступа к проектам, содержащим общие секреты.

аутентификация Microsoft Entra

Используйте проверку подлинности Microsoft Entra, если сервер MCP (и ее базовая служба) поддерживает маркеры Microsoft Entra. Этот метод устраняет необходимость управления секретами и обеспечивает автоматическое обновление токенов.

Использование проверки подлинности удостоверения агента

Используйте удостоверение агента, если требуется проверка подлинности для определенного агента. Этот подход идеально подходит, если у вас несколько агентов, которым требуется разные уровни доступа к одному и тому же серверу MCP.

Используйте удостоверение агента для проверки подлинности с серверами MCP, поддерживающими проверку подлинности удостоверений агента. Если вы создаете агент с помощью Службы агентов, вы автоматически назначаете ему идентификатор агента.

Перед публикацией все агенты в проекте Foundry используют одно и то же удостоверение агента. После публикации агента агент получает уникальное удостоверение агента.

Убедитесь, что удостоверение агента имеет необходимые назначения ролей в базовой службе, которая управляет сервером MCP.

Когда агент вызывает сервер MCP, служба агента использует доступное удостоверение агента для запроса токена авторизации и передает его серверу MCP.

Использование аутентификации с управляемым удостоверением проекта

Используйте управляемое удостоверение проекта, если требуется, чтобы все агенты в проекте использовали одинаковый уровень доступа или когда серверу MCP требуется управляемое удостоверение, а не удостоверение агента.

Используйте управляемое удостоверение проекта Foundry для проверки подлинности с серверами MCP, поддерживающими проверку подлинности управляемых удостоверений.

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

Когда агент вызывает сервер MCP, Служба агента использует идентификатор проекта для запроса маркера авторизации и передает его серверу MCP.

OAuth сквозная идентификация

Сквозная идентификация OAuth доступна для аутентификации на серверах MCP от Microsoft и других компаний, а также на поддерживающих сервисах, соответствующих OAuth, включая Microsoft Entra.

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

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

Служба агента поддерживает два варианта OAuth: управляемый OAuth и настраиваемый OAuth.

• С помощью управляемого приложения OAuth Microsoft или издателя сервера MCP управляет приложением OAuth.
• С помощью настраиваемого OAuth вы приведете собственную регистрацию приложения OAuth.

При настройке пользовательского OAuth укажите следующие сведения:

• Идентификатор клиента: обязательный
• Секрет клиента: необязательный (зависит от приложения OAuth)
• URL-адрес проверки подлинности: обязательный
• URL для обновления: обязательный (если у вас нет отдельного URL для обновления, вместо него можно использовать URL токена).
• URL-адрес токена: обязательный
• Области действия: необязательны (добавьте offline_access, чтобы включить автоматическое обновление токена). При указании нескольких областей разделяйте их одним пробелом, а не запятыми. Это следует спецификации OAuth 2.0.

Поток с использованием сквозной аутентификации OAuth

Область применения OAuth определяется именем инструмента (подключения) для каждого проекта Foundry. Каждому новому пользователю, использующим новое средство (подключение) в проекте Foundry, предлагается предоставить согласие.

• Когда пользователь впервые пытается использовать новое средство в проекте Foundry, выходные данные ответа предоставляют ссылку согласия.response.output_item Ссылку на согласие можно найти в типе oauth_consent_request элемента, в разделе consent_link. Представьте эту ссылку согласия пользователю.

  "type":"response.output_item.done",
  "sequence_number":7,
  "output_index":1,
  "item":{
      "type":"oauth_consent_request",
      "id":"oauthreq_10b0f026610e2b76006981547b53d48190840179e52f39a0aa",
      "created_by":{},
      "consent_link":"https://logic-swedencentral-001.consent.azure-apihub.net/login?data=xxxx"
  }
  

  См. пример

• Пользователю предлагается войти и предоставить согласие после проверки необходимого доступа. После успешного предоставления согласия пользователь видит диалоговое окно, как показано в этом примере:

• После закрытия диалогового окна необходимо отправить другой ответ с идентификатором предыдущего ответа.

  # Requires: azure-ai-projects >= 2.0.0
  from azure.ai.projects import AIProjectClient
  from azure.identity import DefaultAzureCredential
  
  # Submit another response after user consent
  response = client.responses.create(
       previous_response_id="YOUR_PREVIOUS_RESPONSE_ID",
       input=user_input,
       extra_body={
           "agent_reference": {"name": agent.name, "type": "agent_reference"},
           "tool_choice": "required",
           "stream": True
       },
  )
  

После входа пользователя и предоставления согласия один раз они не должны давать согласие в будущем.

Используйте собственную регистрацию приложения Microsoft Entra

Чтобы использовать проброс идентификации с сервисами Microsoft, предоставьте свою собственную регистрацию приложения Microsoft Entra. Используя собственную регистрацию приложения Microsoft Entra, вы управляете тем, какие разрешения предоставляете.

Следующие действия используют сервер MCP агента 365 в качестве примера:

1. Следуйте инструкциям по регистрации app, чтобы создать приложение Microsoft Entra и получить идентификатор клиента и секрет клиента.

2. Предоставьте разрешения с определенным объемом приложению Microsoft Entra.

   Для серверов MCP агента 365 перейдите к разделу "Управление>разрешениями API " и выполните поиск средств агента 365. Если не удается его найти, выполните поиск ea9ffc3e-8a23-4a7d-836d-234d7c7565c1. Назначьте необходимые разрешения и предоставьте согласие администратора для вашего клиента.

   Ниже приведены разрешения для каждого сервера MCP:

   • Microsoft Outlook почтовый сервер MCP (сервер Frontier): McpServers.Mail.All
   • сервер MCP календаря Microsoft Outlook Frontier: McpServers.Calendar.All
   • Microsoft Teams MCP Server (Frontier): McpServers.Teams.All
   • Microsoft 365 сервер профиля пользователя MCP (Frontier): McpServers.Me.All
   • Microsoft SharePoint и сервер MCP OneDrive (Frontier): McpServers.OneDriveSharepoint.All
   • Microsoft SharePoint Списки сервера MCP (Граница): McpServers.SharepointLists.All
   • сервер Microsoft Word MCP (Frontier): McpServers.Word.All
   • Microsoft 365 Copilot (поиск) MCP-сервер (граница): McpServers.CopilotMCP.All
   • Microsoft 365 Admin Center MCP Server (Frontier): McpServers.M365Admin.All
   • Microsoft Dataverse MCP Server (Frontier): McpServers.Dataverse.All

3. Вернитесь на портал Foundry и настройте сервер MCP. Подключите средство, перейдите к custom и выберите MCP. Укажите имя и конечную точку сервера MCP, а затем выберите OAuth Identity Passthrough:

   • Идентификатор клиента и секрет клиента
   • URL-адрес токена: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • URL-адрес проверки подлинности: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
   • URL-адрес обновления: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • области действия: ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/{permission above} offline_access (разделённые пробелами, согласно спецификации OAuth 2.0)

4. После завершения настройки вы получите URL-адрес перенаправления. Добавьте его в приложение Microsoft Entra.

Доступ без проверки подлинности

Используйте неуверенный доступ только в том случае, если сервер MCP не требует проверки подлинности. Этот метод подходит для общедоступных серверов MCP, которые предоставляют открытый доступ к своим средствам или для частных серверов MCP в виртуальной сети, которые используют изоляцию на уровне сети вместо явной проверки подлинности.

Настройка проверки подлинности для сервера MCP

1. Определите удаленный сервер MCP, к которому вы хотите подключиться.

2. Создайте или выберите подключение проекта, включающее конечную точку сервера MCP, тип проверки подлинности и все необходимые учетные данные.

   При подключении сервера MCP на портале Foundry портал создает подключение к проекту.

3. Создайте или обновите агента с помощью инструмента mcp, используя следующую информацию:

   1. server_url: URL-адрес сервера MCP. Например, https://api.githubcopilot.com/mcp/.
   2. server_label: уникальный идентификатор этого сервера MCP для агента. Например, github.
   3. require_approval: при необходимости определите, требуется ли утверждение. Поддерживаемые значения:
      • always: разработчику необходимо предоставить утверждение для каждого вызова. Если вы не предоставляете значение, это значение по умолчанию.
      • never: утверждение не требуется.
      • {"never":[<tool_name_1>, <tool_name_2>]}: вы предоставляете список инструментов, которые не требуют утверждения.
      • {"always":[<tool_name_1>, <tool_name_2>]}: вы предоставляете список инструментов, требующих утверждения.
   4. project_connection_id: имя подключения, которое хранит конечную точку сервера MCP, выбор проверки подлинности и соответствующие сведения. Если вы предоставляете разные конечные точки в соединении по сравнению с server_url, то используется конечная точка в соединении.

4. Запустите агент.

5. Если модель пытается вызвать средство на сервере MCP, требующее одобрения, или если пользователю необходимо войти в систему для передачи удостоверения OAuth, просмотрите данные ответа:

   • Ссылка на согласие: oauth_consent_request
   • Запрос на утверждение: mcp_approval_request

   После входа пользователя или утверждения вызова отправьте еще один ответ, чтобы продолжить.

Проверить

После настройки проверки подлинности убедитесь, что подключение работает правильно:

1. Инициируйте вызов инструмента MCP из агента, отправив запрос, который заставляет агента использовать один из инструментов сервера MCP.
2. Подтвердите успешное завершение вызова инструмента. Вы должны увидеть результаты работы средства в ответе агента без ошибок аутентификации.
3. Если вы используете сквозную передачу удостоверения личности с использованием OAuth:
   • Подтвердите, что новый пользователь получает ссылку на согласие (oauth_consent_request в ответе).
   • После согласия пользователя подтвердите, что последующие вызовы инструментов завершатся успешно, не запрашивая согласие еще раз.
   • Проверьте правильность работы потока согласия для каждого пользователя с другим пользователем.

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

Размещение локального сервера MCP

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

Среда выполнения службы агента принимает только удаленную конечную точку сервера MCP. Если вы хотите добавить средства с локального сервера MCP, необходимо самостоятельно разместить его на Контейнеры приложений Azure или Функции Azure для получения удаленной конечной точки сервера MCP.

Удаленная конечная точка может быть общедоступной конечной точкой или частной конечной точкой в виртуальной сети. Для частных серверов MCP разверните приложение-контейнер в выделенной подсети MCP с только внутренним входом, делегированной Microsoft.App/environments. Чтобы приступить к работе, используйте шаблон 19-hybrid-private-resources-agent-setup . Дополнительные сведения о поддержке средств в изолированных от сети средах см. в разделе "Средства агента" с сетевой изоляцией.

При попытке размещения локальных серверов MCP в облаке следует учитывать следующие моменты:

Дальнейшие действия

• Подключение к серверам протокола контекста модели
• Настройка частной сети для службы агента Foundry
• Понятия идентификации агента в Foundry
• Управление доступом на основе ролей на портале Foundry
• Добавление подключения в Foundry