kb-agentcore-identity

name	kb-agentcore-identity
description	AgentCore Identity（アウトバウンド認証）のナレッジ。3LO/M2M/デコレータ分離/callback等
user-invocable	true
model	sonnet

AgentCore Identity（アウトバウンド認証）

先に AWS Agent Toolkit を当たる。 この領域は aws-agents:agents-connect（アウトバウンド認証を担当） がカバーする。 このスキルは Toolkit の代わりではなく、公式どおりにやったのに動かなかったときの原因を貯めておく場所として使う。 Toolkit 側が同じ内容をカバーしたと分かった項目は、このスキルから削る（両方に置くと、更新されるのは公式側だけなのでこちらが古い情報の発生源になる）。

Bedrock AgentCore Identity を使った外部サービスとの OAuth2 連携パターンを記録する。

@requires_access_token と @tool は必ず分離する

@tool と @requires_access_token を同じ関数にスタックすると、パラメータ解析が干渉してツールが正しく動作しない（エージェントが access_token を入力パラメータとして要求してしまう）。

# ❌ NG: デコレータをスタック → パラメータ干渉
@tool
@requires_access_token(provider_name="my-provider", scopes=[...], auth_flow="USER_FEDERATION")
async def get_pages(*, access_token: str):
    ...

# ✅ OK: トークン取得とツールを分離
@requires_access_token(provider_name="my-provider", scopes=[...], auth_flow="USER_FEDERATION",
    on_auth_url=lambda url: print(f"認可URL: {url}"),
    callback_url="http://localhost:9090/oauth2/callback")
def get_token(access_token: str = ""):
    return access_token

@tool
def get_pages():
    """外部APIのページ一覧を取得する"""
    token = get_token()
    response = httpx.get("https://api.example.com/pages",
        headers={"Authorization": f"Bearer {token}"})
    return response.json()

内部関数パターン（推奨：よりコンパクト）

トークン取得関数をツール内部に定義するとファイルを分けずに済む。公式サンプル（01_outbound.py）もこの方式：

@tool
def add_calendar_event(
    summary: str,
    start_datetime: str,
    end_datetime: str,
    description: str = "",
):
    """Google Calendarに予定を追加する。"""

    @requires_access_token(
        provider_name=PROVIDER_NAME,
        scopes=["https://www.googleapis.com/auth/calendar"],
        auth_flow="USER_FEDERATION",
        on_auth_url=lambda url: print(f"認証URL: {url}"),
        callback_url="http://localhost:9090/oauth2/callback",
    )
    def call_api(access_token: str = ""):
        event = {
            "summary": summary,
            "start": {"dateTime": start_datetime, "timeZone": "Asia/Tokyo"},
            "end": {"dateTime": end_datetime, "timeZone": "Asia/Tokyo"},
        }
        resp = requests.post(
            "https://www.googleapis.com/calendar/v3/calendars/primary/events",
            headers={"Authorization": f"Bearer {access_token}"},
            json=event,
        )
        return resp.json()

    result = call_api()
    if "error" in result:
        return f"失敗: {result['error'][]}"
     

ポイント: 外側の @tool が認識するスキーマには access_token が含まれないため、LLM がユーザーにトークンを直接要求する問題が解消される。

USER_FEDERATION は同期関数でも動作する

auth_flow="USER_FEDERATION" でも def（同期関数）で定義可能。SDK 内部でポーリングをブロッキング実行する。async def + asyncio.run_until_complete() は BedrockAgentCoreApp の async コンテキストと競合するため避ける。

3LO (USER_FEDERATION) フローにはローカル callback サーバーが必要

3LO フローの callback は2段階で動作する：

1. Atlassian 等の IdP → AgentCore callback（/identities/oauth2/callback/{providerId}?code=XXX&state=YYY）→ code exchange
2. AgentCore → アプリの callback サーバー（?session_id=...）→ CompleteResourceTokenAuth を呼ぶ

callback_url に AgentCore の callback endpoint 自体を指定するとバリデーションエラーになる（GitHub Issue #801）。アプリ側で callback サーバーを立てる必要がある。

# callback_server.py（FastAPI で localhost:9090 に立てる）
from fastapi import FastAPI
from bedrock_agentcore.services.identity import IdentityClient, UserIdIdentifier

app = FastAPI()
identity_client = IdentityClient(region="us-east-1")

@app.get("/oauth2/callback")
async def handle_callback(session_id: str):
    identity_client.complete_resource_token_auth(
        session_uri=session_id,
        user_identifier=UserIdIdentifier(user_id="<user_id>"),
    )
    return {"status": "success"}

# エージェント側：callback_url を localhost に向ける
@requires_access_token(
    provider_name="my-provider",
    scopes=["read:confluence-content.all", "offline_access"],
    auth_flow="USER_FEDERATION",
    on_auth_url=lambda url: print(f"BROWSER: {url}"),
    callback_url="http://localhost:9090/oauth2/callback",
)
def get_token(access_token: str = ""):
    return access_token

セットアップ手順:

1. Workload Identity の allowedResourceOauth2ReturnUrls に http://localhost:9090/oauth2/callback を追加
2. callback サーバーを起動（uv run python callback_server.py）
3. エージェントを実行、auth URL をブラウザで開いて認可
4. callback サーバーが CompleteResourceTokenAuth を呼び、ポーリングでトークン取得

参考: 公式サンプル awslabs/amazon-bedrock-agentcore-samples の 05-Outbound_Auth_3lo/oauth2_callback_server.py

M2M (client_credentials) フローの互換性問題

AgentCore Identity の M2M フローは標準 grant_type=client_credentials を使用するが、多くの外部プロバイダーが独自仕様を持つため互換性に注意：

プロバイダー	M2M結果	原因
Zoom	❌ トークン取得成功、API拒否	grant_type=account_credentials + account_id が必要
GitHub	❌ トークン取得失敗	Token endpoint レスポンス形式が非標準
Atlassian	△ サイトアクセス権なし	サービスアカウント設定が別途必要

結論: M2M は実務上イレギュラー。3LO (USER_FEDERATION) が主流パターン。

BedrockAgentCoreApp の初期化タイムアウト

AgentCore Runtime は初期化を30秒以内に完了する必要がある。モジュールレベルで agent(...) を実行すると、3LO のポーリングで初期化がブロックされタイムアウトする。

# ❌ NG: モジュールレベルで実行 → 30秒タイムアウト
agent = Agent(tools=[my_tool])
agent("処理を実行して")

# ✅ OK: BedrockAgentCoreApp + @app.entrypoint で invoke 時に実行
app = BedrockAgentCoreApp()

@app.entrypoint
def handle_request(request, context=None):
    agent = Agent(tools=[my_tool])
    result = agent(request.get("prompt", ""))
    return {"response": str(result)}

if __name__ == "__main__":
    app.run()

トラブルシューティング

workload-identity ARN 不一致

症状: @requires_access_token で GetResourceOauth2Token の権限エラー。IAMポリシーには GetResourceOauth2Token が設定済み

原因: agentcore deploy で .agentcore.json がパッケージに含まれると、ローカルで自動生成された workload identity ID（例: workload-383171e1）が使われる。IAMポリシーのリソースARNが workload-identity/sample_identity-* のようなパターンだと不一致

解決策: IAMポリシーの workload-identity リソースをワイルドカードに拡張

{
  "Sid": "BedrockAgentCoreIdentityGetResourceOauth2Token",
  "Effect": "Allow",
  "Action": ["bedrock-agentcore:GetResourceOauth2Token"],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:token-vault/default",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:token-vault/default/oauth2credentialprovider/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:workload-identity-directory/default/workload-identity/*"
  ]
}

3LO callback で authorizationCode/state が null エラー

症状: 3LO (USER_FEDERATION) フローで、ブラウザの Atlassian 同意後に callback endpoint でバリデーションエラー

{"message":"2 validation errors detected: Value at 'authorizationCode' failed to satisfy constraint: Member must not be null; Value at 'state' failed to satisfy constraint: Member must not be null"}

原因: callback_url に AgentCore の callback endpoint を直接指定していた。3LO フローは2段階で動作し、AgentCore callback → アプリの callback サーバーへのリダイレクトが必要。

解決策: アプリ側でローカル callback サーバーを立て、callback_url をそちらに向ける（詳細は上記「3LO (USER_FEDERATION) フローにはローカル callback サーバーが必要」参照）

callback_url="http://localhost:9090/oauth2/callback"

identity_client.complete_resource_token_auth(
    session_uri=session_id,
    user_identifier=UserIdIdentifier(user_id="<user_id>"),
)

追加設定:

• Workload Identity の allowedResourceOauth2ReturnUrls に localhost URL を追加
• fastapi + uvicorn を依存関係に追加

参考: GitHub Issue #801、公式サンプル 05-Outbound_Auth_3lo/oauth2_callback_server.py