Mit dem Authentifizierungsmanager mit zweiseitigem OAuth authentifizieren

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Wenn Sie Ihren KI-Agenten die Authentifizierung bei externen Tools wie ServiceNow oder Salesforce mit ihrer eigenen Autorisierung ermöglichen möchten, konfigurieren Sie die ausgehende Authentifizierung mit 2-Legged-OAuth-Authentifizierungsanbietern (Clientanmeldedaten) im Agent Identity-Authentifizierungsmanager.

Authentifizierungsanbieter mit zweibeinigem OAuth verwalten Anmeldedaten und Tokens für Sie. Dadurch müssen Sie keinen benutzerdefinierten Code mehr schreiben, um Authentifizierungsabläufe zu verarbeiten.

Warnung: In diesem Dokument wird gezeigt, wie Sie sich mit der IAM Connectors API authentifizieren, die nicht allgemein verfügbar sein wird. Für neue Projekte empfehlen wir die Verwendung der Agent Identity API. Migrieren Sie vorhandene Projekte zur Agent Identity API.

Zweibeiniger OAuth-Workflow

Zweibeinige OAuth-Authentifizierungsanbieter verwenden die Identität des Agents und erfordern keine Nutzereinwilligung. 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 Connector API, falls sie noch nicht aktiviert ist.

   Erforderliche Rollen zum Aktivieren von APIs

   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 Inhaberrolle (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 von der Drittanbieteranwendung ab, mit der Sie eine Verbindung herstellen 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-Agent-Identity-Authentifizierungsanbieters benötigen:

• So erstellen Sie Authentifizierungsanbieter:
  • IAM Connector Admin (roles/iamconnectors.admin)
  • IAM-Connector-Bearbeiter (roles/iamconnectors.editor)
• So verwenden Sie Authentifizierungsanbieter:
  • IAM Connector User (roles/iamconnectors.user)
  • Standardzugriff für Agenten (roles/aiplatform.agentDefaultAccess)
  • Agent Context Editor (roles/aiplatform.agentContextEditor)
  • 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-Agent-Identity-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen 2-Legged-Authentifizierungsanbieter für Agentenidentitäten 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.

2-Legged-Authentifizierungsanbieter erstellen

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

Verwenden Sie zum Erstellen eines 2-Legged-Authentifizierungsanbieters die Google Cloud Console oder die Google Cloud CLI.

Console

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

   Zur Agent Registry

2. Klicken Sie auf den Namen des KI-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-Typ die Option OAuth (zweibeinig) aus.
7. Klicken Sie auf Erstellen und fortfahren.
8. Klicken Sie auf Zugriff gewähren, um der Agentenidentität die Berechtigung zur Verwendung des Authentifizierungsanbieters zu erteilen.

   Dadurch wird der Agent-Identität für die Authentifizierungsanbieterressource automatisch die Rolle Connector User (roles/iamconnectors.user) zugewiesen.

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

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

gcloud-CLI

1. Erstellen Sie den Authentifizierungsanbieter:

   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"

2. Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste aufgeführt ist und den Status ENABLED hat:

   gcloud alpha agent-identity connectors 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 Connector User (roles/iamconnectors.user) für die Authentifizierungsanbieter-Ressource zu:

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

      gcloud alpha agent-identity connectors add-iam-policy-binding AUTH_PROVIDER_NAME \
          --project="PROJECT_ID" \
          --location="LOCATION" \
          --role="roles/iamconnectors.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 Ihrem persönlichen Nutzerkonto Zugriff für die lokale Entwicklung und Tests (adk web):

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

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Google Cloud Projekt-ID
• LOCATION: Der Standort, 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 über den Drittanbieterdienst generiert haben.
• CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie über den Drittanbieterdienst generiert haben.
• TOKEN_ENDPOINT: Die URL des Token-Endpunkts (z. B. https://oauth2.googleapis.com/token).
• ORGANIZATION_ID: Ihre Organisations-ID von Google Cloud .
• PROJECT_NUMBER: Ihre Google Cloud -Projektnummer.
• ENGINE_ID: Die ID des bereitgestellten Reasoning-Engine-Agenten.
• USER_EMAIL: Die E-Mail-Adresse Ihres persönlichen Nutzerkontos.

Im Agentencode authentifizieren

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

ADK

Verweisen Sie im Code Ihres KI-Agenten auf den Authentifizierungsanbieter, indem Sie das MCP-Toolset im ADK verwenden.

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="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.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="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 „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="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

  

Abhängigkeiten für lokale Tests installieren

Installieren Sie die folgenden erforderlichen Abhängigkeiten, um Ihren Agenten lokal in einer virtuellen Umgebung zu testen:

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 KI-Agenten in Google Cloudbereitstellen, muss die Agentenidentität aktiviert sein.

Wenn Sie in der Agent Runtime auf der Gemini Enterprise Agent Platform 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]"],
    },
)

Nächste Schritte

• Agentenidentität – Übersicht
• Mit dreibeinigem OAuth mit Auth Manager authentifizieren
• Mit API-Schlüssel und Auth Manager authentifizieren
• Agent Identity-Authentifizierungsanbieter verwalten
• Fehlerbehebung für den Agent Identity-Authentifizierungsmanager