使用入站身份验证和出站身份验证进行身份验证和授权

本节向您介绍如何使用带身份的 OAuth 和 JWT 持有者令牌为代理运行时实现身份验证和授权。 AgentCore 您将学习如何设置 Cognito 用户池、为 JWT 身份验证（入站身份验证）配置代理运行时以及如何实现对第三方资源的 OAuth-based 访问权限（出站身份验证）。

有关完整示例，请参阅 https://github.com/awslabs/amazon-bedrock-agentcore-samples/。

有关在 MCP 服务器上使用 OAuth 的信息，请参阅在运行时部署 MCP 服务器。 AgentCore

亚马逊 Bedrock AgentCore 运行时为托管代理提供了两种身份验证机制：

限制 IAM (SigV4) 对您的网关的入站调用

您可以在 AgentCore 运行时前使用 AgentCore 网关，使网关成为运行时的单一、受管控的入口点——为您提供基于策略的授权、Amazon Bedrock Guardrails、请求和响应拦截器以及统一的可观察性，所有这些都应用在代理自己的环境之外。有关完整原理以及如何进行此设置，请参阅使用 AgentCore 网关预置运行时间。

但是，这仅在调用者无法直接绕过网关到达运行时时才有用。如果您的运行时使用默认 IAM (SigV4) 入站授权，则可以限制对网关的调用，以便流量只能通过网关到达运行时。要实现这一点，请将基于资源的策略附加到运行时，限制对网关执行角色的调用。网关假定其服务角色来签署运行时请求，因此网关角色是调用运行时的主体。允许该角色，Deny并为所有其他主体添加明确的权限，这样即使使用基于身份的许可策略，其他身份也无法调用运行时。有关基于资源的运行时政策的更多信息，请参阅 Amazon Bedroc Resource-based k 的政策。 AgentCore

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowOnlyGatewayRole",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
        },
        {
            "Sid": "DenyOtherPrincipals",
            "Effect": "Deny",
            "Principal": { "AWS": "*" },
            "Action": "bedrock-agentcore:InvokeAgentRuntime",
            "Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "Condition": {
                "ArnNotEquals": {
                    "aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
                }
            }
        }
    ]
}

JWT 入站授权和 OAuth 出站访问示例

本指南引导您完成将代理运行时设置为使用 JWT 格式的 OAuth 兼容访问令牌调用的过程。样本代理将使用 AWS Cognito 访问令牌获得授权。稍后，您还将了解代理代码如何代表用户获取 Google 令牌以查看 Google 云端硬盘和提取内容。

你会学到什么

在本指南中，您将学习如何：

先决条件

开始之前，请确保您已具备以下条件：

第 1 步：创建代理项目

使用该agentcore create命令来设置一个空项目。在步骤 2 中创建 Cognito 资源后添加 JWT-authorized 代理。

agentcore create --project-name OAuthAgentProject --no-agent
cd OAuthAgentProject

这会生成：

第 2 步：设置 AWS Cognito 用户池并添加用户

要设置 Cognito 用户池并创建用户，您将使用自动执行该过程的 shell 脚本。

有关更多信息，请参阅步骤 2：导入身份和身份验证模块。

设置 Cognito 用户池并创建用户

此脚本创建 Cognito 用户池、用户池客户端、添加用户并为用户生成持有者令牌。默认情况下，该令牌的有效期为 60 分钟。

第 3 步（可选）：使用 AgentCore 网关作为运行前端

您可以在 AgentCore 运行时前使用 AgentCore 网关，使网关成为运行时的单一、受管控的入口点——为您提供基于策略的授权、Amazon Bedrock Guardrails、请求和响应拦截器以及统一的可观察性，所有这些都应用在代理自己的环境之外。有关完整原理以及如何进行此设置，请参阅使用 AgentCore 网关预置运行时间。

如果您想提前部署此运行时，请立即创建网关，然后在下一步部署运行时。部署后，您需要将运行时添加为网关目标。

为确保调用者无法绕过网关，请将运行时间限制为仅接受来自该网关的调用。allowedWorkloadConfiguration按允许的方法使用WorkloadConfiguration：限制对网关的调用。C AgentCore LI 不配置此字段。使用 AgentCore 控制平面 API。

第 4 步：部署您的代理

{
    "Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
    "Effect": "Allow",
    "Action": "iam:CreateServiceLinkedRole",
    "Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
    "Condition": {
        "StringEquals": {
            "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
        }
    }
}

现在，您将使用您创建的 Cognito 用户池部署具有 JWT 授权的代理。您将需要使用授权者配置创建代理。下表列出了各种授权者配置参数以及我们如何使用它们来验证传入的令牌。

如果同时提供了 client_id 和 aud，则代理运行时授权者将对两者进行验证。

允许WorkloadConfiguration：限制对您的网关的调用

上的allowedWorkloadConfiguration字段customJWTAuthorizer限制了允许请求身份链中的哪些工作负载调用运行时。为您的网关设置允许的工作负载，以便运行时仅在其身份链包含该网关时才接受请求——这就是 OAuth (JWT) 运行时强制流量仅通过您在步骤 3 中设置的网关到达的方式。

您可以使用以下任一字段提供允许的工作负载。您可以指定其中一个或两个——如果请求的身份链与任一字段中的条目相匹配，则该请求将被接受，因此您无需同时提供这两个信息。

以下授权方配置通过其 ARN 限制对特定 AgentCore 网关的调用。hostingEnvironments单独指定是允许网关的最简单方法：

{
    "authorizerConfiguration": {
        "customJWTAuthorizer": {
            "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
            "allowedClients": ["your-client-id"],
            "allowedWorkloadConfiguration": {
                "hostingEnvironments": [
                    {
                        "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
                    }
                ]
            }
        }
    }
}

或者，您可以通过网关的工作负载标识名称来识别网关，也可以同时指定这两个字段。当两者都存在时，如果请求与任一字段中的条目相匹配，则允许该请求。以下allowedWorkloadConfiguration代码段允许使用两个不同的网关——一个由其 ARN 标识，另一个由其工作负载标识名称标识：

"allowedWorkloadConfiguration": {
    "hostingEnvironments": [
        {
            "arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
        }
    ],
    "workloadIdentities": [
        "my-gateway-2-workload-identity"
    ]
}

创建和部署代理运行时

准备好授权器配置后，创建和部署代理运行时。以下示例说明如何使用 AgentCore CLI 或 Python AWS 开发工具包 (Boto3) 来执行此操作。记下输出中的代理运行时 ARN ——在下一步中，您需要它来调用代理。

第 5 步：使用不记名代币调用您的代理

现在您的代理已通过 JWT 授权部署，您可以使用持有者令牌调用它。

{
    "Sid": "GetAgentAccessToken",
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetWorkloadAccessToken",
        "bedrock-agentcore:GetWorkloadAccessTokenForJWT",
        "bedrock-agentcore:GetWorkloadAccessTokenForUserId"
    ],
    # point to the workload identity for the runtime; the workload identity can be found in
    # the GetAgentRuntime response and has your agent name in it.
    "Resource": [
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
    ]
}

调用代理

为您使用亚马逊 Cognito 创建的用户获取不记名代币。

# use the password and other details used when you created the cognito user

export TOKEN=$(aws cognito-idp initiate-auth \
    --client-id "$CLIENT_ID" \
    --auth-flow USER_PASSWORD_AUTH \
    --auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
    --region us-east-1 | jq -r '.AuthenticationResult.AccessToken')

按照以下其余说明继续调用代理。

使用 OAuth 调用代理。

OAuth 错误响应

OAuth-configured 代理遵循 RFC 6749 (OAuth 2.0) 身份验证标准。缺少身份验证时，该服务会返回带有 WWW-Authenticate 标头的 401 未经授权的响应（根据 RFC 7235），使客户端能够通过 API 发现授权服务器端点。 GetRuntimeProtectedResourceMetadata

401 未经授权-缺少身份验证

当授权标头中未提供不记名令牌时，响应为：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"

WWW-Authenticate 标题中的 resource_metadata URL 指向受保护资源元数据 (PRM) API。PRM API 使客户端能够发现哪些授权服务器保护了该代理及其 OAuth 端点 URL。

第 6 步：设置您的代理以使用 OAuth 访问工具

在本节中，您将学习如何将代理代码与 AgentCore 凭据提供者连接起来，以便使用 OAuth2 身份验证安全访问外部资源。

以下示例演示了在 Agent Runtime 中运行的代理如何请求用户的 OAuth 同意，从而使他们能够使用自己的 Google 帐号进行身份验证并授权代理访问其 Google 云端硬盘内容。

有关设置身份的更多信息，请参阅 AgentCore 身份入门。

步骤 6.1：设置凭证提供商

要设置 Google 凭证提供商，您需要：

确保您的调用角色具有访问凭证提供商的必要权限。

步骤 6.2：允许代理读取 Google 云端硬盘内容

创建带有代理核心 SDK 注释的工具，如以下示例所示，以自动启动三步 OAuth 流程。当您的代理调用此工具时，系统会提示用户在浏览器中打开授权网址，并同意代理访问他们的 Google 云端硬盘。

import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key

# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
    auth_flow="USER_FEDERATION", # 3LO flow
    on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
    print(access_token) #You can see the access_token
    # Make API calls...
    main(access_token)

asyncio.run(read_from_google_drive(access_token=""))

幕后会发生什么

当此代码运行时，会发生以下过程：

第 7 步：（可选）将 JWT 令牌传播到运行时 AgentCore

或者，您可以将授权标头传递给 AgentCore Runtime 以提取索赔。这可以通过使用请求标头允许列表配置来完成。有关更多信息，请参阅 RequestHeaderConfiguration。

第 7.1 步：修改代理代码以读取标题

在此步骤中，您将更改代理代码，以便可以使用 PyJWT 库对 JWT 令牌进行解码和提取索赔。

Python 依赖

将 PyJWT 添加到生成的代理中：pyproject.toml

cd app/OAuthAgent
uv add PyJWT
cd ../..

更新您的代理代码

按以下代码app/OAuthAgent/main.py所示进行修改。您可以在此处跳过验证令牌签名，因为 AgentCore Runtime 已经在入站授权期间验证了令牌。

import jwt
import json
....

@app.entrypoint
def invoke(payload, context):
    auth_header = context.request_headers.get('Authorization')
    if not auth_header:
        return None

    # Remove "Bearer " prefix if present
    token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
    try:
        # Skip signature validation as agent runtime has validated the token already.
        claims = jwt.decode(token, options={"verify_signature": False})
        app.logger.info("Claims: %s", json.dumps(claims))
    except jwt.InvalidTokenError as e:
        app.logger.exception("Invalid JWT token: %s", e)

    .....

步骤 7.2：部署更新的代理

步骤 4 中的agentcore add agent命令已经配置了Authorization请求标头允许列表。部署代码更新：

agentcore deploy

步骤 7.3：调用您的代理

使用 OAuth 调用您的代理，您应该会在代理日志中的日志中 CloudWatch 看到索赔。

问题排查

如何调试与令牌相关的问题

如果您遇到令牌身份验证问题，则可以对令牌进行解码以检查其内容：

echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i<l; i++) printf "="; print "" }' | base64 -D | jq

这将输出代币的有效载荷，其外观类似于：

{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}

对令牌问题进行故障排除时，请检查以下内容：