インバウンド認証とアウトバウンド認証による認証と認可

このセクションでは、AgentCore Identity で OAuth および JWT ベアラートークンを使用して、エージェントランタイムの認証と認可を実装する方法について説明します。 AgentCore Cognito ユーザープールの設定、JWT 認証用のエージェントのランタイムの設定 (インバウンド認証）、サードパーティーリソースへの OAuth ベースのアクセスの実装 (アウトバウンド認証) を行う方法について説明します。

完全な例については、https://github.com/awslabs/amazon-bedrock-agentcore-samples/ を参照してください。

MCP サーバーで OAuth を使用する方法については、AgentCore ランタイムで MCP サーバーをデプロイする」を参照してください。

Amazon Bedrock AgentCore ランタイムは、ホストされたエージェントに 2 つの認証メカニズムを提供します。

ゲートウェイへの IAM (SigV4) インバウンド呼び出しを制限する

AgentCore ランタイムを AgentCore Gateway でフロントして、ゲートウェイがランタイムへの単一の管理エントリポイントになるようにできます。これにより、ポリシーベースの認可、Amazon Bedrock ガードレール、リクエストとレスポンスのインターセプター、統合オブザーバビリティが提供され、すべてエージェント独自の環境外で適用されます。詳細な理論的根拠と設定方法については、「Front your runtime with an 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 コマンドを使用して、空のプロジェクトをセットアップします。ステップ 2 で Cognito リソースを作成した後、JWT 認可エージェントを追加します。

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

これにより、以下が生成されます。

ステップ 2: AWS Cognito ユーザープールを設定し、ユーザーを追加する

Cognito ユーザープールをセットアップしてユーザーを作成するには、プロセスを自動化するシェルスクリプトを使用します。

詳細については、「ステップ 2: ID と認証モジュールをインポートする」を参照してください。

Cognito ユーザープールをセットアップしてユーザーを作成するには

このスクリプトは、Cognito ユーザープール、ユーザープールクライアントを作成し、ユーザーを追加し、ユーザーのベアラートークンを生成します。トークンはデフォルトで 60 分間有効です。

ステップ 3 (オプション): AgentCore Gateway を使用してランタイムをフロントする

AgentCore ランタイムを AgentCore Gateway でフロントして、ゲートウェイがランタイムへの単一の管理エントリポイントになるようにできます。これにより、ポリシーベースの認可、Amazon Bedrock ガードレール、リクエストとレスポンスのインターセプター、統合オブザーバビリティが提供され、すべてエージェント独自の環境外で適用されます。詳細な理論的根拠と設定方法については、「Front your runtime with an AgentCore Gateway」を参照してください。

このランタイムをフロントする場合は、次のステップでランタイムをデプロイする前に、今すぐゲートウェイを作成します。デプロイ後、ランタイムをゲートウェイターゲットとして追加します。

発信者がゲートウェイをバイパスできないようにするには、そのゲートウェイからの呼び出しのみを受け入れるようにランタイムを制限します。allowedWorkloadConfiguration: restrict invocation to your gateway の説明allowedWorkloadConfigurationに従って を使用します。AgentCore CLI はこのフィールドを設定しません。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 の両方が指定されている場合、エージェントランタイムオーソライザーは両方を検証します。

allowedWorkloadConfiguration: ゲートウェイへの呼び出しを制限する

の allowedWorkloadConfigurationフィールドは、リクエストの ID チェーン内のどのワークロードがランタイムを呼び出すことができるか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"
                    }
                ]
            }
        }
    }
}

または、ワークロード ID 名でゲートウェイを識別するか、両方のフィールドを指定することもできます。両方が存在する場合、いずれかのフィールドのエントリと一致するリクエストが許可されます。次のスニペットでは、ARN で識別されるゲートウェイとワークロード ID 名で識別されるゲートウェイの allowedWorkloadConfiguration 2 つの異なるゲートウェイを使用できます。

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

エージェントランタイムを作成してデプロイする

オーソライザー設定の準備ができたら、エージェントランタイムを作成してデプロイします。次の例は、AgentCore CLI または AWS SDK for Python (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 ヘッダー (RFC 7235 ごと) を含む 401 Unauthorized レスポンスを返します。これにより、クライアントは 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 認証を使用して外部リソースに安全にアクセスする方法について説明します。

次の例は、エージェントランタイムで実行されているエージェントがユーザーに OAuth 同意をリクエストし、Google アカウントで認証し、エージェントが Google ドライブコンテンツにアクセスすることを許可する方法を示しています。

ID の設定の詳細については、AgentCore Identity の開始方法」を参照してください。

ステップ 6.1: 認証情報プロバイダーを設定する

Google 認証情報プロバイダーを設定するには、以下を行う必要があります。

呼び出しロールに、認証情報プロバイダーにアクセスするために必要なアクセス許可があることを確認します。

ステップ 6.2: エージェントが Google Drive の内容を読み取れるようにする

次の例に示すように、エージェントコア SDK 注釈を使用してツールを作成し、3 レッグの 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 トークンからクレームをデコードおよび抽出できるように、エージェントコードを変更します。

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

トークンの問題をトラブルシューティングする場合は、以下を確認してください。