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

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

2-legged OAuth 認証プロバイダは、認証情報とトークンを管理します。これにより、認証フローを処理するカスタムコードを作成する必要がなくなります。

2-legged OAuth ワークフロー

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

始める前に

正しい認証方法を選択していることを確認します。
Agent Identity Connector API を有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。
API の有効化
エージェントを作成してデプロイします。
接続するサードパーティアプリケーションからクライアント ID とクライアントシークレット を取得します。
このタスクを完了するために必要なロールがあることを確認します。

必要なロール

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

認証プロバイダを作成するには:
- IAM Connector 管理者（roles/iamconnectors.admin）
- IAM Connector 編集者（roles/iamconnectors.editor）
認証プロバイダを使用するには:
- IAM Connector ユーザー（roles/iamconnectors.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 認証プロバイダを作成して使用するには、次の権限が必要です。

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

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

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

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

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

コンソール

コンソールで、[エージェントレジストリ] ページに移動します。 Google Cloud
エージェントレジストリに移動
認証プロバイダを作成するエージェントの名前をクリックします。
[ID] をクリックします。
[認証プロバイダ] セクションで、[ 認証プロバイダを追加] をクリックします。
[認証プロバイダを追加] パネルで、名前と説明を入力します。

名前には小文字、数字、ハイフンのみを使用できます。ハイフンで終わることはできません。小文字で始める必要があります。
[OAuth タイプ] リストから [OAuth（2-legged）] を選択します。
[作成して続行] をクリックします。
認証プロバイダを使用するエージェント ID 権限を付与するには、[アクセス権を付与] をクリックします。
これにより、認証プロバイダリソースのエージェント ID にコネクタユーザー （roles/iamconnectors.user）ロールが自動的に割り当てられます。
[認証プロバイダの認証情報] セクションに、次の情報を入力します。
- クライアント ID
- Client Secret
- トークン URL
[プロバイダ構成を追加] をクリックします。

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

Google Cloud CLI

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

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"

認証プロバイダを使用するエージェント ID 権限を付与するには、プロジェクトまたは特定の認証プロバイダの IAM 許可ポリシーを更新し、エージェントプリンシパルにコネクタユーザー （roles/iamconnectors.user）ロールを付与します。

Agent Identity は、業界標準の SPIFFE ID 形式に基づいています。IAM 許可ポリシーでは、エージェント ID はプリンシパル ID を使用して参照されます。
プロジェクトレベル（gcloud）

プロジェクトレベルでロールを付与すると、エージェントはそのプロジェクト内の任意の認証プロバイダを使用できます。
- プロジェクト内の認証プロバイダへのアクセス権を単一のエージェントに付与するには、次のコマンドを実行します。
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- プロジェクト内のすべてのエージェントに認証プロバイダへのアクセス権を付与するには、次のコマンドを実行します。
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
コネクタレベル（curl）

特定の認証プロバイダへのアクセス権を単一のエージェントに付与するには、 setIamPolicy API を使用します。このコマンドを実行すると、リソースの既存の許可ポリシーが上書きされます。
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
次のように置き換えます。
- PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- AUTH_PROVIDER_NAME: 認証プロバイダの名前。
- ORGANIZATION_ID: 実際の Google Cloud 組織 ID。
- PROJECT_NUMBER: あなたの Google Cloud プロジェクトの番号。
- LOCATION: エージェントのロケーション（例: us-central1）。
- ENGINE_ID: 推論エンジンの ID。

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

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

ADK

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

from google.adk.agents.llm_agent import LlmAgent
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 using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

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

import httpx
from google.adk.agents.llm_agent import LlmAgent
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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

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

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

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

  from google.adk.agents.llm_agent import LlmAgent
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 by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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 = LlmAgent(
    name="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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

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

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

python3 -m venv env
source env/bin/activate

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

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

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

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

Agent Runtime にデプロイする場合は、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]"],
    },
)

認証マネージャーで 2-legged OAuth を使用して認証する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

2-legged OAuth ワークフロー

始める前に

必要なロール

必要な権限

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

コンソール

Google Cloud CLI

プロジェクト レベル（gcloud）

コネクタ レベル（curl）

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

ADK

ADK

ADK

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

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

次のステップ

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

プロジェクトレベル（gcloud）

コネクタレベル（curl）

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