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 Ihre Agenten sich mit ihrer eigenen Autorisierung bei externen Tools wie ServiceNow oder Salesforce authentifizieren sollen, konfigurieren Sie die ausgehende Authentifizierung mit 2-legged OAuth-Authentifizierungsanbietern (Clientanmeldedaten) im Authentifizierungsmanager für Agent Identity.

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

Warnung:Die IAM Connectors API wird nicht allgemein verfügbar sein. Wir empfehlen, die Agent Identity API zu verwenden. Die API-Dokumentation zur IAM Connectors API finden Sie unter Mit der IAM Connectors API mit 2-legged OAuth und dem Authentifizierungsmanager authentifizieren.

2-legged OAuth-Workflow

2-legged OAuth-Authentifizierungsanbieter verwenden die Identität des Agenten 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 Toolaufrufheader 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. Erstellen und stellen Sie einen Agenten bereit.

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 erforderlichen Rollen haben, um diese Aufgabe auszuführen.

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: Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen:

• Zum Erstellen von Authentifizierungsanbietern:
  • Agent Identity-Administrator (roles/agentidentity.admin)
  • Agent Identity-Bearbeiter (roles/agentidentity.editor)
• Zum Verwenden von Authentifizierungsanbietern:
  • Agent Identity-Nutzer (roles/agentidentity.user)
  • Standardzugriff für Agenten (roles/aiplatform.agentDefaultAccess)
  • Bearbeiter für Agentenkontext (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 Agent Identity-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen und Verwenden eines 2-legged Agent Identity-Authentifizierungsanbieters erforderlich:

• Zum Erstellen von Authentifizierungsanbietern: agentidentity.authProviders.create
• Zum Verwenden von Authentifizierungsanbietern:
  • 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 gcloud CLI, um einen 2-legged-Authentifizierungsanbieter zu erstellen:

1. Erstellen Sie den Authentifizierungsanbieter:

   gcloud alpha agent-identity authProviders 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 angezeigt wird und der Status ENABLED ist:

   gcloud alpha agent-identity authProviders list \
      --project="PROJECT_ID" \
      --location="LOCATION"

3. Erteilen 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 der Authentifizierungsanbieterressource die Rolle Agent Identity-Nutzer (roles/agentidentity.user) zu:

   1. Erteilen Sie Zugriff auf die SPIFFE-ID Ihres bereitgestellten Agenten (Agent Identity):

      gcloud alpha agent-identity authProviders 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. Erteilen Sie Zugriff auf Ihr persönliches Nutzerkonto für die lokale Entwicklung und das Testen (adk web):

      gcloud alpha agent-identity authProviders 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 Standort, an dem Ihr Authentifizierungsanbieter und Ihr Agent bereitgestellt werden (z. B. us-west1)
• AUTH_PROVIDER_NAME: Der Name für Ihren Authentifizierungsanbieter (z. B. bigquery-mcp-3lo-authprovider)
• AUTHORIZATION_URL: Die URL des Autorisierungsservers (z. B. https://accounts.google.com/o/oauth2/v2/auth)
• TOKEN_URL: Die URL des Tokenservers (z. B. https://oauth2.googleapis.com/token)
• CLIENT_ID: Die OAuth-Client-ID, die Sie vom Drittanbieterdienst generiert haben
• CLIENT_SECRET: Der OAuth-Clientschlüssel, den Sie vom Drittanbieterdienst generiert haben
• ORGANIZATION_ID: Ihre Google Cloud Organisations-ID
• PROJECT_NUMBER: Ihre Google Cloud Projektnummer
• ENGINE_ID: Die ID Ihres 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 Agenten zu authentifizieren.

ADK

Verweisen Sie im Code Ihres 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
# 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 = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="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
# 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 = 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 Agenten mit dem MCP-Toolset der 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
# 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 = LlmAgent(
    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 Agenten in Google Cloudbereitstellen, muss Agent Identity aktiviert sein.

Wenn Sie in Agent Runtime on Gemini Enterprise Agent Platform bereitstellen, verwenden Sie das identity_type=AGENT_IDENTITY Flag:

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

• Agent Identity – Übersicht
• Mit 3-legged OAuth und dem Authentifizierungsmanager authentifizieren
• Mit einem API-Schlüssel und dem Authentifizierungsmanager authentifizieren
• Authentifizierungsanbieter für Agent Identity verwalten
• Fehlerbehebung beim Authentifizierungsmanager für Agent Identity