使用傳入身分驗證和傳出身分驗證進行身分驗證和授權

本節說明如何使用 OAuth 和 JWT 承載符記搭配 AgentCore Identity 來實作代理程式執行時間的身分驗證和授權。您將了解如何設定 Cognito 使用者集區、為 JWT 身分驗證 （傳入身分驗證） 設定代理程式執行期，以及實作以 OAuth 為基礎的第三方資源存取權 （傳出身分驗證）。

如需完整範例，請參閱 https://github.com/awslabs/amazon-bedrock-agentcore-samples/。

如需搭配 MCP 伺服器使用 OAuth 的資訊，請參閱在 AgentCore 執行期中部署 MCP 伺服器。

Amazon Bedrock AgentCore 執行期為託管代理程式提供兩種身分驗證機制：

限制對閘道的 IAM (SigV4) 傳入呼叫

您可以使用 AgentCore Gateway 預付 AgentCore 執行期，讓閘道成為執行期的單一受管進入點 — 為您提供以政策為基礎的授權、Amazon Bedrock Guardrails、請求和回應攔截器，以及統一的可觀測性，這些都適用於代理程式自己的環境之外。如需完整原理以及如何設定，請參閱使用 AgentCore Gateway 開啟您的執行時間。

但這只有在呼叫者無法直接繞過閘道到達執行時間時才有用。如果您的執行時間使用預設 IAM (SigV4) 傳入授權，您可以限制對閘道的呼叫，讓流量只能透過它到達執行時間。若要達成此目的，請將資源型政策連接至執行時間，以限制對閘道執行角色的呼叫。閘道會擔任其服務角色來簽署對執行期的請求，因此閘道角色是叫用執行期的委託人。允許該角色，並Deny為每個其他主體新增明確 ，以便即使使用寬鬆的身分型政策，其他身分也無法叫用執行時間。如需執行時間的資源型政策詳細資訊，請參閱 Amazon Bedrock 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 Drive 並擷取內容。

您將學到什麼

在本指南中，您將了解如何：

先決條件

開始之前，請確定您已：

步驟 1：建立您的代理程式專案

使用 agentcore create命令，使用您選擇的架構來設定骨架代理程式專案：

agentcore create

命令會提示您：

這會產生：

步驟 2：設定 AWS Cognito 使用者集區並新增使用者

若要設定 Cognito 使用者集區並建立使用者，您將使用可自動化程序的 shell 指令碼。

如需詳細資訊，請參閱步驟 2：匯入身分和身分驗證模組。

設定 Cognito 使用者集區並建立使用者

此指令碼會建立 Cognito 使用者集區、使用者集區用戶端、新增使用者，並為使用者產生承載字符。根據預設，字符有效期為 60 分鐘。

步驟 3 （選用）：使用 AgentCore Gateway 開啟執行時間

您可以使用 AgentCore Gateway 預付 AgentCore 執行期，讓閘道成為執行期的單一受管進入點 — 為您提供以政策為基礎的授權、Amazon Bedrock Guardrails、請求和回應攔截器，以及統一的可觀測性，這些都適用於代理程式自己的環境之外。如需完整原理以及如何設定，請參閱使用 AgentCore Gateway 開啟您的執行時間。

如果您想要提前此執行時間，請先建立閘道，再於下一個步驟部署執行時間。部署之後，您會將執行時間新增為閘道目標。

為了確保呼叫者無法略過閘道，請將執行時間限制為僅接受來自該閘道的呼叫。您可以在下一個步驟中，使用 作為授權方的一部分來設定此項目 allowedWorkloadConfiguration（請參閱 allowedWorkloadConfiguration：限制對閘道的呼叫)。

步驟 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，代理程式執行時間授權方會驗證兩者。

allowedWorkloadConfiguration：限制對閘道的呼叫

上的 allowedWorkloadConfiguration 欄位會customJWTAuthorizer限制請求身分鏈中允許叫用執行時間的工作負載。將允許的工作負載設定為您的閘道，讓執行時間僅在其身分鏈包含該閘道時接受請求 — 這是 OAuth (JWT) 執行時間強制流量僅透過您在步驟 3 中設定的閘道到達的方式。

您可以使用下列任一欄位提供允許的工作負載。您可以指定一個或兩者 - 如果請求的身分鏈符合任一欄位中的項目，則表示您不需要同時提供兩者。

下列範例會建立代理程式執行時間，以限制其 ARN 對特定 AgentCore Gateway 的呼叫。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 設定的代理程式遵循 RFC 6749 (OAuth 2.0) 身分驗證標準。缺少身分驗證時，服務會傳回包含 WWW-Authenticate 標頭的 401 未授權回應 （根據 RFC 7235)，讓用戶端能夠透過 GetRuntimeProtectedResourceMetadata API 探索授權伺服器端點。

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 端點 URLs。

步驟 6：設定您的代理程式以使用 OAuth 存取工具

在本節中，您將了解如何將代理程式程式碼與 AgentCore 登入資料提供者連線，以便使用 OAuth2 身分驗證安全地存取外部資源。

下列範例示範在 Agent Runtime 中執行的代理程式如何向使用者請求 OAuth 同意，讓他們能夠向 Google 帳戶進行身分驗證，並授權代理程式存取其 Google Drive 內容。

如需設定身分的詳細資訊，請參閱開始使用 AgentCore Identity。

步驟 6.1：設定登入資料提供者

若要設定 Google 登入資料提供者，您需要：

請確定您的調用角色具有存取登入資料提供者的必要許可。

步驟 6.2：讓代理程式讀取 Google Drive 內容

建立具有代理程式核心 SDK 註釋的工具，如下列範例所示，以自動啟動三個區段的 OAuth 程序。當您的代理程式叫用此工具時，系統會提示使用者在瀏覽器中開啟授權 URL，並授予代理程式存取其 Google Drive 的同意。

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 執行期已驗證權杖簽章。

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 Logs 的代理程式日誌中看到宣告。

疑難排解

如何偵錯字符相關問題

如果您遇到字符身分驗證問題，您可以解碼字符以檢查其內容：

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"
}

疑難排解字符問題時，請檢查下列項目：