用授权码流为 AgentCore Gateway 上的 MCP 做入站身份验证

在现代开发工作流中，开发人员越来越依赖智能体式编码助手，例如 Kiro 集成开发环境（Integrated Development Environment, IDE）（https://kiro.dev/），来与远程工具和服务交互。然而，组织需要稳健的身份验证机制，以便在这些智能体式编码助手与企业模型上下文协议（Model Context Protocol, MCP）（https://modelcontextprotocol.io/docs/getting-started/intro）服务器之间，提供安全、经过身份核验的访问。

Amazon Bedrock AgentCore（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html）是一项全托管服务，帮助你在生产环境中部署、管理和扩展 AI 智能体。它的关键组件之一 AgentCore Gateway（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html），为智能体到工具的通信提供集中入口，用于路由和保护这些通信。当 AI 助手通过 Gateway 向 MCP 服务器发出请求时，该请求必须在处理之前得到核验。这称为入站身份验证（inbound authentication）。只有经过授权的用户和智能体才能访问 MCP 服务器所暴露的工具和服务。组织通常通过身份提供者（identity provider, IdP）管理用户身份，例如 Okta、Microsoft Entra ID 或 Amazon Cognito（/cognito/）。IdP 对用户进行身份验证，并签发用于证明其身份的安全令牌。

本文演示如何把开放授权（Open Authorization, OAuth）授权码流实现为托管在 Amazon Bedrock AgentCore Gateway（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html）上的 MCP 服务器的入站授权机制。读完本指南后，你将拥有一套可用于生产的配置：每一次 AI 助手请求，都使用由贵组织身份提供者签发的有效用户身份令牌进行身份验证。

#### 你将学到什么

• 授权码流如何与作为 MCP 资源服务器的 AgentCore Gateway 配合工作。
• 逐步配置贵组织的身份提供者。
• AgentCore Gateway 入站身份验证设置。
• 与 Kiro IDE 客户端集成。

解决方案概述

在入站授权码流 OAuth 配置中，AgentCore Gateway 充当 MCP 资源服务器，在允许 AI 客户端访问任何工具之前，要求提供有效的身份令牌。

下图展示授权码流与 AgentCore Gateway 的端到端架构，包括身份提供者、AI 客户端和 MCP 服务器之间的交互。

图 1：授权码流架构图。

关键组件

该解决方案涉及下列组件共同完成身份验证流：

• 身份提供者（IdP）：管理用户身份验证并签发令牌。上图引用 Amazon Cognito，但它也可以是贵组织的 IdP。
• 用户：与 IdP 进行身份验证的最终用户，其身份在每次请求中得到核验。
• Amazon Bedrock AgentCore Gateway：充当 OAuth 资源服务器，验证令牌并把请求代理到 MCP 服务器。
• 智能体式编码助手：Kiro IDE，它充当 OAuth 客户端并管理身份验证流。
• MCP 服务器：AI 助手需要访问的后端工具和服务。
• MCP OAuth 代理（可选）：帮助弥合智能体式编码助手、IdP 与 MCP 服务器之间规范标准化的差距。MCP OAuth 代理带来支持授权码流的标准化。

入站授权码流

此流程确保 AI 助手发送到 MCP 服务器的每一个请求，都使用属于该用户的有效身份令牌进行身份验证。

• MCP 客户端连接：智能体式编码助手（例如 Kiro IDE）向 AgentCore Gateway 的 MCP 端点发起连接。
• 身份验证质询：Gateway 检测到请求缺少有效令牌，并返回 HTTP 401，其中包括指向 Gateway 的 OAuth 受保护资源元数据端点（.well-known/oauth-protected-resource）的 www-authenticate 头。这遵循 MCP 规范的受保护资源元数据（Protected Resource Metadata, PRM）模式（https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization）。
• 发现：MCP 客户端从 Gateway 获取受保护资源元数据，后者返回 IdP 的授权服务器发现 URL（例如 https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration）。
• 用户重定向：MCP 客户端打开用户的系统浏览器，并带着 PKCE 质询重定向到 IdP 的授权端点，请求已配置的作用域（例如 openid profile email offline_access）。
• 用户身份验证与同意：用户在 IdP 登录页输入凭证。IdP 核验用户身份，并提示同意以授权该应用。
• 授权码授予：批准之后，IdP 把用户浏览器重定向到客户端的本地回调 URL（由客户端的本地监听器管理），并附上授权码。
• 令牌交换请求：MCP 客户端把授权码连同 PKCE 代码验证器发送到 IdP 的令牌端点。
• 令牌签发：IdP 验证授权码和 PKCE 验证器，然后向 MCP 客户端返回访问令牌（以及可选的刷新令牌）。
• 已认证的 MCP 请求与验证：MCP 客户端在后续所有请求的 Authorization 头中包含访问令牌。Gateway 验证令牌的签名、过期时间、签发者和受众或自定义声明，然后把请求代理到目标 MCP 服务器执行。

图 2：授权码流请求时序。

配置概览

下表汇总授权码流配置中每个组件所需的配置。技术实现一节随后给出逐步说明。

技术实现

架构和流程确定之后，配置每个组件。本节为配置概览表中引用的三个组件提供逐步说明：

• 身份提供者：注册一个 OIDC 应用，并配置授权类型、重定向 URI 和令牌设置。
• AgentCore Gateway：启用基于 JWT 的入站授权，并把它指向你的 IdP 发现端点。
• MCP 客户端（Kiro IDE）：把客户端连接到 Gateway URL，并验证端到端 OAuth 流。

前提条件

要跟着操作，你必须具备下列前提条件。

• 一个已部署 AgentCore Gateway（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-building.html）的 AWS 账户。
• 一个身份提供者（IdP），并有权配置应用（例如 Amazon Cognito、Okta、Auth0 或其他企业身份提供者）。
• MCP OAuth 代理。
• 本地已安装 Kiro IDE。
• 对 OAuth 2.0（https://oauth.net/2/）流程的基本理解。

步骤 1：配置组织的身份提供者

在此步骤中，你向组织的身份提供者注册一个 OIDC 应用，并将其配置为支持带 PKCE 的授权码流。

#### 1.1 创建 OIDC 应用

登录你的 IdP 管理控制台，并创建新的 OIDC/OAuth 2.0 应用集成：

• 登录方法：OIDC。
• 应用类型：Web 应用。
• 名称：AgentCore Gateway client（或你偏好的名称）。

#### 1.2 配置授权类型

启用下列授权类型：

• Authorization Code。
• Refresh Token。

#### 1.3 设置重定向 URI

添加你的 AI 客户端将使用的回调 URL：

http://localhost:PORT/callback

把 PORT 替换为你的客户端使用的端口（https://kiro.dev/docs/enterprise/identity-provider/okta/#create-new-app-integration）。

#### 1.4 配置令牌设置

在 IdP 应用设置中执行下列操作。

令牌生命周期：

• 访问令牌生命周期：1 小时（推荐）。
• 刷新令牌生命周期：90 天（根据你的安全要求调整）。
• ID 令牌生命周期：1 小时。

#### 1.5 记下你的配置

保存下列值。配置 Gateway 时会用到它们：

• Client ID：位于应用的 General 选项卡（Kiro IDE 客户端配置需要）。
• Issuer URL：你的 IdP 签发者 URL（例如 https://{yourIdPDomain}/oauth2/default）。
• Discovery URL：你的 IdP 的 OpenID Connect 发现端点（例如 https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration）。

对于此配置：

• 不需要客户端密钥：此流程使用 PKCE（Proof Key for Code Exchange，代码交换证明密钥），它是为桌面应用这类公共客户端设计的。Kiro IDE 不需要也不使用客户端密钥。
• 客户端配置中没有 IdP 端点：Kiro IDE 从 Gateway 自动发现 OAuth 端点，Gateway 返回发现 URL。你不在客户端中直接配置 IdP URL。

步骤 2：配置 AgentCore Gateway

身份提供者配置完成之后，下一步是把 AgentCore Gateway 连接到你的 IdP，以便它能验证传入的令牌。

#### 2.1 设置入站授权模式

把 Gateway 配置为使用基于 JWT 的身份验证，并指向你的 IdP 发现端点：

# Example Gateway configuration (adjust based on your deployment method)
aws agentcore update-gateway \
  --gateway-id <your-gateway-id> \
  --inbound-auth-type JWT \
  --jwt-discovery-url "https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration" \
  --region <your-region>

#### 2.2 自定义声明验证

AgentCore Gateway 基于标准 OAuth 2.0 声明验证 JWT 令牌，并支持自定义声明验证，以适配不同的 IdP 实现。Gateway 期望令牌包含：

• 标准声明：iss（签发者）、aud（受众）、exp（过期）、iat（签发时间）、client_id（客户端身份）和 scopes（允许的作用域）。
• 客户端识别：Gateway 可以根据你的 IdP，通过各种声明验证客户端身份。

其他 IdP 可能对客户端识别、作用域等使用不同的声明名称（例如 cid、azp、scp）。你可以在 Gateway 中配置自定义声明验证，以匹配你的 IdP 令牌结构：

• 自定义声明：<claim-name> EQUALS <expected-value>（见 AgentCore Gateway：设置 JWT（https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-inbound-auth.html））。
• 示例：cid EQUALS 0oaz7147z771FZmdQ697（用于使用 cid 的 IdP，例如 Okta）。
• 这会验证令牌是为你的特定应用签发的。

注意：使用自定义声明验证时，Gateway 的 Allowed audience 字段可以保持为空。自定义声明检查提供必要的客户端身份核验。

#### 2.3 理解 Gateway 的令牌验证

既然 Gateway 已配置你的 IdP 发现 URL 和声明规则，接下来看它在运行时如何验证传入令牌。

AgentCore Gateway 的设计与用户如何取得 OAuth 令牌无关。Gateway 不区分通过下列方式取得的令牌：

• 客户端凭证流：应用直接进行身份验证。
• 授权码流：用户显式进行身份验证并授予同意。

Gateway 只要求请求中出示的 OAuth 令牌，根据 Gateway 设置期间配置的参数是有效的：

• 令牌签名：对照来自 IdP 发现 URL 的公钥进行验证。
• 令牌过期：验证令牌尚未过期。
• 签发者（iss 声明）：与预期的 IdP 签发者匹配。
• 受众或自定义声明：验证令牌是为这个特定 Gateway 或应用签发的。
• 标准 OAuth 声明：检查所需声明，例如 iat、exp 等。

无论用户通过客户端凭证流、授权码流还是其他 OAuth 授权类型取得令牌，Gateway 都同等对待所有令牌。只要令牌通过你在 Gateway 设置中配置的验证检查，请求即被授权。有了这种灵活性，你可以选择适合用例的身份验证流，同时在 Gateway 层保持一致的安全。

#### 2.4 验证 Gateway 配置

测试你的 Gateway 端点可访问，并且要求身份验证：

# Test authentication with an actual MCP request (POST without auth token)
curl -i -X POST https://<your-gateway-url>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

下列响应确认身份验证已正确配置（对未认证的 MCP 请求返回 401）：

# Expected response showing authentication is required:
HTTP/2 401
www-authenticate: Bearer resource_metadata="https://<your-gateway-url>/.well-known/oauth-protected-resource"
{"jsonrpc":"2.0","id":0,"error":{"code":-32001,"message":"Missing Bearer token"}}

步骤 3：MCP OAuth 代理

就本文而言，使用 mcp-remote 来标准化 MCP 客户端接口，并完成授权码流。

#### 3.1 安装 mcp-remote 包

使用 mcp-remote（https://www.npmjs.com/package/mcp-remote）把 Kiro IDE 的 MCP 客户端桥接到 Gateway 受 OAuth 保护的端点。

注意：mcp-remote 是一个可用的概念验证，应视为实验性的。

npm install -g mcp-remote

步骤 4：配置 AI 客户端（Kiro IDE）

Gateway 和 MCP OAuth 代理配置完成之后，最后的配置步骤是把你的 AI 客户端连接到 Gateway 端点。Kiro IDE 自动处理 OAuth 流。当它从 Gateway 收到 401 质询时，它会与你的 IdP 发起授权码流。

#### 4.1 配置 Kiro IDE

把 Gateway 添加到位于 ~/.kiro/settings/mcp.json 的 MCP 配置文件：

{
  "mcpServers": {
    "gateway-tools": {
      "command": "mcp-remote",
      "args": [
        "https://<your-gateway-url>/mcp",
        "<PORT>",
        "--static-oauth-client-info",
        "{\"client_id\": \"<your-idp-client-id>\", \"redirect_uris\": [\"http://localhost:<PORT>/oauth/callback\"], \"scope\": \"openid profile email offline_access\"}"
      ]
    }
  }
}

配置参数：

• command：使用 mcp-remote 连接到远程 MCP 服务器（mcp-remote（https://www.npmjs.com/package/mcp-remote））。
• 第一个参数：带 /mcp 路径的 Gateway URL。
• 第二个参数：OAuth 回调的本地端口（例如 3334）。
• --static-oauth-client-info：包含下列内容的 JSON 字符串：
• client_id：你的 IdP 应用客户端 ID。
• redirect_uris：必须与第二个参数中指定的端口匹配。
• scope：包含 openid profile email offline_access 以进行基本身份验证。

#### 4.2 测试身份验证流

添加 Gateway 连接之后，验证身份验证流成功完成：

• 重启你的 AI 客户端。
• 尝试使用来自 Gateway 的工具。
• 你被重定向到浏览器进行 IdP 登录。
• 身份验证成功之后，该工具运行。

步骤 5：验证端到端流程

所有组件配置完成且初次身份验证成功之后，验证完整流程端到端可用：从 AI 客户端发送工具请求，经过 Gateway 的令牌验证，到从 MCP 服务器收到响应。

#### 5.1 检查令牌验证

监视 Gateway 日志以确认令牌验证：

# Example log entry showing successful validation
[INFO] Token validated successfully for user: user@example.com
[INFO] Executing tool: list_files

若要使用 Okta 作为 IdP 的逐步演练，见此 GitHub 仓库（https://github.com/awslabs/agentcore-samples/tree/main/06-workshops/02-AgentCore-gateway/17-inbound-auth-code-flow-okta）。

清理

如果你跟着本文操作，并想撤销所创建的资源，请完成下列步骤。它们按创建的相反顺序给出，以便在依赖组件之前先移除依赖它们的资源。

撤销 OAuth 令牌

在移除任何配置之前，撤销测试期间签发的任何活动令牌。查阅你的 IdP 文档，了解确切的撤销端点 URL 和支持的参数。

curl -X POST "<your-idp-revocation-endpoint>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<your-refresh-token>&client_id=<your-client-id>"

因 IdP 而异的关键考量：

• 撤销端点 URL：查看你的 IdP 的 OpenID Connect 发现文档（revocation_endpoint 字段）。
• 接受的令牌类型：有些 IdP 只接受刷新令牌。另一些同时接受访问令牌和刷新令牌。
• 客户端身份验证：公共客户端通常在正文中传递 client_id。机密客户端可能要求带编码凭证的 Basic Authorization 头。
• 级联行为：撤销刷新令牌通常会使与之关联的访问令牌失效，但请向你的 IdP 确认。

你也可以通过移除 mcp-remote 身份验证缓存来清除本地缓存的令牌。在 macOS 或 Linux 上：

rm -rf ~/.mcp-auth

移除 AI 客户端配置（Kiro IDE）

从位于 ~/.kiro/settings/mcp.json 的 Kiro IDE MCP 配置中移除 Gateway 条目。删除你在步骤 4 中添加的 gateway-tools 服务器块。

移除 MCP OAuth 代理

卸载你在步骤 3 中安装的 mcp-remote 包：

npm uninstall -g mcp-remote

删除 AgentCore Gateway 配置

移除你在步骤 2 中设置的入站身份验证配置，或者如果你只是为本次演练创建了 Gateway，则整个删除它：

选项 A：移除入站身份验证（保留 Gateway）

aws agentcore update-gateway \
  --gateway-id <your-gateway-id> \
  --inbound-auth-type NONE \
  --region <your-region>

选项 B：删除 Gateway

aws agentcore delete-gateway \
  --gateway-id <your-gateway-id> \
  --region <your-region>

移除组织的身份提供者配置

删除你在步骤 1 中创建的 OIDC 应用集成：

• 登录你的 IdP 管理控制台。
• 导航到 Applications > Applications。
• 选择你创建的应用（例如 “AgentCore Gateway client”）。
• 先停用该应用（如果你的 IdP 要求），然后删除它。

这会撤销所有客户端凭证，并阻止将来为该应用签发任何令牌。

结论

在本文中，你了解了如何使用入站授权码流，为托管在 Amazon Bedrock AgentCore Gateway 上的 MCP 服务器实现安全、经过身份核验的访问。有了这一配置，每一次 AI 助手请求都使用来自贵组织身份提供者的有效用户令牌进行身份验证。

#### 要点

• 授权码流通过要求用户同意和身份核验，提供强身份验证。
• AgentCore Gateway 充当 OAuth 资源服务器，在允许请求调用目标之前验证令牌。
• 该流程对最终用户是透明的。他们认证一次，令牌会自动刷新。
• 此架构可以扩展，以支持多个 AI 客户端和身份提供者。

PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/building-a-secure-auth-code-flow-setup-using-agentcore-gateway-with-mcp-clients