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-Agenten.

Durch die Verwaltung von Anmeldedaten und Tokens machen 2-legged-OAuth-Authentifizierungsanbieter benutzerdefinierten Code für die Verarbeitung von Authentifizierungsabläufen überflüssig.

Wichtig:In diesem Dokument wird beschrieben, wie Sie sich mit der Agent Identity API authentifizieren. Wir empfehlen die Verwendung der Agent Identity API, da die IAM Connectors API (Vorschau) nicht allgemein verfügbar sein wird. Wenn Sie die IAM Connectors API verwenden, migrieren Sie zur Agent Identity API.

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

1. Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.

2. Aktivieren Sie die Agent Identity API.

   Rollen, die zum Aktivieren von APIs erforderlich sind

   Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

   API aktivieren

3. KI-Agenten erstellen und bereitstellen

4. Rufen Sie die Client-ID und den Clientschlüssel der Drittanbieteranwendung ab, die Sie verbinden möchten.

5. 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-Authentifizierungsanbieters für Agent-Identitäten benötigen:

• So erstellen Sie Authentifizierungsanbieter:
  • Agent Identity Admin (roles/agentidentity.admin)
  • Bearbeiter von Agent-Identitäten (roles/agentidentity.editor)
• So verwenden Sie Authentifizierungsanbieter:
  • Agent Identity-Nutzer (roles/agentidentity.user)
  • Standardzugriff für Agenten (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 Authentifizierungsanbieter für die Agentenidentität mit zwei Schritten zu erstellen und zu verwenden:

• So erstellen Sie Authentifizierungsanbieter: agentidentity.authProviders.create
• So verwenden Sie Authentifizierungsanbieter:
  • agentidentity.authProviders.retrieveCredentials
  • aiplatform.endpoints.predict
  • aiplatform.sessions.create

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

2-legged-Authentifizierungsanbieter 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

1. Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.

   Zur Agent Registry

2. Klicken Sie auf den Namen des Agenten, für den Sie einen Authentifizierungsanbieter erstellen möchten.
3. Klicken Sie auf Identität.
4. Klicken Sie im Bereich Authentifizierungsanbieter auf Authentifizierungsanbieter hinzufügen.

5. 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.

6. Wählen Sie in der Liste OAuth Type (OAuth-Typ) die Option OAuth (2 legged) (OAuth – 2-beinig) aus.
7. Klicken Sie auf Erstellen und fortfahren.
8. Wenn Sie Ihrer Agent-Identität die Berechtigung zur Verwendung des Authentifizierungsanbieters erteilen möchten, klicken Sie auf Zugriff erlauben.

   Bei diesem Vorgang wird der Agent-Identität in der Ressource des Authentifizierungsanbieters automatisch die Rolle Agent Identity User (roles/agentidentity.user) zugewiesen.

9. Geben Sie im Bereich Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
   • Client-ID
   • Client-Secret
   • Token-URL
10. Klicken Sie auf Anbieterkonfiguration hinzufügen.

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

gcloud-CLI

1. Authentifizierungsanbieter erstellen:

   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. Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste aufgeführt ist und der Status ENABLED lautet:

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

3. Gewähren Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklungsumgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Damit Ihr bereitgestellter Agent und Ihr persönliches Nutzerkonto auf den Authentifizierungsanbieter zugreifen können, weisen Sie die Rolle Agent Identity User (roles/agentidentity.user) für die Authentifizierungsanbieterressource zu:

   1. Gewähren Sie Zugriff auf die SPIFFE-ID (KI-Agentenidentität) Ihres bereitgestellten KI-Agenten:

      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. Gewähren Sie Zugriff auf Ihr persönliches Nutzerkonto für die lokale Entwicklung und das lokale Testen (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"

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Google Cloud Projekt-ID
• LOCATION: Der Ort, an dem Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B. us-west1).
• AUTH_PROVIDER_NAME: Der Name Ihres Authentifizierungsanbieters (z. B. jira-mcp-2lo-authprovider).
• CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben.
• CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie vom Drittanbieterdienst generiert haben.
• TOKEN_URL: Die URL des Token-Servers (z. B. https://oauth2.googleapis.com/token).
• ORGANIZATION_ID: Ihre Google Cloud Organisations-ID.
• PROJECT_NUMBER: Ihre Google Cloud Projektnummer.
• ENGINE_ID: Die ID Ihres bereitgestellten Reasoning-Engine-Agents.
• USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.

Im Agent-Code authentifizieren

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

Hinweis:In den folgenden Beispielen wird der Auth-Anbieter auf Modulebene registriert. Das funktioniert, wenn Sie den Agenten lokal ausführen oder mit der Agent CLI bereitstellen. Wenn Sie die Bereitstellung mit dem Vertex AI Python SDK vornehmen, registrieren Sie den Authentifizierungsanbieter stattdessen in set_up(), damit er im bereitgestellten Container ausgeführt wird. Weitere Informationen finden Sie unter Agent bereitstellen.

ADK

Verweisen Sie im Code Ihres KI-Agenten mithilfe des MCP-Toolsets im ADK auf den Authentifizierungsanbieter.

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

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

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

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

Sie erstellen kein Authentifizierungsschema für diesen Ablauf. Im Outbound-Binding des MCP-Servers ist bereits der zu verwendende Authentifizierungsanbieter angegeben.

Achtung:Verwenden Sie für den Authentifizierungsanbieter, den MCP-Server und den Agent Registry-Client dieselbe Region. Authentifizierungsanbieter sind am Standort global nicht verfügbar. Wenn Sie also location="global" festlegen, schlägt die Erstellung der ausgehenden Bindung mit dem Fehler Location of auth provider does not match location of binding fehl.

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

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

agent = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="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:

1. Erstellen und aktivieren Sie eine virtuelle Umgebung:

   python3 -m venv env
   source env/bin/activate

2. 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.

Agent CLI

Wenn Sie das Agent Development Kit (ADK) und die Agent-CLI verwenden, gehen Sie so vor, um Ihren Agenten mit aktivierter Agent Identity bereitzustellen:

1. Erstellen Sie im Ordner Ihrer Agent-Anwendung eine Konfigurationsdatei mit dem Namen .agent_engine_config.json, um die Agent-Identität zu aktivieren:

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

2. So stellen Sie Ihren KI-Agenten in der Laufzeit für KI-Agenten auf der Gemini Enterprise Agent Platform bereit:

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

   Ersetzen Sie Folgendes:

   • AGENT_NAME: Der Name des Ordners Ihrer Agent-Anwendung, z. B. maps_agent.
   • PROJECT_ID: Ihre Google Cloud-Projekt-ID.
   • LOCATION: Die unterstützte Region, in der Sie den Agent bereitstellen möchten, z. B. us-west1.

Python SDK

Wenn Sie die Bereitstellung programmatisch mit dem Vertex AI Python SDK vornehmen, verwenden Sie das Flag identity_type=AGENT_IDENTITY:

Achtung:Das SDK serialisiert Ihr App-Objekt. Der CredentialManager.register_auth_provider()-Aufruf, der von Ihrem lokalen Skript zur Importzeit ausgeführt wird, wird daher nicht im bereitgestellten Container ausgeführt. Registrieren Sie den Auth-Anbieter stattdessen in der set_up()-Methode Ihrer App, die von der Laufzeit beim Start des Containers aufgerufen wird. Andernfalls schlägt der Agent zur Abfragezeit mit No auth provider registered for custom auth scheme 'gcpAuthProviderScheme' fehl. Weitere Informationen finden Sie unter Überlegungen zur Bereitstellung.

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

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Google Cloud Projekt-ID.
• LOCATION: Die unterstützte Region, in der Sie den Agent bereitstellen möchten, z. B. us-west1.

Nächste Schritte

• Agent-Identität – Übersicht
• Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren
• Mit einem API-Schlüssel und dem Auth-Manager authentifizieren
• Agent Identity-Authentifizierungsanbieter verwalten
• Fehlerbehebung beim Agent Identity-Authentifizierungsmanager