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 Identität von KI-Agenten einen 3-legged OAuth-Authentifizierungsanbieter konfigurieren.

Dreibeinige OAuth-Authentifizierungsanbieter verwalten die Nutzerweiterleitung und Tokens für Sie. Dadurch ist es nicht mehr erforderlich, benutzerdefinierten Code für die Verarbeitung komplexer OAuth 2.0-Abläufe zu schreiben.

Ablauf des dreibeinigen OAuth

Für 3-legged OAuth-Authentifizierungsanbieter ist die Nutzereinwilligung erforderlich, da der Agent im Namen des Nutzers auf Ressourcen zugreift.

Aufforderung und Weiterleitung: Die Chatoberflä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-Tresor gespeichert.
Einfügen: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Autorisierungsanbieter ab und fügt es in die Header des Toolaufrufs 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. Weitere Informationen zum Zuweisen von Rollen
API aktivieren
Agent erstellen und bereitstellen.
Sie benötigen eine Frontend-Anwendung, um Anmeldeaufforderungen für Nutzer und Weiterleitungen zu Einwilligungsseiten von Drittanbietern zu verarbeiten.
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 3-legged-Authentifizierungsanbieters 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 3-Legged-Authentifizierungsanbieters erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um einen 3-Legged-Authentifizierungsanbieter 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.

3-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 3-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 (3 legged) (OAuth (3-legged)) aus.
Klicken Sie auf Erstellen und fortfahren.
Wenn Sie der Identität Ihres Agents die Berechtigung zum Verwenden 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.
Kopieren Sie die Rückruf-URL.
Registrieren Sie die Callback-URL in 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
- Client-Secret
- Token-URL
- Autorisierungs-URL
Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Auth Providers (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 den Weiterleitungs-URI aus den Details des Authentifizierungsanbieters ab:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
Der Befehl gibt den Weiterleitungs-URI im Feld redirectUrl zurück.
Registrieren Sie den Weiterleitungs-URI 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 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

Zur Authentifizierung Ihres Agenten können Sie das ADK verwenden oder die Agent Identity API direkt aufrufen.

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

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

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

# 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 verarbeiten:

Erste Anfrage: Der Kundenservicemitarbeiter ruft retrieveCredentials an.
Einwilligung erforderlich: Wenn der Nutzer keine Einwilligung erteilt hat, gibt die API einen LRO zurück, dessen Metadaten auth_uri und consent_nonce enthalten.
Frontend-Weiterleitung: Ihre Anwendung muss den Nutzer zu auth_uri weiterleiten.
Abschluss: Nachdem der Nutzer die Einwilligung erteilt hat, rufen Sie FinalizeCredential mit consent_nonce auf, um den Ablauf abzuschließen und das Token zu erhalten.

Clientseitige Anwendung aktualisieren

Um die Nutzeranmeldung und ‑weiterleitung für 3-legged 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 unter Frontend-Beispiel für 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 Nutzerautorisierungsdialogfeld 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 während des Validierungsschritts zu bestätigen. Speichern Sie die auth_config und auth_request_function_call_id in der Sitzung, um den Ablauf nach Erteilung der Einwilligung fortsetzen zu können.

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 Nutzerüberprüfung implementieren

Implementieren Sie einen Validierungs-Endpunkt 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.
Rufen Sie user_id und consent_nonce aus dem Sitzungskontext ab.
Rufen Sie die FinalizeCredentials-API des Authentifizierungsanbieters mit diesen Parametern auf.
Schließen Sie das Autorisierungsfenster, nachdem Sie eine Erfolgsmeldung erhalten haben.

@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>
  """)

Agent-Unterhaltung fortsetzen

Nachdem der Nutzer die Einwilligung erteilt hat und das Autorisierungsfenster geschlossen wurde, rufen Sie die auth_config und auth_request_function_call_id aus Ihren Sitzungsdaten ab. Wenn Sie die Unterhaltung fortsetzen möchten, fügen Sie diese Details in einer neuen Anfrage an den Kundenservicemitarbeiter als function_response 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 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]"],
    },
)