Mit dreibeinigem OAuth und dem Auth-Manager authentifizieren

Wenn Sie Ihrem Agenten im Namen eines bestimmten Endnutzers Zugriff auf externe Tools und Dienste (z. B. Jira-Aufgaben oder GitHub-Repositories) gewähren möchten, konfigurieren Sie im Authentifizierungsmanager für die Identität von KI-Agenten einen dreibeinigen OAuth-Authentifizierungsanbieter.

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.

  1. Aufforderung und Weiterleitung: Die Chat-Oberfläche fordert den Nutzer auf, sich anzumelden und leitet ihn dann zur Einwilligungsseite der Drittanbieteranwendung weiter.
  2. Einwilligung und Speicherung: Nachdem der Nutzer die Berechtigung erteilt hat, speichert der Authentifizierungsmanager für die Identität von KI-Agenten die resultierenden OAuth-Tokens in einem von Google verwalteten Anmeldedatenspeicher.
  3. Einfügung: Wenn Sie das Agent Development Kit (ADK) verwenden, ruft der Agent das Token automatisch vom Authentifizierungsanbieter ab und fügt es in die Header für den Toolaufruf ein.

Hinweis

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

  2. Aktivieren Sie die Agent Identity Connector 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. Sie benötigen eine Front-End-Anwendung, um Aufforderungen zur Nutzeranmeldung und Weiterleitungen zu Einwilligungsseiten von Drittanbietern zu verarbeiten.
  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 dreibeinigen Authentifizierungsanbieters benötigen:

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 dreibeinigen 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 dreibeinigen Authentifizierungsanbieters 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

  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 Abschnitt 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. Er muss mit einem Kleinbuchstaben beginnen und darf nicht mit einem Bindestrich enden.

  6. Wählen Sie in der Liste OAuth-Typ die Option OAuth (3-legged) aus.
  7. Klicken Sie auf Erstellen und fortfahren.
  8. Klicken Sie auf Zugriff erlauben, um der Identität Ihres Agenten die Berechtigung zur Verwendung des Authentifizierungsanbieters zu gewähren.

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

  9. Kopieren Sie die Rückruf-URL.
  10. Registrieren Sie die Rückruf-URL auf einem separaten Tab in Ihrer OAuth-Clientanwendung eines Drittanbieters.
  11. Geben Sie im Abschnitt Anmeldedaten des Authentifizierungsanbieters die folgenden Informationen ein:
    • Client-ID
    • Clientschlüssel
    • Token-URL
    • Autorisierungs-URL
  12. Klicken Sie auf Anbieterkonfiguration hinzufügen.

Der neu erstellte Authentifizierungsanbieter wird in der Liste Authentifizierungsanbieter angezeigt.

gcloud CLI

  1. Konfigurieren Sie Ihre OAuth-Clientanwendung, um Ihren Client zu registrieren und eine Client-ID und einen Clientschlüssel zu erhalten. Geben Sie die Weiterleitungs-URI mit der Vorlage in diesem Abschnitt an.

  2. Erstellen Sie den Authentifizierungsanbieter mit Ihren Clientanmeldedaten:

    gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"
  3. Prüfen Sie, ob Ihr Authentifizierungsanbieter in der Liste angezeigt wird und der Status ENABLED ist: 
    gcloud alpha agent-identity connectors list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  4. Erteilen Sie Zugriffsberechtigungen, damit Ihr Agent und Ihre lokale Entwicklungsumgebung Anmeldedaten vom Authentifizierungsanbieter abrufen können. Wenn Sie Ihrem bereitgestellten Agenten und Ihrem persönlichen Nutzerkonto Zugriff auf den Authentifizierungsanbieter gewähren möchten, weisen Sie die Rolle Connector-Nutzer (roles/iamconnectors.user) für die Authentifizierungsanbieterressource zu:

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

      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 Zugriff auf Ihr persönliches Nutzerkonto 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 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 Token-Servers (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

OAuth-Clientanwendung konfigurieren

Bevor Sie Ihre OAuth-Clientanmeldedaten registrieren, rufen Sie eine Client-ID und einen Clientschlüssel vom Autorisierungsserver eines Drittanbieters ab (z. B. Google, GitHub oder Jira).

Wenn Sie eine Verbindung zu einem Drittanbieterdienst außerhalb von Google Cloudherstellen, rufen Sie die OAuth-Clientanmeldedaten im Entwicklerportal dieses Dienstes ab und überspringen Sie die Schritte in diesem Abschnitt.

Weiterleitungs-URI registrieren

Wenn Sie Ihre OAuth-Clientanmeldedaten konfigurieren, müssen Sie die dedizierte Rückruf-Weiterleitungs-URI des Authentifizierungsanbieters registrieren.

  1. Erstellen Sie die Weiterleitungs-URI mit der folgenden Vorlage:

    https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Google Cloud Projekt-ID
    • LOCATION: The region where your auth provider will be deployed (for example,us-west1`)
    • CONNECTOR_NAME: Der Name Ihres Authentifizierungsanbieters

    Beispiel: https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback

  2. Wenn Sie eine Verbindung zu Google Cloud -Diensten (z. B. BigQuery) herstellen, können Sie den Zustimmungsbildschirm konfigurieren und OAuth Clientanmeldedaten in der Google Cloud Console erstellen:

    1. OAuth-Zustimmungsbildschirm konfigurieren:

      1. Rufen Sie in der Google Cloud Console die Seite APIs & Dienste >OAuth-Zustimmungsbildschirm auf.

        Zu APIs & Dienste >OAuth-Zustimmungsbildschirm

      2. Geben Sie im Abschnitt