Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren

Wenn Ihr Agent im Namen eines bestimmten Nutzers auf externe Tools und Dienste (z. B. Jira-Aufgaben oder GitHub-Repositories) zugreifen soll, müssen Sie im Authentifizierungsmanager für die Agent-Identität einen dreibeinigen OAuth-Authentifizierungsanbieter konfigurieren.

Dreibeinige OAuth-Authentifizierungsanbieter verwalten die Nutzerweiterleitung und Tokens für Sie. So müssen Sie keinen benutzerdefinierten Code schreiben, um komplexe OAuth 2.0-Abläufe zu verarbeiten.

Dreibeiniger OAuth-Workflow

Dreibeinige OAuth-Authentifizierungsanbieter erfordern die Nutzereinwilligung, da der Agent im Namen des Nutzers auf Ressourcen zugreift.

Aufforderung und Weiterleitung: Die Chat-Oberfläche fordert den Nutzer auf, sich anzumelden und leitet ihn dann zur Einwilligungsseite der Drittanbieteranwendung weiter.
Einwilligung und Speicherung: Nachdem der Nutzer die Berechtigung erteilt hat, werden die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedaten-Vault gespeichert.
Einfügen: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Authentifizierungsanbieter ab und fügt es in die Aufrufheader des Tools ein.

Hinweis

[Prüfen Sie, ob Sie die richtige Authentifizierungsmethode ausgewählt haben.](/iam/docs/agent-identity-overview#auth-models)
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. Informationen zum Zuweisen von Rollen.
API aktivieren
Erstellen und stellen Sie einen Agent bereit.
Sie benötigen eine Front-End-Anwendung, um Nutzeraufforderungen zur Anmeldung und Weiterleitung zu Einwilligungsseiten von Drittanbietern zu verarbeiten.
Prüfen Sie, ob Sie die Rollen haben, die zum Ausführen dieser 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 dreibeinigen Authentifizierungsanbieters benötigen:

Zum Erstellen von Authentifizierungsanbietern:
- IAM Connector-Administrator (roles/iamconnectors.admin)
- IAM Connector-Bearbeiter (roles/iamconnectors.editor)
Zum Verwenden von Authentifizierungsanbietern:
- IAM Connector-Nutzer (roles/iamconnectors.user)
- Standardzugriff für Agent (roles/aiplatform.agentDefaultAccess)
- Agent Context-Bearbeiter (roles/aiplatform.agentContextEditor)
- Vertex AI-Nutzer (roles/aiplatform.user)
- Service Usage-Nutzer (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 3-legged Auth-Anbieters 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 3-legged Auth-Bereitstellers erforderlich:

Zum Erstellen von Authentifizierungsanbietern: iamconnectors.connectors.create
Zum Verwenden von Authentifizierungsanbietern:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

Dreibeinigen 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 dreibeinigen Authentifizierungsanbieter zu erstellen.

Console

Rufen Sie in der Google Cloud Console die Seite Agent Registry auf.
Zu Agent Registry
Klicken Sie auf den Namen des Agents, für den Sie einen Authentifizierungsanbieter erstellen möchten.
Klicken Sie auf Identität.
Klicken Sie im Abschnitt 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. Er darf nicht mit einem Bindestrich enden und muss mit einem Kleinbuchstaben beginnen.
Wählen Sie in der Liste OAuth-Typ die Option OAuth (3-legged) aus.
Klicken Sie auf Erstellen und fortfahren.
Klicken Sie auf Zugriff erlauben, um der Identität Ihres Agents die Berechtigung zur Verwendung des Authentifizierungsanbieters zu erteilen.
Dadurch wird der Agentenidentität automatisch die Rolle Connector-Nutzer (roles/iamconnectors.user) für die Authentifizierungsanbieterressource zugewiesen.
Kopieren Sie die Rückruf-URL.
Registrieren Sie die Rückruf-URL auf einem separaten Tab in Ihrer Drittanbieteranwendung.
Rufen Sie in Ihrer Drittanbieteranwendung die Client-ID, den Clientschlüssel, die Token-URL und die Autorisierungs-URL ab.
Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
- Client-ID
- Clientschlüssel
- Token-URL
- Autorisierungs-URL
Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

Google Cloud CLI

Erstellen Sie den Authentifizierungsanbieter mit Autorisierungs- und Token-URLs:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Rufen Sie die Weiterleitungs-URI aus den Details des Auth-Anbieters ab:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
Der Befehl gibt die Weiterleitungs-URL im Feld redirectUrl zurück.
Registrieren Sie die Weiterleitungs-URL bei Ihrer Drittanbieteranwendung, um die Client-ID und den Clientschlüssel zu erhalten.

Aktualisieren Sie den Authentifizierungsanbieter mit der Client-ID und dem Clientschlüssel:

gcloud alpha agent-identity connectors update AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET"

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

Die Identität des Agents basiert auf dem Industriestandard SPIFFE -ID-Format. In IAM-Zulassungsrichtlinien werden Agentenidentitä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 Agenten 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 Agenten 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"
Connectorebene (curl)

Verwenden Sie die setIamPolicy API, um einem einzelnen Agenten Zugriff auf einen bestimmten Authentifizierungsanbieter zu gewähren. Dieser Befehl überschreibt alle vorhandenen Zulassungsrichtlinien für die Ressource.
```
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 Standort für Ihren Agenten (z. B. us-central1)
- ENGINE_ID: Die ID Ihrer Reasoning Engine

Authentifizierung im Agentencode

Sie können den Agenten mit dem ADK authentifizieren oder die Agent Identity API direkt aufrufen.

ADK

Verweisen Sie im Code Ihres Agents 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())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

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

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

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

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme=GcpAuthProviderScheme(
name="projects/GOOGLE_PROJECT/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
continue_uri=CONTINUE_URI)

# Set Agent Registry
registry = AgentRegistry(project_id="GOOGLE_PROJECT", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/GOOGLE_PROJECT/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],
)

API direkt aufrufen

Wenn Sie das ADK nicht verwenden, muss Ihr Agent die iamconnectorcredentials.retrieveCredentials API aufrufen, um das Token zu erhalten.

Da es sich um einen mehrstufigen OAuth-Ablauf handelt, gibt die API einen Vorgang mit langer Ausführungszeit zurück. Ihr Agent muss den Lebenszyklus des Vorgangs verwalten:

Erste Anfrage: Der Agent ruft retrieveCredentials auf.
Einwilligung erforderlich: Wenn der Nutzer keine Einwilligung erteilt hat, gibt die API einen Vorgang mit langer Ausführungszeit zurück, dessen Metadaten die auth_uri und eine consent_nonce enthalten.
Weiterleitung zum Front-End: Ihre Anwendung muss den Nutzer zur auth_uri weiterleiten.
Abschluss: Nachdem der Nutzer die Einwilligung erteilt hat, rufen Sie FinalizeCredential mit der consent_nonce auf, um den Vorgang abzuschließen und das Token zu erhalten.

Clientseitige Anwendung aktualisieren

Um die Nutzeranmeldung und -weiterleitung für dreibeiniges OAuth zu verarbeiten, muss Ihre clientseitige Anwendung die folgenden Schritte ausführen, um die Nutzereinwilligung zu verwalten und die Unterhaltung fortzusetzen:

Autorisierungstrigger verarbeiten
Endpunkt für die Nutzervalidierung implementieren
Unterhaltung mit dem Agent fortsetzen

Ein vollständiges Implementierungsbeispiel finden Sie im Front-End-Beispiel ValidateUserId.

Autorisierungstrigger verarbeiten

Wenn ein Agent die Nutzereinwilligung benötigt, gibt er einen adk_request_credential-Funktionsaufruf zurück. Ihre Anwendung muss diesen Aufruf abfangen, um ein Dialogfeld zur Nutzerautorisierung zu starten oder eine Weiterleitung auszulösen.

Verwalten Sie den Sitzungskontext, indem Sie die vom Authentifizierungsanbieter bereitgestellte consent_nonce aufzeichnen. Diese Nonce ist erforderlich, um den Nutzer im Validierungsschritt zu bestätigen. Speichern Sie auth_config und auth_request_function_call_id in der Sitzung, um die Fortsetzung des Ablaufs nach der Einwilligung zu erleichtern.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, auth_provider_name, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, 'id', None)
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Endpunkt für die Nutzervalidierung implementieren

Implementieren Sie einen Validierungsendpunkt auf Ihrem Webserver (derselbe URI, der bei der Konfiguration als continue_uri angegeben wurde). Dieser Endpunkt muss Folgendes tun:

user_id_validation_state und auth_provider_name als Abfrageparameter empfangen.
user_id und consent_nonce aus dem Sitzungskontext abrufen.
Die FinalizeCredentials API des Authentifizierungsanbieters mit diesen Parametern aufrufen.
Das Autorisierungsfenster schließen, nachdem eine Erfolgsmeldung empfangen wurde.

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
  auth_provider_name = request.query_params.get("auth_provider_name")
  session_id = request.cookies.get("session_id")
  session = consent_sessions.get(session_id, {})

  payload = {
      "userId": session.get("user_id"),
      "userIdValidationState": request.query_params.get(
          "user_id_validation_state"
      ),
      "consentNonce": session.get("consent_nonce"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{auth_provider_name}/credentials:finalize"

  try:
    async with httpx.AsyncClient(timeout=30.0) as client:
      resp = await client.post(finalize_url, json=payload)
      resp.raise_for_status()
  except httpx.HTTPError as e:
    err_text = e.response.text if hasattr(e, "response") else str(e)
    status = e.response.status_code if hasattr(e, "response") else 500
    return HTMLResponse(err_text, status_code=status)

  return HTMLResponse("""
      <script>
          window.close();
      </script>
      <p>Success. You can close this window.</p>
  """)

Unterhaltung mit dem Agent fortsetzen

Nachdem der Nutzer die Einwilligung erteilt hat und das Autorisierungsfenster geschlossen wurde, rufen Sie auth_config und auth_request_function_call_id aus Ihren Sitzungsdaten ab. Wenn Sie die Unterhaltung fortsetzen möchten, fügen Sie diese Details als function_response in eine neue Anfrage an den Agenten ein.

if request.is_auth_resume and session.auth_request_function_call_id and session.auth_config:
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Agent bereitstellen

Wenn Sie Ihren Agenten in Google Cloudbereitstellen, muss die Identität des Agents aktiviert sein.

Wenn Sie in der 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]"],
    },
)