Mit dem Authentifizierungsmanager mit zweiseitigem OAuth authentifizieren

Wenn Ihre KI-Agenten sich mit ihrer eigenen Berechtigung bei externen Tools wie ServiceNow oder Salesforce authentifizieren sollen, konfigurieren Sie die ausgehende Authentifizierung mit 2-legged-OAuth-Anbietern (Client Credentials) im Authentifizierungsmanager für KI-Agentenidentitäten.

Bei 2‑legged OAuth-Authentifizierungsanbietern werden Anmeldedaten und Tokens für Sie verwaltet. Dadurch entfällt die Notwendigkeit, benutzerdefinierten Code für die Verarbeitung von Authentifizierungsabläufen zu schreiben.

Zweibeiniger OAuth-Workflow

Bei der 2-legged-OAuth-Authentifizierung wird die Identität des Agents verwendet und es ist keine Einwilligung des Nutzers erforderlich. Google verwaltet die Speicherung der Clientanmeldedaten. Wenn Sie das Agent Development Kit (ADK) verwenden, werden die resultierenden Zugriffstokens automatisch abgerufen und in die Header für den Toolaufruf eingefügt.

Hinweis

Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.
Aktivieren Sie die Agent Identity Connector API.
Rollen, die zum Aktivieren von APIs erforderlich sind
Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen
API aktivieren
Agent erstellen und bereitstellen.
Rufen Sie die Client-ID und den Clientschlüssel der Drittanbieteranwendung ab, mit der Sie eine Verbindung herstellen möchten.
Prüfen Sie, ob Sie die Rollen haben, die für diese Aufgabe erforderlich sind.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwenden eines 2-legged-Agent-Identitätsanbieters benötigen:

So erstellen Sie Authentifizierungsanbieter:
- IAM Connector Admin (roles/iamconnectors.admin)
- IAM Connector Editor (roles/iamconnectors.editor)
So verwenden Sie Authentifizierungsanbieter:
- IAM Connector User (roles/iamconnectors.user)
- Standardzugriff für Agent (roles/aiplatform.agentDefaultAccess)
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Vertex AI-Nutzer (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Erstellen und Verwenden eines 2-legged-Authentifizierungsanbieters für Agent Identity erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen 2-legged-Agent-Identitätsanbieter zu erstellen und zu verwenden:

So erstellen Sie Authentifizierungsanbieter: iamconnectors.connectors.create
So verwenden Sie Authentifizierungsanbieter:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Anbieter für die 2-Faktor-Authentifizierung erstellen

Erstellen Sie einen Authentifizierungsanbieter, um die Konfiguration und Anmeldedaten für Drittanbieteranwendungen zu definieren.

Verwenden Sie die Google Cloud Console oder die Google Cloud CLI, um einen Anbieter für die 2-legged-Authentifizierung zu erstellen.

Console

Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.
Zur Agent Registry
Klicken Sie auf den Namen des Agenten, für den Sie einen Authentifizierungsanbieter erstellen möchten.
Klicken Sie auf Identität.
Klicken Sie im Bereich Authentifizierungsanbieter auf Authentifizierungsanbieter hinzufügen.
Geben Sie im Bereich Authentifizierungsanbieter hinzufügen einen Namen und eine Beschreibung ein.

Der Name darf nur Kleinbuchstaben, Ziffern oder Bindestriche enthalten, darf nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.
Wählen Sie in der Liste OAuth Type (OAuth-Typ) die Option OAuth (2 legged) (OAuth [2-beinig]) aus.
Klicken Sie auf Erstellen und fortfahren.
Wenn Sie der Identität Ihres Agents die Berechtigung zur Verwendung des Authentifizierungsanbieters erteilen möchten, klicken Sie auf Zugriff gewähren.
Dadurch wird der Agent-Identität in der Ressource des Authentifizierungsanbieters automatisch die Rolle Connector User (roles/iamconnectors.user) zugewiesen.
Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
- Client-ID
- Client-Secret
- Token-URL
Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Auth Providers (Authentifizierungsanbieter) angezeigt.

Google Cloud CLI

Authentifizierungsanbieter erstellen:

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"

Wenn Sie der Identität Ihres Agents die Berechtigung zur Verwendung von Authentifizierungsanbietern erteilen möchten, aktualisieren Sie die IAM-Zulassungsrichtlinie für das Projekt oder den jeweiligen Authentifizierungsanbieter und weisen Sie dem Agent-Prinzipal die Rolle Connector User (roles/iamconnectors.user) zu.

Die Agent-Identität basiert auf dem Branchenstandard SPIFFE-ID-Format. In IAM-Zulassungsrichtlinien werden Agent-Identitäten mit Hauptkonto-IDs bezeichnet.
Auf Projektebene (gcloud)

Wenn Sie die Rolle auf Projektebene zuweisen, kann der Agent jeden Authentifizierungsanbieter in diesem Projekt verwenden.
- Führen Sie den folgenden Befehl aus, um einem einzelnen Agent Zugriff auf Auth-Anbieter in einem Projekt zu gewähren:
  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"
- Führen Sie den folgenden Befehl aus, um allen Agents in einem Projekt Zugriff auf Authentifizierungsanbieter zu gewähren:
  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"
Connector-Ebene (curl)

Wenn Sie einem einzelnen Agent Zugriff auf einen bestimmten Authentifizierungsanbieter gewähren möchten, verwenden Sie die setIamPolicy API. Mit diesem Befehl wird jede vorhandene Zulassungsrichtlinie für die Ressource überschrieben.
```
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"
```
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Google Cloud Projekt-ID
- AUTH_PROVIDER_NAME: Der Name des Authentifizierungsanbieters.
- ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.
- PROJECT_NUMBER: Ihre Google Cloud Projektnummer.
- LOCATION: Der Speicherort für Ihren Agenten, z. B. us-central1.
- ENGINE_ID: Die ID Ihrer Reasoning Engine.

Im Agent-Code authentifizieren

Sie können das ADK verwenden, um Ihren KI-Agenten zu authentifizieren.

ADK

Verweisen Sie im Code Ihres KI-Agenten mit dem MCP-Toolset im ADK auf den Authentifizierungsanbieter.

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

Verweisen Sie im Code Ihres Agenten mit einem authentifizierten Funktionstool im ADK auf den Authentifizierungsanbieter.

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

Verweisen Sie im Code Ihres Agenten mit dem MCP-Toolset für die Agent Registry im ADK auf den Authentifizierungsanbieter.

  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],
)

Abhängigkeiten für lokale Tests installieren

Wenn Sie Ihren Agenten lokal in einer virtuellen Umgebung testen möchten, installieren Sie die folgenden erforderlichen Abhängigkeiten:

Erstellen und aktivieren Sie eine virtuelle Umgebung:
```
python3 -m venv env
source env/bin/activate
```

Installieren Sie die erforderlichen Pakete:

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

Agent bereitstellen

Wenn Sie Ihren Agent in Google Cloudbereitstellen, muss die Agent-Identität aktiviert sein.

Wenn Sie in Agent Runtime bereitstellen, verwenden Sie das Flag 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]"],
    },
)