Bedrock AgentCore OAuth 同意管理：GitHub / Slack 三方登录实战

AI 智能体常常需要代表用户访问 GitHub、Slack 等服务。在智能体能够操作之前，用户必须先通过服务提供商进行身份验证，并明确批准所请求的访问权限。随后，应用必须将该 OAuth 授权结果安全地关联到授权该操作的用户。这一过程称为会话绑定。

此前，使用 AgentCore Identity（Amazon Bedrock AgentCore 的一项功能）进行三-legged OAuth（3LO）流程（也称为 OAuth 2.0 授权码流程）的客户，必须自行构建和托管自己的会话绑定基础设施。这包括：展示授权 URL、托管公共 HTTPS 回调端点、对返回的用户进行身份验证、管理浏览器会话，以及调用 CompleteResourceTokenAuth 来完成整个流程。

AgentCore Identity 现已提供 Consent portal（授权门户），这是一套面向 AgentCore Gateway（Amazon Bedrock AgentCore 的一项功能）的托管 Web 体验和会话绑定端点。管理员为某个网关创建一个门户，然后将对应的 URL 分享给用户。用户通过所在组织的身份提供商（IdP）进行身份验证，查看智能体可用的服务，并逐个提供商授予授权同意。门户负责处理浏览器重定向和会话绑定，而 AgentCore Identity 则将生成的令牌安全存储在其令牌保险库中。

这一功能对于通过 IDE 和 Model Context Protocol（MCP）客户端（如 Kiro、Claude Code、Cursor 和 Visual Studio Code）访问的智能体尤为实用。用户可以在调用工具之前预先授予授权，后续的工具调用即可直接使用已为该用户存储的令牌。在本文中，我们以一个软件开发助手为例进行说明。我们将带您走过 AWS Management Console 和浏览器端的管理员体验和最终用户体验，并展示如何在 AWS CloudTrail 中审查由此产生的活动记录。

图 1：Consent 门户通过企业 IdP 对用户进行身份验证，使用其 IAM 执行角色发现已配置的网关目标，展示提供商连接，完成会话绑定，并将每个用户的令牌存储在 AgentCore Identity 令牌保险库中

示例场景：授予开发助手访问 GitHub 的权限

假设有一家名为 Example Corp 的公司，通过 AgentCore Gateway 为其开发人员提供 AI 编程助手。该助手有两个目标：

一个 GitHub 目标，可以列出代码仓库和创建 issue。

一个 Slack 目标，可以列出公共频道和发布消息。

Example Corp 使用其企业 IdP 对员工进行身份验证。管理员希望每个 GitHub 和 Slack 的 OAuth 授权都能与批准它的员工关联。开发人员可以独立连接任一提供商，然后返回 IDE 而无需重复弹窗提示。

本次演练围绕两个角色展开：

管理员：配置企业 IdP、GitHub 和 Slack 网关目标、执行角色和 Consent 门户，然后将门户 URL 发送给开发人员。

最终用户：打开 URL，通过企业 IdP 登录，在需要时连接 GitHub，并可单独授予 Slack 访问权限。

在开始演练之前，Example Corp 需要具备以下条件：

一个可访问 Amazon Bedrock AgentCore 的 AWS 账户。

一个已配置 JWT 入站授权的 AgentCore Gateway。

一个已配置为连接同一 AgentCore Gateway 的 IDE 或 MCP 客户端（该网关将附加到 Consent 门户）。

对企业 IdP 的管理员访问权限。

一个已注册的 GitHub OAuth App，以及一个用于开发或测试工作空间的 Slack App。

在每个提供商应用中注册 AgentCore Identity 回调 URL 的权限。

以下步骤展示了 Example Corp 管理员的配置内容，以及开发人员在收到门户 URL 后的使用体验。

管理员完成步骤 1-6 以配置身份提供商、网关目标、执行角色和 Consent 门户。

管理员 IAM 策略

将此策略附加到执行步骤 1-3 的管理员身份上。请替换账户 ID。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManageConsentPortalResources",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateConsentPortal",
        "bedrock-agentcore:GetConsentPortal",
        "bedrock-agentcore:ListConsentPortals",
        "bedrock-agentcore:CreateOauth2CredentialProvider",
        "bedrock-agentcore:GetOauth2CredentialProvider",
        "bedrock-agentcore:ListOauth2CredentialProviders",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets",
        "bedrock-agentcore:UpdateGatewayTarget"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CreateAndPassExecutionRole",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:GetRole",
        "iam:PutRolePolicy",
        "iam:GetRolePolicy",
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::111122223333:role/service-role/AmazonBedrockAgentCoreConsentPortal*"
    }
  ]
}

AWS Identity and Access Management（IAM）策略语句涵盖了控制台上的"Create default role"选项，该选项会创建一个名为 AmazonBedrockAgentCoreConsentPortalDefaultServiceRole-<suffix> 的服务角色。如果使用自己的角色，请将 iam:PassRole 的范围限定在该角色 ARN 上。

在企业 IdP 中，为 Consent 门户创建一个 OpenID Connect（OIDC）Web 应用程序。

启用授权码授权模式，并生成客户端 ID 和客户端密钥。

配置登录作用域，至少包含 openid。

记录 OpenID Connect（OIDC）发现 URL。门户从此文档中获取授权端点、令牌端点和签名密钥。

添加一个临时回调 URL。该 URL 将在步骤 6 中替换为门户创建后的真实 URL。

IdP 必须签发一个门户可以验证的 JSON Web Token（JWT）访问令牌。例如，使用 Okta 时，应使用自定义授权服务器，并配置访问策略以允许该应用程序和授权码授权模式。使用 Auth0 时，请根据需要配置 audience 参数，以便 IdP 返回签名 JWT 访问令牌而非不透明令牌。

门户从 OAuth2 凭证提供商读取 IdP 客户端 ID 和客户端密钥。

打开 Amazon Bedrock AgentCore 控制台。

在 Build 下，选择 Identity。

在 Outbound Auth 中，选择 Add Outbound Auth，然后选择 Add OAuth client。

输入名称，例如 gateway-demo-idp。

输入来自企业 IdP 应用程序的客户端 ID 和客户端密钥，并提供 OIDC 发现配置。

选择 Add OAuth client。

图 2：AgentCore Identity 使用一个凭证提供商进行门户登录，而 GitHub 和 Slack 各自使用独立的出站提供商

在创建 Consent 门户之前，请确认：

GitHub 和 Slack OAuth 应用程序已注册，且其客户端密钥已存储在 AWS Secrets Manager 中。

AgentCore Identity 分别为 GitHub 和 Slack 配置了独立的出站 OAuth 凭证提供商，且每个提供商生成的回调 URL 已在对应的提供商应用程序中注册。

GitHub 和 Slack 网关目标使用了授权码授权模式，仅请求所需的最小作用域，并处于 Ready 状态。

步骤 5 中选择的 Consent 门户执行角色可以读取出站凭证提供商所引用的任何客户管理密钥。

门户 URL 分配后，在步骤 6 中配置每个目标的默认返回 URL。

图 3：网关暴露了独立的 GitHub 和 Slack 目标，每个目标关联各自对应的出站 OAuth 提供商

在 Identity 页面上，Consent portals 部分列出了该账户和 AWS 区域中的所有门户。

图 4：AgentCore Identity 页面上的 Consent portals 部分。仅当网关使用需要用户授权的 3LO 时，才需要创建门户

在 Consent portals 中，选择 Create portal。

在 Consent portal details 下，对于 Name，输入名称，例如 consent-portal-heqk0。名称接受 1-50 个字符，可使用字母、数字、连字符和下划线。

可选输入最多 512 个字符的 Description。

对于 Gateway，选择开发助手所使用的网关。网关名称对最终用户在 Consent 门户中可见，因此请选择一个清晰、可识别的名称。每个网关允许一个 Consent 门户，且网关在创建后无法更改。

在 IdP credential configurations 下，对于 IdP Credential Provider，选择在步骤 3 中创建的 OAuth2 凭证提供商。

在 Scopes 下，保留所需的 openid 作用域。额外的作用域为可选项。仅在 IdP 或应用程序需要时才添加作用域。

对于 Audience（可选），除非网关指定了受众，否则保持 None。该值将根据 AgentCore Gateway 上配置的受众进行验证。

展开 Permissions。对于 IAM permissions，选择 Create default role 以便控制台创建一个具有所需权限的服务角色，或选择 Use another role 以选择现有角色。

选择 Create portal。

Figure 5: 当状态为 Creating 时，门户 ARN 和执行角色可见，但 URL 尚未分配

配置完成后，状态变为 Active，同意门户 URL 出现，Launch Consent portal 按钮会在新标签页中打开它。URL 遵循以下模式：https://<gateway-name>.consent-portal.bedrock-agentcore.<region>.amazonaws.com。

Figure 6: 门户变为 Active 后，控制台显示分配的 URL，您可以将其分享给最终用户

从门户详情页复制同意门户 URL。

在企业 IdP 应用程序（例如 Amazon Cognito、Okta 或 Auth0）中，用 <portal-url>/callback 替换临时回调 URL。不要添加尾部斜杠。这不是 GitHub 或 Slack 应用程序的回调。那些应用程序使用唯一的 AgentCore Identity callbackUrl。

对于每个 3LO 网关目标，将默认返回 URL 设置为 <portal-url>/connect/callback。

确认每个出站提供商应用程序包含创建其 OAuth 凭证提供商时返回的 AgentCore Identity callback URL。

在浏览器中测试门户 URL。

通过批准的沟通渠道将门户 URL 发送给开发团队。

完成提供商回调和网关目标后，在分享门户 URL 之前验证最终的管理员配置。

最终用户在收到门户 URL 后完成第 7 步以登录并连接提供商。

在浏览器中打开门户 URL。

选择 Sign in。浏览器重定向到 Example Corp IdP。

使用企业身份进行身份验证。然后门户使用其 IAM 执行角色来检索网关配置的目标及其连接状态。

在 Connections 页面上，查看 GitHub 和 Slack OAuth 客户端及其目标状态。

选择 Connect for GitHub。

查看 GitHub 同意页面上的范围并批准访问权限。

浏览器返回门户后，确认 GitHub 显示 Connected，而 Slack 仍为 Not connected。这表明每个提供商的授权是独立的。

如果智能体需要 Slack，选择 Connect for Slack，选择工作区，查看请求的权限，并批准应用。否则，让 Slack 保持未连接状态，直到需要时再连接。

返回配置为使用附加到同意门户的同一 AgentCore Gateway 的 IDE 或 MCP 客户端，并通过该网关重试适用的 GitHub 或 Slack 工具调用。

以下截图捕捉了演练中有用的检查点。

Figure 7: 同意门户发现 GitHub OAuth 客户端及其目标。在用户授予访问权限之前，两者都保持 Not connected 状态

Figure 8: GitHub 在用户授权之前显示 OAuth 应用程序请求的范围和组织访问权限

Figure 9: GitHub 返回授权结果后，门户完成会话绑定，并将 OAuth 客户端和目标显示为 Connected

Figure 10: GitHub 保持 Connected 状态，而 Slack 为 Not connected，表明用户独立为每个出站提供商授予同意

门户验证 IdP 响应并建立加密浏览器会话。

门户使用其执行角色列出附加网关的 3LO 目标。

当用户选择 Connect 时，门户调用 GetResourceOauth2Token 并接收授权 URL 和会话 URI。

在提供商将授权码返回给 AgentCore Identity 后，浏览器返回到门户的托管会话绑定端点。

门户使用已认证的用户上下文调用 CompleteResourceTokenAuth。

当提供商返回刷新令牌时，AgentCore Identity 会存储它，并在当前访问令牌过期后自动使用它来获取新的访问令牌。有时没有有效的刷新令牌可用，因为提供商没有颁发刷新令牌，或者它已过期或被撤销。在这种情况下，用户必须返回同意门户，并在访问令牌无法再使用时重新授权。配置提供商在支持的情况下颁发刷新令牌。例如，为 GitHub 启用用户对服务器令牌过期，或为 Slack 启用令牌轮换。

下次开发人员打开门户时，已连接的提供商仍然可见。开发人员不需要再次批准提供商，除非授权被撤销、过期或需要续订同意。开发人员也可以选择 Disconnect，稍后再重新连接提供商。

在 AWS CloudTrail 中审查同意活动

Amazon Bedrock AgentCore 在 AWS CloudTrail 中记录同意操作。在 CloudTrail 事件历史中，按 Event source 筛选 bedrock-agentcore.amazonaws.com，然后查看：

GetResourceOauth2Token — 当门户为提供商启动 OAuth 授权时。

CompleteResourceTokenAuth — 当会话绑定完成时。

GetWorkloadAccessTokenForJWT — 当门户为已认证用户获取网关访问权限时。

GetResourceOauth2Token 事件标识凭证提供商、请求的范围、OAuth 流程、门户执行角色和区域。敏感的令牌和状态值被编辑。

{
  "eventSource": "bedrock-agentcore.amazonaws.com",
  "eventName": "GetResourceOauth2Token",
  "awsRegion": "ap-southeast-2",
  "userIdentity": {
    "type": "AssumedRole",
    "arn": "arn:aws:sts::111122223333:assumed-role/AmazonBedrockAgentCoreConsentPortalDefaultServiceRole-example/consent-dashboard-example"
  },
  "requestParameters": {
    "workloadIdentityToken": "HIDDEN_DUE_TO_SECURITY_REASONS",
    "resourceCredentialProviderName": "gateway-demo-github",
    "scopes": ["read:user", "repo"],
    "oauth2Flow": "USER_FEDERATION",
    "customState": "HIDDEN_DUE_TO_SECURITY_REASONS"
  },
  "resources": [
    {
      "accountId": "111122223333",
      "type": "AWS::BedrockAgentCore::OAuth2CredentialProvider",
      "arn": "arn:aws:bedrock-agentcore:ap-southeast-2:111122223333:token-vault/default/oauth2credentialprovider/gateway-demo-github"
    }
  ],
  "managementEvent": true
}

对于失败，使用 errorCode 和 errorMessage，并结合事件时间、 assumed role、区域、凭证提供商和请求的范围来识别原因。

当不再需要这些资源时：

打开 Amazon Bedrock AgentCore 控制台并删除同意门户。

从企业 IdP 应用程序和网关目标中移除门户回调 URL。

删除引用出站凭证提供商的网关目标。

删除出站 OAuth 凭证提供者和企业 IdP 凭证提供者（如果没有其他资源使用它们）。

如果没有任何其他资源使用门户执行角色，则删除它。

注意：在删除其出站凭证提供者之前，先删除网关目标。仍被目标引用的凭证提供者无法被删除。

Amazon Bedrock AgentCore 同意门户为管理员提供了一种托管方式来配置 AgentCore Gateway 的最终用户 OAuth 同意。管理员连接企业 IdP、执行角色、网关和出站提供商，然后分享一个 URL。最终用户进行身份验证、查看可用提供商并单独授予同意。门户处理浏览器流程和托管会话绑定，而 AgentCore Identity 在令牌保管库中保护生成的用户令牌。

有关使用 Microsoft Entra ID 和 Okta 的端到端示例，请参阅 GitHub 上的以下 Amazon Bedrock AgentCore 示例：

使用授权码流目标的同意门户

使用 OAuth 授权码流的 AgentCore Gateway 目标

要了解更多，请参阅 Amazon Bedrock AgentCore。