使用 AgentCore Gateway 与 MCP 客户端构建安全的授权码流程设置

在现代开发工作流中，开发者越来越依赖 Kiro Integrated Development Environment (IDE) 等代理式编码助手来与远程工具和服务交互。然而，组织需要强健的身份验证机制，以便在这些代理式编码助手与企业 Model Context Protocol (MCP) 服务器之间提供安全且经过身份验证的访问。

Amazon Bedrock AgentCore 是一项完全托管的服务，可帮助你在生产环境中部署、管理和扩展 AI 代理。其关键组件之一 AgentCore Gateway 提供了一个集中式入口点，用于路由并保护代理到工具的通信。当 AI 助手通过 Gateway 向 MCP 服务器发出请求时，该请求必须先经过验证才能被处理。这被称为入站身份验证。只有获得授权的用户和代理才能访问 MCP 服务器公开的工具和服务。组织通常通过身份提供商 (IdP) 管理用户身份，例如 Okta、Microsoft Entra ID 或 Amazon Cognito；这些身份提供商会对用户进行身份验证，并签发用于验证其身份的安全令牌。

本文演示如何将开放授权（OAuth）授权码流程实现为托管在 Amazon Bedrock AgentCore Gateway 上的 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 服务器的每个请求都使用属于该用户的有效身份令牌进行身份验证。

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

图 2：授权码流程请求序列。

配置概述

下表总结了授权码流程设置中每个组件所需的配置。详细的分步说明见“技术实现”部分。

技术实现

在架构和流程确立后，配置各个组件。本节为配置概览表中提到的三个组件提供分步说明：

1. 身份提供商：注册一个 OIDC 应用，并配置授权类型、重定向 URI 和令牌设置。
2. AgentCore Gateway：启用基于 JWT 的入站授权，并将其指向您的 IdP 发现端点。
3. MCP 客户端（Kiro IDE）：将客户端连接到网关 URL，并验证端到端的 OAuth 流程。

先决条件

你必须具备以下先决条件才能继续操作。

• 已部署 AgentCore Gateway 的 AWS 账户。
• 具有配置应用权限的身份提供者（IdP）（例如 Amazon Cognito、Okta、Auth0 或其他企业身份提供者）。
• MCP OAuth 代理。
• 本地安装的 Kiro IDE。
• 对 OAuth 2.0 流程有基本了解。

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

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

1.1 创建一个 OIDC 应用

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

• 登录方式：OIDC。
• 应用程序类型：Web 应用程序。
• 名称：AgentCore Gateway client（或您偏好的名称）。

1.2 配置授权类型

启用以下授权类型：

• 授权码。
• 刷新令牌。

1.3 设置重定向 URI

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

http://localhost:PORT/callback

将 PORT 替换为你的客户端使用的端口。

1.4 配置令牌设置

在你的 IdP 应用程序设置中，执行以下操作。

令牌有效期：

• 访问令牌有效期：1 小时（推荐）。
• 刷新令牌有效期：90 天（根据您的安全要求进行调整）。
• ID 令牌有效期：1 小时。

1.5 记录你的配置

保存以下值。你将需要它们来进行 Gateway 配置：

• Client ID：可在应用程序的 General 选项卡中找到（Kiro IDE 客户端配置需要）。
• Issuer URL：你的 IdP 的颁发者 URL（例如，https://{yourIdPDomain}/oauth2/default ）。
• 发现 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: Set up a JWT）。
• 示例：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 颁发者。
• 受众或自定义声明：验证令牌是为此特定网关或应用程序颁发的。
• 标准 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 将 Kiro IDE 的 MCP 客户端与网关受 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）。
• 第一个参数：带有 /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 连接后，验证身份验证流程是否成功完成：

1. 重启你的 AI 客户端。
2. 尝试使用 Gateway 中的工具。
3. 你会被重定向到浏览器进行 IdP 登录。
4. 身份验证成功后，工具会运行。

步骤 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 仓库。

清理

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

撤销 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 仅接受刷新令牌。其他 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 应用程序集成：

1. 登录你的 IdP 管理控制台。
2. 导航至 Applications > Applications。
3. 选择你创建的应用程序（例如，“AgentCore Gateway client”）。
4. 首先停用该应用程序（如果你的 IdP 要求），然后将其删除。

这会撤销所有客户端凭证，并阻止今后为此应用程序签发任何令牌。

结论

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

关键要点

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

更多资源

• 正文：AgentCore Gateway。
• OAuth 2.0 授权码流程。
• OpenID Connect 规范。
• MCP 规范。

关于作者