View a markdown version of this page

ワークロードアクセストークンを取得する - Amazon Bedrock AgentCore
ワークロードアクセストークンとはRuntime と Gateway がトークンを自動的に取得する方法ワークロードアクセストークンを手動で取得する方法GetWorkloadAccessTokenForUserId API のセキュリティコントロール

ワークロードアクセストークンを取得する

ワークロードアクセストークンとは何か、それらを取得する方法、およびそれらを操作する際のセキュリティの側面を理解することは、安全なエージェントアプリケーションを構築する上で不可欠です。このセクションでは、知っておく必要がある主要な概念と実装パターンについて説明します。

ワークロードアクセストークンとは

ワークロードアクセストークンは AWS、エージェントがアウトバウンド認証情報プロバイダーなどのファーストパーティー AgentCore サービスにアクセスできるようにする署名付き不透明アクセストークンです。ランタイムは、ワークロードアクセストークンをペイロードヘッダーとしてエージェント実行インスタンスに自動的に配信するため、ほとんどのシナリオで手動でトークンを管理する必要はありません。

主な特徴

  • ファーストパーティサービスのみ – ワークロードアクセストークンは AWS ファーストパーティ AgentCore サービスへのアクセス専用であり、外部サービスには使用できません

  • 自動配信 – ランタイムとゲートウェイは、実行中にこれらのトークンをエージェントに自動的に提供します。

  • 設計によるセキュリティ – ランタイムマネージドエージェント ID はワークロードアクセストークンを直接取得できず、トークンの抽出と誤用を防止します。

  • ユーザーとエージェントの ID バインディング – トークンには、認証情報に安全にアクセスするためのユーザー ID とエージェント ID の両方の情報が含まれています。

Runtime と Gateway がトークンを自動的に取得する方法

エージェントをインバウンド認証で AgentCore Runtime または Gateway 経由で呼び出すと、サービスはワークロードアクセストークンの生成を自動的に処理します。

  1. ランタイムがインバウンド ID プロバイダーの OAuth トークン (発行者、署名) を検証する

  2. ランタイムは、ユーザー ID を表す OAuth トークンから発行者とサブクレームを抽出します。

  3. ランタイムは、エージェントの関連するワークロード ID を取得します。

  4. ユーザー ID とエージェントワークロード ID の両方GetWorkloadAccessTokenForJWTを使用してランタイムを呼び出す

  5. ランタイムは、呼び出しペイロードヘッダーの一部としてワークロードアクセストークンをエージェントコードに渡します。

この自動プロセスにより、エージェントは手動操作なしで適切な範囲のトークンを受信できます。

ワークロードアクセストークンを手動で取得する方法

エージェントのエンドユーザーを識別する方法に応じて、ワークロードアクセストークンを取得するために使用する 2 つのパターンがあります。

パターン 1: JWT ベースの識別 (本番環境に推奨)

エージェントの発信者にエンドユーザーの ID プロバイダーによって発行された JWT がある場合は、 を使用してワークロードアクセストークンをリクエストしますGetWorkloadAccessTokenForJWT。JWT を指定すると、AgentCore Identity はトークンを検証して正しく署名され、有効期限が切れていないことを確認し、その「iss」および「sub」クレームを使用してユーザーを一意に識別します。ユーザーに代わってエージェントによって保存される認証情報は、この暗号的に検証された ID に関連付けられ、将来の取得には同じ ID を持つ有効なワークロードアクセストークンが必要です。

このパターンは、次の場合に使用します。

  • アプリケーションが ID プロバイダー (Cognito、Auth0、Okta など) と統合されている

  • エンドユーザーの ID の暗号化証明が必要です

  • 本番環境にデプロイする

パターン 2: UserId ベースの識別

エージェントの発信者にエンドユーザーを識別する JWT がない場合は、ユーザーを識別する一意の文字列GetWorkloadAccessTokenForUserIdを持つ を使用してワークロードアクセストークンをリクエストします。

このパターンは、次の場合に使用します。

  • アプリケーションは独自のユーザー識別子を管理し、カスタマー管理の userId 文字列を AgentCore Identity に渡す必要があります

  • IdP トークンがまだ利用できない開発シナリオまたはクイックスタートシナリオにいる

  • エンタープライズアーキテクチャはユーザー ID をアップストリームで解決し、信頼できる識別子をエージェントのワークロードに渡します。

トレードオフ: プラットフォームは userId を不透明な文字列として扱い、認証されたエンドユーザー ID と照合することはできません。セキュリティバインドは、正しい userId を渡す呼び出しワークロードと、適切にスコープされる IAM ポリシーに依存します。推奨されるコントロールGetWorkloadAccessTokenForUserId API のセキュリティコントロールについては、「」を参照してください。

コードの例

以下の例は、AgentCore SDK を使用して、これら 2 つの方法を使用してワークロードアクセストークンを取得する方法を示しています。

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

GetWorkloadAccessTokenForUserId API のセキュリティコントロール

GetWorkloadAccessTokenForUserId API は、発信者が提供するユーザー識別子文字列を受け入れ、そのユーザーとエージェントのペアを対象とするワークロードアクセストークンを発行します。この API は、カスタマー管理の userId 文字列を渡す必要があるエンタープライズのお客様や、開発中に ID プロバイダー (IdP) トークンを利用できないビルダーをサポートするように設計されています。

重要

を使用する場合GetWorkloadAccessTokenForUserId、プラットフォームはuserId値を不透明な文字列として扱い、認証されたエンドユーザー ID に対して検証しません。セキュリティバインディングは、呼び出し元のワークロードが正しい userId を渡し、IAM ポリシーが適切にスコープされるかどうかに完全に依存します。アプリケーションがエンドユーザーを識別する JWT にアクセスできる場合は、GetWorkloadAccessTokenForJWT代わりに を使用します。これにより、ワークロードアクセストークンを発行する前にトークンの発行者、署名、有効期限を検証します。

GetWorkloadAccessTokenForUserId API は、不正アクセスを防ぐためにいくつかのセキュリティコントロールを実装します。

  • ワークロード ID の検証 – API は、リクエスト元の ID に、指定されたワークロード ID に代わって動作するアクセス許可があることを確認します。

  • サービスマネージド ID 制限 – ランタイムマネージド型およびゲートウェイマネージド型のワークロード ID は、トークンを直接取得できません。これにより、エージェントが誤用のためにトークンを抽出できなくなります。

  • IAM アクセス許可の要件 – 発信者には、、、 などの適切な GetWorkloadAccessTokenForUserId IAM GetWorkloadAccessToken アクセス許可が必要です。 GetWorkloadAccessTokenForJWT

  • トークンスコープ — トークンは特定のユーザーとエージェントのペアに限定され、あるユーザーに保存されている認証情報に別のユーザーがアクセスできないようにします。

  • 複数の ID プロバイダーのユーザー ID パーティショニング – 複数の ID プロバイダーを使用する場合は、 パターンを使用してユーザー IDs をパーティション化しprovider_id+user_id、異なるプロバイダー間のユーザーの衝突を防ぎます。たとえば、 cognito+user123と を使用して、異なる ID プロバイダー間で同じ識別子を持つユーザーauth0+user123を区別します。

推奨されるセキュリティコントロール

プラットフォームは userId 文字列を検証できないため、この API に渡される値の整合性を確保する責任があります。次のコントロールを適用します。

  • JWT が利用可能なGetWorkloadAccessTokenForJWT場合を優先する – JWT ベースのパスはトークンの発行者と署名を検証し、ユーザーの ID の暗号化証明を提供します。JWT が使用できないGetWorkloadAccessTokenForUserId場合にのみ使用します。

  • 信頼できるソースから userId を取得する – userId 値は、クライアントが指定した任意の値を受け入れるのではなく、認証されたプリンシパルのコンテキスト (IAM 発信者 ID、セッション属性、アップストリーム ID 解決レイヤーなど) から取得する必要があります。これにより、認証された発信者が他のユーザーになりすますことを防ぎます。

  • IAM アクセス許可を制限する – 信頼されたプリンシパルのみが アクセスbedrock-agentcore:GetWorkloadAccessTokenForUserId許可を持つ必要があります。このアクセス許可を特定のワークロード ID リソースにスコープします。管理ポリシーまたはワイルドカードリソースステートメントを介して広く付与しないでください。

  • 不要なGetWorkloadAccessTokenForUserId場所での拒否 – 常に JWT が使用可能なワークロードの場合は、IAM ポリシーのアクションを明示的に拒否して、userId パスが使用されないようにします。

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • 監査ログの実装 – 認証された IAM プリンシパルと渡される userId 値との関係をログに記録します。 AWS CloudTrail を使用してGetWorkloadAccessTokenForUserId呼び出しをモニタリングし、予期しない userId 値を検出します。

WorkloadIdentity がサービスにリンクされており、発信者がアクセストークンを取得できない」というエラーが発生した場合、ワークロード ID が Runtime または Gateway によって管理され、トークンを直接取得できないことを示します。この制限は、セキュリティ境界を維持し、不正なトークンアクセスを防ぐのに役立ちます。

セキュリティコントロールを強化するために、きめ細かなアクセスポリシーを実装して、特定の認証情報プロバイダーにアクセスできるワークロード ID を制限できます。詳細については、「ワークロード ID による認証情報プロバイダーへのアクセスのスコープダウン」を参照してください。