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

エージェントが独自の権限を使用して ServiceNow や Salesforce などの外部ツールに対して認証を行えるようにするには、Agent Identity 認証マネージャーで 2-legged OAuth（クライアント認証情報）認証プロバイダを使用してアウトバウンド認証を構成します。

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

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

2-legged OAuth のワークフロー

2-legged OAuth 認証プロバイダはエージェントの ID を使用するため、ユーザーの同意は必要ありません。クライアント認証情報の保存は Google が管理します。Agent Development Kit（ADK）を使用すると、結果のアクセス トークンが自動的に取得され、ツール呼び出しヘッダーに挿入されます。

始める前に

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

2. Agent Identity API を有効にします。

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

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

   API の有効化

3. エージェントを作成してデプロイします。

4. 接続するサードパーティ アプリケーションからクライアント ID とクライアント シークレット を取得します。

5. このタスク を完了するために必要なロールが付与されていることを確認します。

必要なロール

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

• 認証プロバイダを作成するには:
  • Agent Identity 管理者 (roles/agentidentity.admin)
  • Agent Identity 編集者 （roles/agentidentity.editor）
• 認証プロバイダを使用するには:
  • Agent Identity ユーザー （roles/agentidentity.user）
  • エージェントのデフォルト アクセス （roles/aiplatform.agentDefaultAccess）
  • エージェント コンテキスト編集者 （roles/aiplatform.agentContextEditor）
  • Vertex AI ユーザー （roles/aiplatform.user）
  • Service Usage コンシューマー （roles/serviceusage.serviceUsageConsumer）

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

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

必要な権限

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

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

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

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

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

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

コンソール

1. コンソール Google Cloud で、[エージェント レジストリ] ページに移動します。

   エージェント レジストリに移動

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

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

   名前に使用できるのは、英小文字、数字、ハイフンに限られます。先頭は英小文字にする必要があり、末尾にハイフンは使用できません。

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

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

9. [認証プロバイダの認証情報] セクションで、次の情報を入力します。
   • クライアント ID
   • Client Secret
   • トークン URL
10. [プロバイダ構成を追加] をクリックします。

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

gcloud CLI

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

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --two-legged-oauth-client-id="CLIENT_ID" \
       --two-legged-oauth-client-secret="CLIENT_SECRET" \
       --two-legged-oauth-token-url="TOKEN_URL"

2. 認証プロバイダがリストに表示され、状態が ENABLED であることを確認します。

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

3. エージェントとローカル開発 環境が認証プロバイダから認証情報を取得できるように、アクセス権を付与します。デプロイされたエージェントと個人のユーザー アカウントが認証プロバイダにアクセスできるようにするには、認証プロバイダ リソースにAgent Identity ユーザー（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: 認証プロバイダの名前（jira-mcp-2lo-authprovider など）。
• CLIENT_ID: サードパーティ サービスから生成した OAuth クライアント ID。
• CLIENT_SECRET: サードパーティ サービスから生成した OAuth クライアント シークレット。
• TOKEN_URL: トークン サーバーの URL（https://oauth2.googleapis.com/token など）。
• ORGANIZATION_ID: あなたの Google Cloud 組織の ID。
• PROJECT_NUMBER: あなたの Google Cloud プロジェクトの番号。
• ENGINE_ID: デプロイされた Reasoning Engine エージェントの ID。
• USER_EMAIL: 個人のユーザー アカウントのメールアドレス。

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

エージェントを認証するには、ADK を使用します。

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 the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# Create the Google Cloud 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"
)

# 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="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# 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="MODEL_NAME",
    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 ツールセットを使用して、エージェントのコードで認証プロバイダを参照します。

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.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
from google.adk.integrations.agent_registry import AgentRegistry

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

# Create Google Cloud 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"
    )
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

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

  

ローカルテスト用の依存関係をインストールする

仮想環境でエージェントをローカルでテストするには、次の必要な依存関係をインストールします。

1. 仮想環境を作成して有効にします。

   python3 -m venv env
   source env/bin/activate

2. 必要なパッケージをインストールします。

   pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

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

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

Agent CLI

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

1. エージェント アプリケーション フォルダに、Agent Identity を有効にする構成ファイル .agent_engine_config.json を作成します。

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

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

   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 フラグを使用します。

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# 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")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(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 など）。

次のステップ

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