Новости

Как подключить OAuth MCP-сервер к Amazon Bedrock AgentCore Gateway через поток Authorization Code

Искусственный интеллект

Amazon Bedrock AgentCore Gateway предоставляет централизованный слой для управления тем, как ИИ-агенты подключаются к инструментам и MCP-серверам в вашей организации. Он объединяет аутентификацию, наблюдаемость и enforcement политик в одной конечной точке, устраняя необходимость настраивать и защищать каждое подключение к MCP-серверу по отдельности.

В этой публикации мы покажем, как настроить AgentCore Gateway для подключения к защищенному OAuth MCP-серверу с использованием потока Authorization Code.

Использование AgentCore Gateway как конечной точки MCP-сервера

По мере масштабирования развертываний ИИ-агентов в организациях число MCP-серверов, на которые опирается каждая команда, быстро растет. Разработчики используют Amazon Bedrock AgentCore Gateway как единую конечную точку для доступа к нескольким MCP-серверам. Вместо настройки каждого MCP-сервера отдельно для каждой IDE команды указывают на один URL Gateway, чтобы обеспечить стабильный доступ ко всему набору MCP-инструментов в разных инструментах.

Этот подход быстро набирает популярность по мере того, как команды отходят от собственных MCP-серверов и переходят на production-grade сторонние серверы, например от AWS, GitHub, Salesforce и Databricks. Многие из этих MCP-серверов защищены через федерацию своим основным поставщиком идентификации, а другие — собственными серверами авторизации. По мере роста числа MCP-серверов в организации управление подключениями, аутентификацией и маршрутизацией на уровне IDE становится неустойчивым. AgentCore Gateway централизует эту сложность, предоставляя командам единую управляющую плоскость для доступа к MCP, а разработчикам — бесшовный опыт.

Многие корпоративные MCP-серверы требуют авторизации OAuth 2.0, при которой агент должен аутентифицироваться от имени пользователя перед вызовом инструментов. AgentCore Gateway теперь поддерживает поток OAuth 2.0 Authorization Code через Amazon Bedrock AgentCore Identity. Благодаря этому ваши агенты могут безопасно получать доступ к защищенным MCP-серверам, не встраивая учетные данные в код приложения и не управляя жизненным циклом токенов вручную.

Ключевые термины

  • Пользователь AgentCore Gateway — конечный пользователь, который потребляет инструменты в Amazon Bedrock AgentCore Gateway через MCP-клиенты. Пользователи Gateway не управляют самим AgentCore Gateway. Они используют единый URL AgentCore Gateway для доступа к доступным им инструментам.
  • Администратор — пользователь, который управляет и сопровождает Amazon Bedrock AgentCore Gateway. Он отвечает за подключение MCP-серверов, инструментов или API к AgentCore Gateway, чтобы пользователи AgentCore Gateway могли ими пользоваться.
  • MCP-сервер — в этой публикации мы предполагаем, что MCP-сервер защищен потоком OAuth 2.0 Authorization Code, который требует взаимодействия с пользователем для завершения аутентификации. Это отличается от методов машинной аутентификации, таких как Client Credentials или Token Exchange, где вмешательство пользователя не требуется. Описанные здесь шаблоны применимы именно к MCP-серверам, которым нужна делегированная пользователем авторизация.

Как работает поток Authorization Code

Чтобы поддержать тип авторизации Authorization Code Grant, мы предлагаем два способа создания целевых ресурсов.

  1. Неявная синхронизация во время создания target для MCP-сервера

В этом варианте администратор завершает поток authorization code во время операций CreateGatewayTarget, UpdateGatewayTarget или SynchronizeGatewayTargets. Это позволяет AgentCore Gateway заранее обнаружить и кэшировать инструменты MCP-сервера.

  1. Предоставление схемы заранее при создании target для MCP-сервера

В этом варианте администраторы передают схему инструментов напрямую во время операций CreateGatewayTarget или UpdateGatewayTarget, а не позволяют AgentCore Gateway динамически получать их с MCP-сервера. AgentCore Gateway разбирает предоставленную схему и кэширует определения инструментов. Это избавляет администратора от необходимости завершать поток authorization code при создании или обновлении target. Это рекомендуемый подход, когда участие человека невозможно во время операций create/update. Этот способ полезен, когда вы не хотите раскрывать все инструменты, предоставляемые target MCP-сервера.

Примечание: поскольку в этом методе схемы инструментов предоставляются заранее, операция SynchronizeGatewayTargets не поддерживается. Вы можете переключать target между способом 1 и способом 2, обновляя конфигурацию target.

Это означает, что пользователи AgentCore Gateway могут вызывать list/tools без запроса на аутентификацию на сервере аутентификации MCP-сервера, поскольку они получают доступ к кэшированным инструментам. Поток authorization code запускается только тогда, когда пользователь Gateway вызывает инструмент на этом MCP-сервере. Это особенно полезно, когда к одному Gateway подключено несколько MCP-серверов. Пользователи могут просматривать полный каталог инструментов (кэшированные инструменты), не аутентифицируясь в каждом MCP-сервере, и завершать поток только для того сервера, инструмент которого они вызывают.

Привязка сессии к URL

Привязка сессии к URL проверяет, что пользователь, инициировавший запрос OAuth-авторизации, — это тот же пользователь, который дал согласие. Когда AgentCore Identity генерирует URL авторизации, он также возвращает session-URI. После того как пользователь завершает согласие, браузер перенаправляется обратно на callback URL вместе с session-URI. Затем приложение должно вызвать API CompleteResourceTokenAuth, передав и идентификатор пользователя, и session-URI. AgentCore Identity проверяет, что пользователь, начавший поток, и пользователь, завершивший согласие, совпадают, прежде чем обменять authorization code на access token. Это помогает избежать сценария, при котором пользователь случайно делится URL авторизации, а согласие завершает кто-то другой, в результате чего токены доступа получает не тот адресат. URL авторизации и session URI действительны только 10 минут, что дополнительно ограничивает окно для злоупотребления. Привязка сессии применяется во время создания target администратором (неявная синхронизация) и во время вызова инструментов.

Обзор решения

В этой публикации мы покажем, как подключить GitHub MCP server к Amazon Bedrock AgentCore Gateway, используя способ 1 (синхронизацию, инициируемую администратором, во время создания target) и способ 2 (предоставление схемы инструментов заранее во время создания target). Соответствующий код доступен в этом репозитории.

Предварительные требования

Вместе с этой публикацией необходимо выполнить следующие предварительные требования.

  1. Настройка GitHub OAuth Apps
    • Перейдите в https://github.com/settings/apps → New GitHub App
    • Заполните сведения:
      1. Имя GitHub App: AgentCore Gateway GitHub MCP
      2. Homepage URL (Полный URL сайта вашего GitHub App): Homepage URL отображается как кликабельная ссылка, когда пользователи видят ваш OAuth app, помогая им узнать больше о вашем приложении. Это помогает пользователям проверить легитимность приложения, запрашивающего доступ к их учетной записи GitHub.
      3. Authorization callback URL: Authorization callback URL (redirect URI) — это URL, на который GitHub перенаправляет пользователя после того, как он разрешит или отклонит ваш OAuth app. Пока укажем https://example.com/auth, позже мы вернемся и изменим это значение.
      4. Дополнительные настройки: ниже приведены рекомендуемые значения по умолчанию. Однако обязательно следуйте практикам безопасности, принятой в вашей организации.
        1. Expire user authorization tokens: Disable — если включить, AgentCore Identity сможет автоматически обновлять токены пользователя.
        2. Request user authorization (OAuth) during installation: Disable.
        3. Device Flow: Disable — позволяет выполнять авторизацию на устройствах без браузера (например, CLI-инструменты, smart TV, CI-среды).
        4. Webhook: Disable.
        5. User permissions: зависят от сценария использования, пока оставьте значения по умолчанию — они выдаются, когда пользователь проходит поток OAuth-авторизации. Запрашивайте только то, что действительно нужно: пользователи видят эти разрешения на экране согласия, а избыточные права снижают доверие.
    • Выберите Create GitHub App.
    • Обязательно запишите Client ID приложения, он отличается от App ID.
    • В общих настройках OAuth app выберите Generate a new client secret. Обязательно сохраните client secret, поскольку GitHub показывает его только один раз при создании.
  1. Разрешения IAM: вам нужны соответствующие разрешения IAM, чтобы запускать код из этой публикации. Ниже указаны минимально необходимые разрешения IAM.
  2. Репозиторий кода: сначала клонируйте GitHub-репозиторий, а затем откройте github-mcp-server.ipynb. Мы рекомендуем сначала следовать инструкциям в консоли из этой публикации, чтобы понять концепции, а затем перейти к разбору кода. 
    git clone https://github.com/awslabs/amazon-bedrock-agentcore-samples.git

cd 01-tutorials/02-AgentCore-gateway/05-mcp-server-as-a-target/03-authorization-code-flow
  3. Поставщик учетных данных GitHub: на этом шаге мы настроим Agentcore Identity Credential Provider. В консоли Amazon Bedrock AgentCore перейдите в AgentCore Identity и создайте OAuth client.
    1. Укажите имя OAuth Client, выберите встроенного поставщика GitHub и заполните client ID и client secret GitHub OAuth App.
    2. Скопируйте callback URL OAuth client в AgentCore Identity и обязательно вернитесь к созданному вами GitHub OAuth provider, чтобы обновить Authorization callback URL.

Неявная синхронизация во время создания target для MCP-сервера

В этом разделе мы объясним, как работает неявная синхронизация во время создания target для MCP-сервера. Убедитесь, что роль выполнения AgentCore Gateway имеет разрешения GetWorkloadAccessTokenForUserId и CompleteResourceTokenAuth. Сначала разберемся в потоке.

  1. Администратор вызывает CreateGatewayTarget, передавая endpoint MCP-сервера, AgentCore Identity Credential Provider и return URL. Это сообщает AgentCore Gateway, к какому MCP-серверу подключаться и какой поставщик учетных данных использовать для получения токенов OAuth 2.0. Этот же поток применяется и к операциям UpdateGatewayTarget и SynchronizeGatewayTargets.
  2. AgentCore Gateway запрашивает токен доступа для workload у AgentCore Identity Credential Provider, передавая идентификатор workload AgentCore Gateway и user ID в формате {gatewayId}{targetId}{uuid}. Этот workload access token идентифицирует AgentCore Gateway как авторизованного вызывающего для последующих операций с учетными данными.
  3. Используя workload access token, AgentCore Gateway запрашивает токен доступа OAuth 2.0 у AgentCore Identity Credential Provider. В ответ администратор получает URL авторизации и session-URI. На этом этапе target имеет статус Needs Authorization.
  4. Администратор открывает URL авторизации в браузере, входит в систему и предоставляет AgentCore Gateway запрошенные разрешения.
  5. После того как администратор дает согласие, сервер авторизации OAuth 2.0 отправляет authorization code на зарегистрированный callback endpoint AgentCore Identity Credential Provider.
  6. Credential provider перенаправляет браузер администратора на return URL вместе с session URI. Приложение администратора вызывает CompleteResourceTokenAuth, передавая user id и session-URI, возвращенный на шаге 2. Credential provider проверяет, что пользователь, инициировавший поток авторизации (шаг 3), и пользователь, завершивший согласие, — один и тот же. Это предотвращает перехват токена, если URL авторизации был случайно передан другому человеку. Если поток был запущен из AWS Console, этот шаг выполняется автоматически. Если он был запущен из другого контекста, администратор должен самостоятельно вызвать API CompleteResourceTokenAuth.
  7. После успешной проверки привязки сессии credential provider обменивает authorization code у сервера авторизации OAuth 2.0 на OAuth 2.0 access token.
  8. Этот access token используется для получения списка инструментов на target MCP-сервера; возвращенные определения инструментов кэшируются в AgentCore Gateway.

Обратите внимание: последующее обновление или синхронизация target не будут повторно использовать этот access token. Вместо этого AgentCore Identity получит новый access token от Authorization Server.

Создание target

Сначала создадим Amazon Bedrock AgentCore Gateway и Target и посмотрим, как работает неявная синхронизация при создании target для MCP-сервера.

При создании AgentCore Gateway необходимо использовать версию MCP 2025-11-25 или новее. Все остальные параметры оставьте по умолчанию и выберите MCP server target. Укажите endpoint MCP-сервера, а в качестве OAuth client выберите AgentCore Identity OAuth Client, созданный в разделе предварительных требований.

В разделе дополнительных настроек обязательно выберите Authorization code grant (3LO). Опция Authorization code grant (3LO) будет недоступна, если AgentCore Gateway не был создан с версией MCP 2025-11-25 или новее. Здесь также необходимо указать return URL. Во время привязки сессии после прохождения authorization code flow пользователи будут возвращаться на этот URL как при неявной синхронизации, так и при вызове инструмента. Вы можете переопределить значение return URL во время вызова. Дополнительную информацию см. в Example: Authorization code grant в руководстве Amazon Bedrock AgentCore Developer Guide. При настройке target можно указать scopes и дополнительные параметры, например audience. Эти параметры включаются в запрос, когда AgentCore Identity обращается к endpoint /authorize сервера авторизации.

После создания target он будет находиться в статусе Needs authorization. На этом этапе администратору необходимо завершить запрос авторизации либо напрямую из консоли AWS, либо перейдя по URL авторизации напрямую. Важно отметить, что если поток завершается из консоли AWS, привязка сессии выполняется автоматически. Если он был инициирован из другого контекста, администратор должен сам вызвать API CompleteResourceTokenAuth. Дополнительную информацию см. в примере кода в GitHub.

Вот как выглядит поток согласия, когда он инициирован из AWS Console.

Через несколько секунд вы увидите, что target перешел в статус Ready со статусом авторизации Authorized.

Предоставление схемы заранее при создании target для MCP-сервера

В этом разделе мы показываем, как предоставить схему заранее при создании target для MCP-сервера. Это рекомендуемый подход, когда вмешательство человека невозможно во время операций create/update.

На этом шаге мы создаем Amazon Bedrock AgentCore Gateway и Target и предоставляем схему заранее при создании target для MCP-сервера. Процесс остается тем же. На этапе выбора target выберите Use pre-defined list tools и вставьте определения инструментов GitHub. Вы можете скопировать определение инструментов из GitHub repository.

В этом случае target становится готов сразу, со статусом авторизации No authorization required.

Демонстрация

После успешного создания target, независимо от того, был ли использован метод неявной синхронизации или предоставление схемы заранее, пользователи AgentCore Gateway могут обнаруживать и вызывать инструменты с помощью протокола MCP. В этом разделе мы рассмотрим потоки tools/list и tools/call в AgentCore Gateway.

  1. Пользователь Gateway отправляет запрос tools/list в AgentCore Gateway со своим входящим токеном авторизации. Поскольку определения инструментов были кэшированы во время создания target, AgentCore Gateway немедленно возвращает кэшированные определения инструментов.
  2. Пользователь Gateway отправляет запрос tools/call в AgentCore Gateway со своим входящим токеном авторизации. Это запускает поток OAuth authorization code для конкретного target MCP-сервера, поскольку AgentCore Gateway нужен access token, чтобы вызвать MCP-сервер от имени этого пользователя.
  3. AgentCore Gateway запрашивает workload access token у AgentCore Identity, передавая workload identity и JWT пользователя из входящего заголовка авторизации.
  4. Используя workload access token, AgentCore Gateway запрашивает OAuth 2.0 access token у credential provider. Поскольку действительный токен для этого пользователя еще не существует, credential provider вместо этого возвращает URL авторизации и session-URI.
  5. AgentCore Gateway передает URL авторизации и session URI обратно пользователю Gateway. Пользователь открывает URL авторизации в браузере, входит в OAuth 2.0 authorization server и предоставляет запрошенные разрешения. Пример ответа URL elicitation от AgentCore Gateway выглядит так:
{    
      "jsonrpc": "2.0",                                                     
      "id": 3,    
      "error": {   
          "code": -32042,     
          "message": "This request requires more information.",   
          "data": {
            "elicitations": [{
               "mode": "url",
               "elicitationId": "<ID>",     
               "url": "<identity_url>/?request_uri=urn%3Aietf%3A...",
               "message": "Please login to this URL for authorization."
              }]      
          }       
      }
  	}
  1. После того как пользователь дает согласие, сервер авторизации OAuth 2.0 отправляет authorization code на зарегистрированный callback endpoint AgentCore Identity Credential Provider.
  2. Credential provider перенаправляет браузер пользователя на return URL вместе с session URI. Приложение пользователя вызывает CompleteResourceTokenAuth, передавая JWT пользователя и session-URI. Credential provider проверяет, что пользователь, начавший поток авторизации (шаг 4), — тот же самый, который завершил согласие.
  3. После успешной проверки привязки сессии credential provider обменивает authorization code у сервера авторизации OAuth 2.0 на OAuth 2.0 access token. Credential provider кэширует этот токен в Token Vault под workload identity и user identity.
  4. Когда пользователь Gateway снова отправляет запрос tools/call, AgentCore Gateway получает кэшированный токен у AgentCore Identity, используя workload identity и user identity, и применяет его для вызова MCP-сервера.

Теперь посмотрим демонстрацию сквозного потока, где мы отправляем запросы tools/list и tools/call в AgentCore Gateway.

Очистка ресурсов

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

Заключение

В этой публикации мы показали, как подключить защищенный OAuth MCP-сервер к Amazon Bedrock AgentCore Gateway с использованием потока Authorization Code. Централизуя аутентификацию через AgentCore Gateway, команды могут безопасно управлять учетными данными с помощью Amazon Bedrock AgentCore Identity, при этом предоставляя разработчикам бесшовный доступ к защищенным инструментам из MCP-клиента.

Хотя в этом примере рассматривается GitHub MCP server, в кодовом репозитории есть примеры интеграции с другими популярными сторонними MCP-серверами, а также руководство по размещению собственного MCP-сервера с поддержкой authorization code flow на AgentCore Runtime в качестве target AgentCore Gateway. Мы рекомендуем изучить эти примеры и адаптировать их под ландшафт MCP-серверов вашей организации.

Ресурсы

Чтобы узнать больше, обратитесь к следующим материалам:

  • Представляем Amazon Bedrock AgentCore Gateway: преобразуем разработку инструментов для корпоративных ИИ-агентов
  • Представляем Amazon Bedrock AgentCore Identity: обеспечиваем безопасность агентного ИИ в масштабе
  • Примеры Amazon Bedrock AgentCore
  • Привязка session для URL авторизации OAuth 2.0

Материал — перевод статьи с английского.

Оригинал: Connecting MCP servers to Amazon Bedrock AgentCore Gateway using Authorization Code flow

Подписаться на новости в Telegram

Больше записей