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

标题：使用 AgentCore Gateway 和 MCP 客户端构建安全的授权码流设置 | 亚马逊网络服务

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

发布日期：2026-06-01T19:23:35-08:00

Markdown 内容： 在现代开发工作流程中，开发者越来越多地依赖代理编码助手（如 Kiro 集成开发环境 (IDE)）来与远程工具和服务进行交互。然而，组织需要强大的身份验证机制，以确保这些代理编码助手与企业 模型上下文协议 (MCP) 服务器之间的访问是安全且经过身份验证的。

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

本文演示如何将开放授权（OAuth）授权码流实现为托管在 Amazon Bedrock AgentCore Gateway 上的 MCP 服务器的入站授权机制。本指南结束时，您将拥有一个生产就绪的设置，其中每个 AI 助手请求都通过来自您组织的身份提供商的有效用户身份令牌进行身份验证。

#### 您将学到的内容

• 如何在 AgentCore Gateway 作为 MCP 资源服务器的情况下使用授权码流。
• 您组织的身份提供商的分步配置。
• 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 代理带来了支持授权码流的标准化。

1. MCP 客户端连接 – 智能编码助手（例如 Kiro IDE）启动与 AgentCore 网关的 MCP 端点的连接。
2. 身份验证挑战 – 网关检测到请求缺少有效令牌，并返回 HTTP 401 响应，其中包含一个 www-authenticate 头，指向网关的 OAuth 受保护资源元数据端点（.well-known/oauth-protected-resource）。这遵循 MCP 规范中的 受保护资源元数据（PRM）模式。
3. 发现 – MCP 客户端从网关获取受保护资源元数据，该元数据返回身份提供者（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 头中包含访问令牌。网关验证令牌的签名、过期时间、发行者和受众或自定义声明，然后将请求代理到目标 MCP 服务器以执行。

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

配置概览

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

| 组件 | 所需配置 | | --- | --- | | 1 | 身份提供者 | 创建一个启用了授权码和刷新令牌授予的 OpenID Connect (OIDC) Web 应用程序。 | | 2 | AgentCore 网关 | 设置入站授权为 JWT。配置发现 URL 为您的 IdP 发行者（例如 https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration）。 | | 3 | Kiro IDE | 在设置 > 连接器（或通过命令行）中添加网关 URL。如果网关返回带有正确认证头的 401 未授权响应，客户端会自动触发 OAuth 流程。 |

技术实现

在建立架构和流程之后，配置每个组件。本节提供了针对配置概述表中引用的三个组件的分步说明：

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

先决条件

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

• 已部署 AgentCore 网关 的 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 客户端（或您偏好的名称）。

#### 1.2 配置授权类型

启用以下授权类型：

• 授权码。
• 刷新令牌。

#### 1.3 设置重定向 URI

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

http://localhost:PORT/callback 将 PORT 替换为您 客户端使用的端口。

#### 1.4 配置令牌设置

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

令牌生命周期：

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

#### 1.5 记录您的配置

保存以下值。您将在网关配置中需要它们：

• 客户端 ID：在应用程序的“常规”选项卡中找到（用于 Kiro IDE 客户端配置）。
• 发行者 URL：您的 IdP 的发行者 URL（例如 https://{yourIdPDomain}/oauth2/default）。
• 发现 URL：您的 IdP 的 OpenID Connect 发现端点（例如 https://{yourIdPDomain}/oauth2/default/.well-known/openid-configuration）。

对于此配置：

• 无需客户端密钥 – 此流程使用 PKCE（代码交换的证明密钥），专为桌面应用程序等公共客户端设计。Kiro IDE 不需要或使用客户端密钥。
• 客户端配置中无 IdP 端点 – Kiro IDE 会从网关自动发现 OAuth 端点，网关会返回发现 URL。您无需在客户端中直接配置 IdP URL。

第 2 步：配置 AgentCore 网关

在配置好身份提供者后，下一步是将 AgentCore 网关连接到您的 IdP，以便它能够验证传入的令牌。

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

配置您的网关以使用基于 JWT 的身份验证，并结合 IdP 的发现端点：

# 示例网关配置（根据您的部署方式进行调整）
aws agentcore update-gateway \
  --gateway-id <您的网关ID> \
  --inbound-auth-type JWT \
  --jwt-discovery-url "https://{您的IdP域名}/oauth2/default/.well-known/openid-configuration" \
  --region <您的区域>

Bash

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

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

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

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

• 自定义声明：<声明名称> EQUALS <预期值>（参见 AgentCore 网关：设置 JWT）。
• 示例：cid EQUALS 0oaz7147z771FZmdQ697（适用于使用 cid 的 IdP，如 Okta）。
• 这可验证令牌是否为您的特定应用程序签发。

注意：在使用自定义声明验证时，网关的“允许的受众”字段可以保持为空。自定义声明检查提供了必要的客户端身份验证。

#### 2.3 理解网关令牌验证

现在网关已配置了您的 IdP 发现 URL 和声明规则，请查看其在运行时如何验证传入的令牌。

AgentCore 网关的设计使其不关心用户如何获取 OAuth 令牌。网关不会区分通过以下方式获取的令牌：

• 客户端凭据流，其中应用程序直接进行身份验证。
• 授权码流，其中用户明确进行身份验证并授予同意。

网关仅要求请求中呈现的 OAuth 令牌基于网关设置期间配置的参数有效：

• 令牌签名：与 IdP 发现 URL 中的公钥进行验证。
• 令牌过期：验证令牌未过期。
• 发行者 (`iss` 声明)：与预期的 IdP 发行者匹配。
• 受众或自定义声明：验证令牌是为此特定网关或应用程序签发的。
• 标准 OAuth 声明：检查必需的声明，如 iat、exp 等。

无论用户通过客户端凭据流、授权码流或其他 OAuth 授予权限类型获取令牌，网关都会同等对待所有令牌。只要令牌通过了网关设置中配置的验证检查，请求就会被授权。借助这种灵活性，您可以选择适合您用例的身份验证流程，同时在网关级别保持一致的安全性。

#### 2.4 验证网关配置

测试您的网关端点是否可访问并需要身份验证：

# 使用实际的 MCP 请求测试身份验证（不带身份验证令牌的 POST）
curl -i -X POST https://<您的网关URL>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

Bash

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

# 预期响应显示需要身份验证：
HTTP/2 401
www-authenticate: Bearer resource_metadata="https://<您的网关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

Bash

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

在网关和 MCP OAuth 代理配置完成后，最后的配置步骤是将您的 AI 客户端连接到网关端点。Kiro IDE 会自动处理 OAuth 流程。当它收到网关的 401 挑战时，它会与您的 IdP 启动授权码流。

#### 4.1 配置 Kiro IDE

将网关添加到您的 MCP 配置文件 ~/.kiro/settings/mcp.json 中：

{
  "mcpServers": {
    "gateway-tools": {
      "command": "mcp-remote",
      "args": [
        "https://<您的网关URL>/mcp",
        "<PORT>",
        "--static-oauth-client-info",
        "{\"client_id\": \"<您的IdP客户端ID>\", \"redirect_uris\": [\"http://localhost:<PORT>/oauth/callback\"], \"scope\": \"openid profile email offline_access\"}"
      ]
    }
  }
}

JSON

配置参数：

• command: 使用 mcp-remote 连接到远程 MCP 服务器 (mcp-remote)。
• 第一个参数：带有 /mcp 路径的网关 URL。
• 第二个参数：用于 OAuth 回调的本地端口（例如，3334）。
• --static-oauth-client-info: 包含以下内容的 JSON 字符串：
• client_id: 您的身份提供者（IdP）应用程序客户端 ID。
• redirect_uris: 必须与第二个参数中指定的端口匹配。
• scope: 包含 openid profile email offline_access 以实现基本身份验证。

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

添加网关连接后，验证身份验证流程是否成功完成：

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

第 5 步：验证端到端流程

在所有组件配置完毕且初始身份验证成功后，验证完整的端到端流程是否正常工作，从 AI 客户端发送工具请求，通过网关进行令牌验证，直到从 MCP 服务器接收响应。

#### 5.1 检查令牌验证

监控您的网关日志以确认令牌验证：

# 示例日志条目显示成功验证
[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>"

Bash

不同 IdP 的关键注意事项：

• 撤销端点 URL：检查您的 IdP 的 OpenID Connect 发现文档（revocation_endpoint 字段）。
• 接受的令牌类型：某些 IdP 仅接受刷新令牌。其他 IdP 接受访问令牌和刷新令牌。
• 客户端认证：公共客户端通常在正文中传递 client_id。机密客户端可能需要带有编码凭据的 Basic Authorization 标头。
• 级联行为：撤销刷新令牌通常会使其关联的访问令牌失效，但请与您的 IdP 确认。

您还可以通过删除 mcp-remote 认证缓存来清除本地缓存的令牌。在 macOS 或 Linux 上：

rm -rf ~/.mcp-auth

Bash

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

从 Kiro IDE 的 MCP 配置文件 ~/.kiro/settings/mcp.json 中删除网关条目。删除在第 4 步中添加的 gateway-tools 服务器块。

删除 MCP OAuth 代理

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

npm uninstall -g mcp-remote

Bash

删除 AgentCore 网关配置

删除在第 2 步中设置的入站身份验证配置，或者如果仅为本演练创建了网关，则将其完全删除：

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

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

Bash

选项 B：删除网关

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

Bash

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

删除在第 1 步中创建的 OIDC 应用程序集成：

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

这将撤销所有客户端凭据，并防止为此应用程序未来发放任何令牌。

结论

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

#### 关键要点

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

#### 额外资源

• AgentCore 网关。
• OAuth 2.0 授权码流程。
• OpenID Connect 规范。
• MCP 规范。

• * *

作者简介