認証マネージャーで 3-legged OAuth を使用して認証する

特定のエンドユーザーに代わって外部ツールやサービス（Jira タスクや GitHub リポジトリなど）へのアクセス権をエージェントに付与するには、Agent Identity Auth Manager で 3-legged OAuth 認証プロバイダを構成します。

3-legged OAuth 認証プロバイダは、認証情報とトークンを管理することで、認証フローを処理するカスタムコードを不要にします。

重要: このドキュメントでは、Agent Identity API を使用して認証する方法について説明します。IAM Connectors API（プレビュー）は一般提供されないため、Agent Identity API を使用することをおすすめします。IAM Connectors API を使用している場合は、Agent Identity API に移行します。

3-legged OAuth ワークフロー

3-legged OAuth 認証プロバイダでは、エージェントがユーザーの代わりにリソースにアクセスするため、ユーザーの同意が必要です。

1. プロンプトとリダイレクト: チャット インターフェースは、ユーザーにログインを求めるプロンプトを表示し、サードパーティ アプリケーションの同意ページにリダイレクトします。
2. 同意と保存: ユーザーが権限を付与すると、Agent Identity Auth Manager は、生成された OAuth トークンを Google が管理する認証情報ボルトに保存します。
3. 挿入: Agent Development Kit（ADK）を使用すると、エージェントは認証プロバイダからトークンを自動的に取得し、ツール呼び出しヘッダーに挿入します。

始める前に

1. 正しい認証方法を選択していることを確認します。

2. Agent Identity API が有効になっていない場合は、有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。

   API の有効化

3. エージェントを作成してデプロイする。
4. ユーザーのログイン プロンプトとサードパーティの同意ページへのリダイレクトを処理するフロントエンド アプリケーションがあることを確認します。
5. このタスクを完了するために必要なロールが付与されていることを確認します。

必要なロール

3-legged 認証プロバイダの作成と使用に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• 認証プロバイダを作成するには:
  • エージェント ID 管理者 （roles/agentidentity.admin）
  • エージェント ID 編集者 （roles/agentidentity.editor）
• 認証プロバイダを使用するには:
  • エージェント ID ユーザー （roles/agentidentity.user）
  • Vertex AI ユーザー （roles/aiplatform.user）
  • Service Usage コンシューマー （roles/serviceusage.serviceUsageConsumer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、3-legged 認証プロバイダを作成して使用するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

3-legged 認証プロバイダを作成して使用するには、次の権限が必要です。

• 認証プロバイダを作成するには: agentidentity.authProviders.create
• 認証プロバイダを使用するには:
  • agentidentity.authProviders.retrieveCredentials
  • aiplatform.endpoints.predict
  • aiplatform.sessions.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

3-legged 認証プロバイダを作成する

認証プロバイダを作成して、サードパーティ アプリケーションの構成と認証情報を定義します。

3-legged 認証プロバイダを作成するには、 Google Cloud コンソール、Google Cloud CLI、または REST API を使用します。

コンソール

1. Google Cloud コンソールで、[Agent Registry] ページに移動します。

   Agent Registry に移動

2. 認証プロバイダを作成するエージェントの名前をクリックします。
3. [Identity] をクリックします。
4. [認証プロバイダ] セクションで、[ 認証プロバイダを追加] をクリックします。

5. [認証プロバイダを追加] ペインで、名前と説明を入力します。

   名前に使用できるのは、英小文字、数字、ハイフンに限られます。先頭は英小文字とし、末尾は英小文字、数字のいずれかにします。

6. [OAuth Type] リストから [OAuth (3 legged)] を選択します。
7. [作成して続行] をクリックします。
8. エージェント ID に認証プロバイダの使用権限を付与するには、[アクセスを許可] をクリックします。

   このプロセスにより、認証プロバイダ リソースのエージェント ID に Agent Identity User（roles/agentidentity.user）ロールが自動的に割り当てられます。

9. コールバック URL をコピーします。
10. 別のタブで、サードパーティの OAuth クライアント アプリケーションにコールバック URL を登録します。
11. [認証プロバイダの認証情報] セクションで、次の情報を入力します。
    • クライアント ID
    • クライアント シークレット
    • トークン URL
    • 認可 URL
    • デフォルトの続行 URI: 省略可。実行時に続行 URI が指定されていない場合に、ユーザーが同意した後にリダイレクトするデフォルトのリダイレクト URI を入力します。
12. [Add provider config] をクリックします。

新しく作成された認証プロバイダが [認証プロバイダ] リストに表示されます。

gcloud CLI

1. OAuth クライアント アプリケーションを構成してクライアントを登録し、クライアント ID とクライアント シークレットを取得します。そのセクションのテンプレートを使用して、リダイレクト URI を指定します。

2. クライアント認証情報を使用して認証プロバイダを作成します。

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --project="PROJECT_ID" \
       --location="LOCATION" \
       --three-legged-oauth-client-id="CLIENT_ID" \
       --three-legged-oauth-client-secret="CLIENT_SECRET" \
       --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
       --three-legged-oauth-token-url="TOKEN_URL" \
       --three-legged-oauth-default-continue-uri="DEFAULT_CONTINUE_URI"

   次のように置き換えます。

   • AUTH_PROVIDER_NAME: 認証プロバイダの名前。
   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
   • LOCATION: 認証プロバイダが作成されるリージョン。
   • CLIENT_ID: OAuth クライアント アプリケーションのクライアント ID。
   • CLIENT_SECRET: OAuth クライアント アプリケーションのクライアント シークレット。
   • AUTHORIZATION_URL: ユーザーが同意を付与するためにリダイレクトされる認可サーバーのエンドポイント。
   • TOKEN_URL: 認可サーバーのトークン交換エンドポイント。
   • DEFAULT_CONTINUE_URI: 省略可。ユーザーが同意を付与した後に送信されるデフォルトのリダイレクト URI。実行時に継続 URI が指定されていない場合に使用されます。
3. 認証プロバイダがリストに表示され、その状態が ENABLED であることを確認します。

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

4. エージェントとローカル開発環境が認証プロバイダから認証情報を取得できるように、アクセス権限を付与します。デプロイされたエージェントと個人のユーザー アカウントが認証プロバイダにアクセスできるようにするには、認証プロバイダ リソースに対するエージェント ID ユーザー（roles/agentidentity.user）ロールを付与します。

   1. デプロイされたエージェントの SPIFFE ID（エージェント ID）にアクセス権を付与します。

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

   2. ローカルでの開発とテスト（adk web）のために、個人のユーザー アカウントにアクセス権を付与します。

      gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/agentidentity.user" \
          --member="user:USER_EMAIL"

次のように置き換えます。

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: 認証プロバイダとエージェントがデプロイされているロケーション（例: us-west1）。
• AUTH_PROVIDER_NAME: 認証プロバイダの名前（例: bigquery-mcp-3lo-authprovider）。
• AUTHORIZATION_URL: 認可サーバーの URL（例: https://accounts.google.com/o/oauth2/v2/auth）。
• TOKEN_URL: トークン サーバーの URL（例: https://oauth2.googleapis.com/token）。
• CLIENT_ID: サードパーティ サービスから生成した OAuth クライアント ID。
• CLIENT_SECRET: サードパーティ サービスから生成した OAuth クライアント シークレット。
• ORGANIZATION_ID: 実際の Google Cloud 組織 ID。
• PROJECT_NUMBER: Google Cloud プロジェクトの番号。
• ENGINE_ID: デプロイされた推論エンジン エージェントの ID。
• USER_EMAIL: 個人ユーザー アカウントのメールアドレス。

REST

1. OAuth クライアント アプリケーションを構成してクライアントを登録し、クライアント ID とクライアント シークレットを取得します。そのセクションのテンプレートを使用して、リダイレクト URI を指定します。

2. 認証プロバイダを作成します。

   Agent Identity API の authProviders.create メソッドは、プロジェクトとロケーションに 3-legged OAuth 認証プロバイダを作成します。

   リクエストのデータを使用する前に、次のように置き換えます。

   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。プロジェクト ID は英数字からなる文字列です（例: my-project）。
   • LOCATION: 認証プロバイダとエージェントがデプロイされているロケーション（例: us-west1）。
   • AUTH_PROVIDER_NAME: 認証プロバイダの名前（例: bigquery-mcp-3lo-authprovider）。名前に使用できるのは、英小文字、数字、ハイフンに限られます。先頭は英小文字とし、末尾は英小文字、数字のいずれかにします。
   • CLIENT_ID: サードパーティ サービスから生成した OAuth クライアント ID。
   • CLIENT_SECRET: サードパーティ サービスから生成した OAuth クライアント シークレット。
   • AUTHORIZATION_URL: 認可サーバーの URL（例: https://accounts.google.com/o/oauth2/v2/auth）。
   • TOKEN_URL: トークン サーバーの URL（例: https://oauth2.googleapis.com/token）。
   • DEFAULT_CONTINUE_URI: 省略可。実行時に続行 URI を指定しない場合に、ユーザーが同意を付与した後にユーザーをリダイレクトするデフォルトの URI。

   HTTP メソッドと URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

   リクエストの本文（JSON）:

   {
     "authProviderTypeParams": {
       "threeLeggedOauth": {
         "clientId": "CLIENT_ID",
         "clientSecret": "CLIENT_SECRET",
         "authorizationUrl": "AUTHORIZATION_URL",
         "tokenUrl": "TOKEN_URL",
         "defaultContinueUri": "DEFAULT_CONTINUE_URI"
       }
     }
   }
   

   リクエストを送信するには、次のいずれかのオプションを展開します。

   curl（Linux、macOS、Cloud Shell）

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME"

   PowerShell（Windows）

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME" | Select-Object -Expand Content

   API Explorer（ブラウザ）

   リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

   次のような JSON レスポンスが返されます。

   {
     "name": "projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider",
     "createTime": "2026-04-03T21:15:41.367155Z",
     "updateTime": "2026-04-03T21:15:41.367155Z",
     "authProviderTypeParams": {
       "threeLeggedOauth": {
         "clientId": "my-oauth-client-id",
         "redirectUrl": "https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback",
         "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
         "tokenUrl": "https://oauth2.googleapis.com/token",
         "defaultContinueUri": "http://localhost:8501/validateUserId"
       }
     },
     "state": "ENABLED"
   }
   

3. デプロイされたエージェントと個人のユーザー アカウントが認証プロバイダから認証情報を取得できるようにするには、認証プロバイダ リソースに対するエージェント ID ユーザー（roles/agentidentity.user）ロールを付与します。

   Agent Identity API の authProviders.setIamPolicy メソッドは、認証プロバイダ リソースに許可ポリシーを設定します。

   リクエストのデータを使用する前に、次のように置き換えます。

   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。プロジェクト ID は英数字からなる文字列です（例: my-project）。
   • LOCATION: 認証プロバイダとエージェントがデプロイされているロケーション（例: us-west1）。
   • AUTH_PROVIDER_NAME: 認証プロバイダの名前。
   • ORGANIZATION_ID: 実際の Google Cloud組織 ID。
   • PROJECT_NUMBER: エージェントがデプロイされているプロジェクトの数値 Google Cloud プロジェクト番号（例: 987654321098）。
   • ENGINE_ID: デプロイされた推論エンジン エージェントの ID。
   • USER_EMAIL: 個人ユーザー アカウントのメールアドレス。

   HTTP メソッドと URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

   リクエストの本文（JSON）:

   {
     "policy": {
       "bindings": [
         {
           "role": "roles/agentidentity.user",
           "members": [
             "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
             "user:USER_EMAIL"
           ]
         }
       ]
     }
   }
   

   リクエストを送信するには、次のいずれかのオプションを展開します。

   curl（Linux、macOS、Cloud Shell）

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy"

   PowerShell（Windows）

   注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

   リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy" | Select-Object -Expand Content

   API Explorer（ブラウザ）

   リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

   次のような JSON レスポンスが返されます。

   {
     "version": 1,
     "etag": "BwYKmjvelug=",
     "bindings": [
       {
         "role": "roles/agentidentity.user",
         "members": [
           "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
           "user:[e-mail]"
         ]
       }
     ]
   }
   

OAuth クライアント アプリケーションを構成する

OAuth クライアント認証情報を登録する前に、サードパーティの認可サーバー（Google、GitHub、Jira など）からクライアント ID とクライアント シークレットを取得します。

Google Cloudの外部のサードパーティ サービスに接続する場合は、そのサービスのデベロッパー ポータルから OAuth クライアント認証情報を取得し、このセクションの手順をスキップします。

リダイレクト URI を登録する

OAuth クライアント認証情報を構成するときは、認証プロバイダ専用のコールバック リダイレクト URI を登録する必要があります。

1. 次のテンプレートを使用してリダイレクト URI を作成します。

   https://agentidentitycredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/oauthcallback

   次のように置き換えます。

   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
   • LOCATION: 認証プロバイダがデプロイされるリージョン（例: us-west1）。
   • AUTH_PROVIDER_NAME: 認証プロバイダの名前。

   次に例を示します。

   https://agentidentitycredentials.googleapis.com/v1/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback

2. Google Cloud サービス（BigQuery など）に接続する場合は、 Google Cloud コンソールで同意画面を構成し、OAuth クライアント認証情報を作成できます。

   1. OAuth 同意画面を構成します。

      1. Google Cloud コンソールで、[API とサービス] > [OAuth 同意画面] ページに移動します。

         [API とサービス] > [OAuth 同意画面] に移動

      2. [アプリ情報] セクションで、アプリケーション名（BigQuery Manager Application など）とサポートメールを入力します。
      3. [対象] セクションで、[内部] または [外部] を選択します。
      4. 通知を受け取るための連絡先情報を入力します。
      5. Google API サービスのユーザーデータに関するポリシーを読み、同意します。
      6. [完了] をクリックします。

   2. OAuth クライアント認証情報を作成します。

      1. Google Cloud コンソールで、[API とサービス] > [OAuth 同意画面] > [クライアント] ページに移動します。

         [API とサービス] > [OAuth 同意画面] > [クライアント] に移動します。

      2. [認証情報を作成] > [OAuth クライアント ID] をクリックします。
      3. リストから [ウェブ アプリケーション] オプションを選択します。
      4. OAuth クライアントのわかりやすい名前を入力します。
      5. [承認済みのリダイレクト URI] セクションで、[URI を追加] をクリックして、作成したリダイレクト URI を入力します。
      6. [作成] をクリックします。[OAuth クライアントを作成しました] ダイアログで、生成されたクライアント ID とクライアント シークレットの値をコピーします。

エージェント コードで認証する

エージェントを認証するには、ADK を使用するか、Agent Identity API を直接呼び出します。

注: 次のサンプルでは、モジュール レベルで認証プロバイダを登録します。これは、エージェントをローカルで実行する場合や、Agent CLI を使用してデプロイする場合に機能します。Vertex AI Python SDK を使用してデプロイする場合は、デプロイされたコンテナで実行されるように、代わりに set_up() に認証プロバイダを登録します。詳細については、エージェントをデプロイするをご覧ください。

認証情報をリクエストするときに、アプリケーションは、ユーザーが同意を付与した後にリダイレクトされる continue_uri を指定します。認証プロバイダの作成時に default_continue_uri を構成した場合、エージェント コードで continue_uri を指定することは任意です。

ADK

ADK の MCP ツールセットを使用して、エージェントのコードで認証プロバイダを参照します。

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted.
# Optional if default_continue_uri is configured on the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME (ex. gemini-2.5-flash)",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

例: BigQuery MCP への接続

次の例は、エージェントを BigQuery MCP サーバーに接続する agent.py 構成を示しています。

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# URI to redirect user to after consent is granted.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

ADK の認証済み関数ツールを使用して、エージェントのコードで認証プロバイダを参照します。

import httpx
from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

ADK の Agent Registry MCP ツールセットを使用して、エージェントのコードで認証プロバイダを参照します。

このフローの認証スキームは作成しません。MCP サーバーのアウトバウンド バインディングには、使用する認証プロバイダがすでに記録されています。continue_uri を渡して、同意後にユーザーをリダイレクトする場所を指定します。

注意: 認証プロバイダ、MCP サーバー、Agent Registry クライアントには同じリージョンを使用してください。認証プロバイダは global ロケーションでは使用できないため、location="global" を設定すると、アウトバウンド バインディングの作成が失敗し、エラー Location of auth provider does not match location of binding が発生します。

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    continue_uri=CONTINUE_URI,
)

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

API を直接呼び出す

ADK を使用していない場合、エージェントは agentidentitycredentials.retrieveCredentials API を呼び出してトークンを取得する必要があります。

これはマルチステップの OAuth フローであるため、エージェントはオペレーションのライフサイクルを処理する必要があります。

1. 最初のリクエスト: エージェント機能による通話が retrieveCredentials を呼び出します。
2. 同意が必要: ユーザーが同意していない場合、API は結果を uri_consent_required として含むレスポンスを返します。これには authorization_uri と consent_nonce が含まれます。
3. フロントエンドのリダイレクト: アプリケーションはユーザーを authorization_uri にリダイレクトする必要があります。
4. 完了: ユーザーが同意したら、consent_nonce を使用して FinalizeCredentials を呼び出し、フローを完了してトークンを取得します。

クライアントサイド アプリケーションを更新する

注: クライアント UI はリモート エージェントでのみ機能します。

3-legged OAuth のユーザー ログインとリダイレクトを処理するには、クライアントサイド アプリケーションで次の手順を実装して、ユーザーの同意を管理し、会話を再開する必要があります。

サンプル UI サーバー

uvicorn を使用する完全なサンプル UI サーバーをダウンロードして実行できます。始める前に、GitHub アカウントがあり、pip がインストールされていることを確認してください。

サンプル UI サーバーを設定して実行する手順は次のとおりです。

1. adk-python GitHub リポジトリのクローンを作成します。

   git clone https://github.com/google/adk-python.git

2. リポジトリに移動して、Python 仮想環境を有効にします。

   cd adk-python
   python3 -m venv .venv
   source .venv/bin/activate

3. サンプル UI クライアント ディレクトリに移動します。

   cd contributing/samples/integrations/gcp_auth/client

4. クライアントの依存関係をインストールします。

   pip install -r requirements.txt

5. サーバーを起動する前に、AGENT_PROJECT_DIR 環境変数を設定して、エージェント コードが配置されているディレクトリを指定します。それ以外の場合、アプリケーションはデフォルトで、クライアント ディレクトリの親フォルダでエージェントを探します。

   uvicorn を使用してサンプル UI サーバーを起動します。ポートが OAuth クライアントで構成されているリダイレクト URI と一致していることを確認します。

   export AGENT_PROJECT_DIR="/path/to/your/agent_project"
   uvicorn main:app --port 8501 --reload

6. ブラウザで http://localhost:8501 を開きます。（注: OAuth リダイレクト URL には localhost ホスト名が必要なため、127.0.0.1 ではなく localhost を使用する必要があります）。設定を指定し、[Save & Apply Settings] をクリックして、エージェントを操作します。

カスタム UI アプリケーション

これらの機能をカスタム UI アプリケーションに直接実装する手順は次のとおりです。

• 承認トリガーを処理する
• ユーザー検証エンドポイントを実装する
• エージェントとの会話を再開する

承認トリガーを処理する

エージェントがユーザーの同意を必要とする場合、adk_request_credential 関数呼び出しを返します。アプリケーションは、この呼び出しをインターセプトして、ユーザー認証ダイアログまたはリダイレクトを開始する必要があります。

認証プロバイダから提供された consent_nonce を記録して、セッション コンテキストを管理します。このノンスは、検証ステップでユーザーを確認するために必要です。ユーザーが同意した後にフローを再開しやすくするため、セッション内に auth_config と auth_request_function_call_id の値を保存します。

if (fc := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(fc)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, AUTH_PROVIDER_NAME, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = (
                fc.get('id') if isinstance(fc, dict)
                else getattr(fc, 'id', None)
            )
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    ec = auth_config.exchanged_auth_credential
    if ec and ec.oauth2:
        oauth2 = ec.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

ユーザー検証エンドポイントを実装する

ウェブサーバーに検証エンドポイントを実装します（構成時に continue_uri として指定した URI と同じ URI）。このエンドポイントは、次のことを行う必要があります。

1. user_id_validation_state、auth_provider_name、uuid をクエリ パラメータとして受け取ります。
2. セッション ストレージから user_id と consent_nonce の値を取得します。複数の認可フローが同時に実行される場合は、uuid を使用して正しいセッションを照合します。
3. これらのパラメータを使用して、認証プロバイダの FinalizeCredentials API を呼び出します。
4. 成功のレスポンスを受け取ったら、認可ウィンドウを閉じます。

例: FastAPI 検証エンドポイント（main.py）

次の例は、OAuth コールバックを処理してユーザー認証情報を確定する完全な FastAPI 検証エンドポイントを示しています。

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
    auth_provider_name = request.query_params.get("auth_provider_name")
    session_id = request.cookies.get("session_id")
    session = consent_sessions.get(session_id, {})

    payload = {
        "userId": session.get("user_id"),
        "userIdValidationState": request.query_params.get(
            "user_id_validation_state"
        ),
        "consentNonce": session.get("consent_nonce"),
    }

    base_url = "https://agentidentitycredentials.googleapis.com/v1"
    finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize"

    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(finalize_url, json=payload)
            resp.raise_for_status()
    except httpx.HTTPError as e:
        err_text = e.response.text if hasattr(e, "response") else str(e)
        status = e.response.status_code if hasattr(e, "response") else 500
        return HTMLResponse(err_text, status_code=status)

    return HTMLResponse("""
        <script>
            window.close();
        </script>
        <p>Success. You can close this window.</p>
    """)

エージェントの会話を再開する

ユーザーが同意して認証ウィンドウが閉じたら、セッション データから auth_config と auth_request_function_call_id の値を取得します。会話を続けるには、これらの詳細を function_response としてエージェントへの新しいリクエストに含めます。

if (request.is_auth_resume and session.auth_request_function_call_id
    and session.auth_config):
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

エージェントをデプロイする

エージェントを Google Cloudにデプロイするときは、エージェント ID が有効になっていることを確認します。

Agent CLI

Agent Development Kit（ADK）と Agent CLI を使用している場合は、次の手順で Agent Identity を有効にしてエージェントをデプロイします。

1. エージェント アプリケーション フォルダに、.agent_engine_config.json という名前の構成ファイルを作成して、エージェント ID を有効にします。

   echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

2. Gemini Enterprise Agent Platform の Agent Runtime にエージェントをデプロイします。

   uv run adk deploy agent_engine AGENT_NAME \
       --project="PROJECT_ID" \
       --region="LOCATION"

   次のように置き換えます。

   • AGENT_NAME: エージェント アプリケーション フォルダの名前（例: maps_agent）。
   • PROJECT_ID: 実際の Google Cloudプロジェクト ID。
   • LOCATION: エージェントをデプロイするサポート対象の地域（例: us-west1）。

Python SDK

Vertex AI Python SDK を使用してプログラムでデプロイする場合は、identity_type=AGENT_IDENTITY フラグを使用します。

注意: SDK はアプリ オブジェクトをシリアル化するため、インポート時にローカル スクリプトが実行する CredentialManager.register_auth_provider() 呼び出しは、デプロイされたコンテナでは実行されません。代わりに、アプリの set_up() メソッドに認証プロバイダを登録します。このメソッドは、コンテナの起動時にランタイムによって呼び出されます。それ以外の場合、エージェントはクエリ時に No auth provider registered for custom auth scheme 'gcpAuthProviderScheme' で失敗します。詳細については、デプロイに関する考慮事項をご覧ください。

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity,mcp]>=2.7.1",
        ],
    },
)

次のように置き換えます。

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• LOCATION: エージェントをデプロイするサポート対象の地域（例: us-west1）。

次のステップ

• エージェント ID 認証に関する問題のトラブルシューティング
• エージェント ID の概要
• 認証マネージャーで 2-legged OAuth を使用して認証する
• 認証マネージャーで API キーを使用して認証する
• Agent Identity 認証プロバイダを管理する