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

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

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

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

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

将 IAM (Sigv4) 入站调用限制到您的网关

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

但是，只有当调用者无法直接绕过网关到达运行时时，这才有用。如果您的运行时使用默认 IAM (Sigv4) 入站授权，则可以限制对网关的调用，以便流量只能通过网关到达运行时。为此，请将基于资源的策略附加到运行时，该策略将调用限制在网关的执行角色上。网关扮演其服务角色来签署对运行时的请求，因此网关角色是调用运行时的委托人。允许该角色，Deny并为所有其他委托人添加一个显式角色，这样即使使用基于身份的宽松策略，其他身份也无法调用运行时。有关基于资源的运行时策略的更多信息，请参阅 Amazon Bedro Resource-based ck 政策。 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 出站访问示例

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

你会学到什么

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

先决条件

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

步骤 1：创建您的代理项目

使用agentcore create命令使用您选择的框架来设置骨架代理项目：

agentcore create

该命令将提示您：

这会生成：

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

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

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

设置 Cognito 用户池并创建用户

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

第 3 步（可选）：在运行时前使用 AgentCore 网关

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

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

为确保呼叫者无法绕过网关，请将运行时限制为仅接受来自该网关的调用。在下一步中，作为授权方的一部分，您可以使用allowedWorkloadConfiguration（参见 allowed WorkloadConfiguration：限制对网关的调用）进行配置。

步骤 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 SDK (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-*"
    ]
}

调用代理

为您使用 Amazon 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网址指向受保护资源元数据 (PRM) API。PRM API 使客户端能够发现哪些授权服务器保护此代理及其 OAuth 端点 URL。

步骤 6：将您的代理设置为使用 OAuth 访问工具

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

以下示例演示了在代理运行时中运行的代理如何请求用户同意 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 运行时以提取声明。这可以通过使用请求标头白名单配置来完成。有关更多信息，请参阅 RequestHeaderConfiguration。

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

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

requirements.txt

将 PyJWT 依赖项添加到生成的requirements.txt项目中的文件中。

PyJWT

更新您的代理代码

修改生成的项目中的主代理文件（通常src/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：使用请求标头许可名单创建代理

使用 AgentCore CLI 为代理配置请求标头允许名单。导航到你生成的项目目录并运行：

agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none

# Now deploy the agent runtime
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"
}

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