OAuth 2.0 認可 URL セッションバインディング

エージェントを呼び出す – エージェントコードは GetResourceOauth2Token API を呼び出して認可 URL を取得します。これは、元のエージェントユーザーが所有しているアプリケーションまたはリソースにアクセスしたい場合です。

認可 URL の生成 – AgentCore Identity は、ユーザーがアクセスに移動して同意するための認可 URL とセッション URI を生成します。

アクセストークンの認可と取得 – ユーザーは認可 URL に移動し、エージェントが自分のリソースにアクセスするための同意を付与します。その後、AgentCore Identity は、承認リクエストの送信元ユーザーを含む情報を使用して、ユーザーのブラウザを HTTPS アプリケーションエンドポイントにリダイレクトします。この時点で、HTTPS アプリケーションエンドポイントは、元のエージェントユーザーがアプリケーションの現在ログインしているユーザーと同じかどうかを決定します。一致すると、アプリケーションエンドポイントは を呼び出しCompleteResourceTokenAuthて、AgentCore Identity がアクセストークンを取得して保存できるようにします。

エージェントを再呼び出ししてアクセストークンを取得する – アプリケーションが有効なレスポンスを返すと、エージェントアプリケーションは、最初にユーザーにリクエストされた OAuth2.0 アクセストークンを取得できるようになります。ユーザーが一致しない場合、アプリケーションは何もしないか、試行を記録します。

アプリケーション URL の作成 – ユーザー向けブラウザアプリケーションでは、ユーザーブラウザからアクセスでき、ブラウザリダイレクトからのリクエストを受け入れることができる新しい URL を作成してホストします。このページは、ユーザーがエージェントセッションを続行できるアプリケーションページにリダイレクトするか、現在アクティブなエージェントセッションを返すようにユーザーに指示する基本的なウェブページをレンダリングします。実装の後半では、このページは現在のユーザーのアクティブなセッションの検証に使用されるため、このページはアプリケーションユーザーセッションデータにアクセスして維持することもできます。

例えば、アプリケーションでは、ユーザーが などのプライマリアプリケーションページでエージェントとやり取りする場合がありますhttps://myagentapp.com/assistant。このような新しい URL を公開するとhttps://myagentapp.com/callback、プライマリアプリケーションページにリダイレクトされます。/callback エンドポイントの実際のコードロジックは、このガイドに従って後で更新されます。

アプリケーション URL を使用してワークロード ID を更新する – (AgentCore CLI を介してローカルでテストする場合はスキップできます) AgentCore Identity がリダイレクトするアプリケーション URL を作成してホストしたら、アプリケーション URL が AllowedResourceOauth2ReturnUrl として登録されるようにワークロード ID を更新します。使用する IAM 認証情報に、新しいワークロード ID を作成するか、既存のワークロード ID を更新するかUpdateWorkloadIdentityに応じて、 CreateWorkloadIdentityまたは を呼び出すアクセス許可があることを確認します。

UpdateWorkloadIdentity API コールの例:

aws bedrock-agentcore-control update-workload-identity --name GoogleCalendarAgent \
--allowed-resource-oauth2-return-urls https://myagentapp.com/callback

AgentCore Identity で OAuth 2.0 認証情報プロバイダーを作成する – OAuth 2.0 認証情報プロバイダーを完全に登録するには、 CreateOauth2CredentialProviderと UpdateOauth2CredentialProvider を呼び出すためのアクセス許可が必要です。以下の手順に従ってください。

CompleteResourceTokenAuth を呼び出すためのコードハンドラーを追加する – OAuth 2.0 認証情報プロバイダーを作成したら、アプリケーション URL ハンドラーで CompleteResourceTokenAuth API を呼び出すためのコードと IAM アクセス許可を追加します。CompleteResourceTokenAuth API を呼び出す場合、アプリケーションは、OAuth 2.0 user_id 認可フローに関係するユーザーとエージェントアプリケーションを表すワークロードアクセストークンを生成するために使用された元のインバウンド ID プロバイダー OAuth トークンまたは文字列を提示する必要があります。この情報は、ユーザーのブラウザのアクティブなアプリケーションセッション (通常はブラウザ Cookie またはブラウザのローカルストレージ) から取得する必要があり、リモートセッションキャッシュからプルしないでください。

さらに、AgentCore Identity によって生成される各認可 URL は、独自のセッション URI で一意に識別されます。このセッション URI は、セッションを目的のユーザーとバインドするために、ユーザー識別子と一緒に提示する必要があります。

サンプルアプリケーションコード:

def _handle_3lo_callback(self, request: Request) -> JSONResponse:
    session_id = request.query_params.get("session_id")

    if not session_id:
        console.print("Missing session_id in OAuth2 3LO callback")
        return JSONResponse(status_code=400, content={"message": "missing session_id query parameter"})

    session_details = validate_session_cookies(request.cookies.get('my-application-cookie'))

    user_id = None
    if oauth2_config:
        user_id = session_details.get(USER_ID)

    if not user_id:
        console.print(f"Missing {USER_ID} in session_details")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    console.print(f"Handling 3LO callback for workload_user_id={user_id} | session_id={session_id}", soft_wrap=True)

    region = agent_config.aws.region
    if not region:
        console.print("AWS Region not configured")
        return JSONResponse(status_code=500, content={"message": "Internal Server Error"})

    identity_client = IdentityClient(region)
    identity_client.complete_resource_token_auth(
        session_uri=session_id, user_identifier=UserIdIdentifier(user_id=user_id)
    )

    return JSONResponse(status_code=200, content={"message": "OAuth2 3LO flow completed successfully"})

テスト – セットアップが完了したら、統合をテストする準備が整います。まず を呼び出しGetResourceOauth2Token、ブラウザで返される認可 URL に移動します。OAuth 2.0 リソースプロバイダーで認可を完了すると、ブラウザがアプリケーション URL にリダイレクトされ、CompleteResourceTokenAuthAPI が呼び出されます。アプリケーションが有効なレスポンスを返すと、エージェントアプリケーションは、最初にユーザーにリクエストされた OAuth 2.0 アクセストークンを取得できるようになります。これらのトークンは、 GetResourceOauth2Token API を呼び出すことで取得できます。