Implementierungsleitfaden für OAuth 2.1

In diesem Leitfaden wird beschrieben, wie Sie die Plattform für verbundene Apps sicher für den Zugriff auf Ihre Dienste autorisieren. Für MCP-Integrationen in verbundene Apps empfehlen wir dringend die Verwendung von OAuth 2.1, dem Branchenstandard für delegierte Autorisierung, mit Proof Key for Code Exchange (PKCE), um die höchste Sicherheit für Nutzerdaten und Zuverlässigkeit in agentischen Abläufen zu gewährleisten. Die Plattform für verbundene Apps unterstützt den Genehmigungstyp „Autorisierungscode“ mit PKCE-Parametern (Proof Key for Code Exchange).

PKCE ist für alle OAuth 2.1-Anfragen obligatorisch und für OAuth 2.0 optional.

Damit die automatische Erkennung aktiviert und der Onboarding-Prozess optimiert werden kann, muss Ihr Autorisierungsserver die Erweiterung für Autorisierungsserver-Metadaten unterstützen, die auch als OAuth Discovery bezeichnet wird.

Tipp: Um eine frustrierende Nutzererfahrung und die Notwendigkeit einer erneuten Verknüpfung von Konten zu vermeiden, ist es am wichtigsten, die Lebensdauer des Aktualisierungstokens mithilfe der dauerhaften Verknüpfung zu verwalten.

So ruft Gemini MCP die JSON-Konfiguration ab

Die Gemini MCP-Konsole versucht, Ihre Konfigurations-JSON-Datei von den folgenden URLs in der in diesem Abschnitt gezeigten Reihenfolge abzurufen.

Achtung: Die Gemini MCP-Konsole verwendet die erste URL, die eine Antwort zurückgibt, einschließlich eines Fehlers. Achten Sie darauf, dass der gewünschte Endpunkt erreichbar ist und HTTP 200 zurückgibt.

Wenn sich die URL Ihres Autorisierungsservers auf der obersten Ebene Ihrer Domain befindet (z. B. https://auth.example.com), hängt Gemini standardmäßige „well-known“-Verzeichnisse an Ihre Domain an und sucht in der folgenden Reihenfolge nach dem Server:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

Wenn sich die URL Ihres Autorisierungsservers in einem bestimmten Unterverzeichnis oder Pfad Ihrer Domain befindet, z. B. https://auth.example.com/realms/master, hängt Gemini die bekannten Pfade direkt an dieses Unterverzeichnis an, und zwar in der folgenden Reihenfolge.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (Unterstützung für verschachtelte Pfade)

Erforderliche JSON-Funktionen

Die Metadatenantwort muss die folgenden Felder enthalten. Die Integration schlägt fehl, wenn Pflichtfelder fehlen oder keine gültigen Typen gefunden werden.

authorization_endpoint

Muss eine gültige String-URL sein.

token_endpoint

Muss eine gültige String-URL sein.

response_types_supported

Muss den String code enthalten.

registration_endpoint

Derzeit wird in der Play Console der dynamische Client verwendet.

Registrierung (RFC 7591). Sie müssen in Ihren Metadaten einen Registrierungsendpunkt angeben oder die Client-ID und den Clientschlüssel direkt in der Play Console-Benutzeroberfläche eingeben.

Wenn dein Autorisierungsserver die dynamische Clientregistrierung (Dynamic Client Registration, DCR) nicht unterstützt, musst du die Felder Client-ID und Clientschlüssel in der Play Console-Benutzeroberfläche manuell implementieren und ausfüllen, um die Integration abzuschließen.

Wenn Ihre Implementierung Proof Key for Code Exchange (PKCE) oder persistente Sitzungen unterstützt, müssen Sie die relevanten Funktionsfelder (z. B. Challenge Methods und Genehmigungstypen) in Ihre Discovery-JSON-Datei aufnehmen. So wird die Kompatibilität mit den Sicherheits- und Verbindungsstandards von Gemini sichergestellt. Wenn Sie den Bereich unterstützen, müssen Sie das Feld scopes_supported angeben.

Konfigurationsbeispiel

Die folgende JSON-Antwort ist gültig und erfüllt die Anforderungen unseres Clients.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

Wenn Sie PKCE einbeziehen, zeigt das folgende Snippet ein Beispiel dafür, was im JSON-Block enthalten sein könnte.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

Wenn Sie das Feld scopes_supported einfügen, zeigt das folgende Snippet ein Beispiel dafür, was im JSON-Block enthalten sein könnte.

"scopes_supported": ["mcp", "cart.order"],

Autorisierungscode-Vorgang (vereinfachte Version)

In den folgenden Schritten wird der Standard-Autorisierungscode-Vorgang beschrieben. Diese Sequenz veranschaulicht genau, wie die Connected Apps Platform die erforderlichen Zugriffstokens sicher von Ihrem Server abruft, um im Namen eines Nutzers zu agieren.

1. Autorisierungsanfrage: Die Google-Oberfläche stellt fest, dass sie Ihre Funktion aufrufen muss, der Nutzer aber noch nicht autorisiert ist. Der Chatbot leitet den Browser des Nutzers an Ihren Autorisierungsendpunkt weiter oder zeigt einen Link dorthin an.

   Diese Anfrage enthält Ihre Client-ID (oder wird automatisch mit DCR generiert), den Weiterleitungs-URI von Gemini und wichtige PKCE-Parameter (code_challenge und code_challenge_method).

   Setzen Sie die folgenden URLs für die OAuth-Einrichtung auf die Zulassungsliste:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. Nutzereinwilligung: Ihr Autorisierungsserver validiert die Anfrage, authentifiziert den Nutzer (Anmeldung) und bittet den Nutzer, der Google-Oberfläche die Berechtigung zu erteilen, auf seine Daten oder seinen Dienst zuzugreifen.

3. Code Grant: Nachdem der Nutzer seine Einwilligung erteilt hat, leitet Ihr Server den Browser des Nutzers zurück zur RedirectURI von Gemini und hängt einen temporären Autorisierungscode an die URL an.

4. Tokenaustausch: Das Backend hinter Gemini sendet eine POST-Anfrage an Ihren Token-Endpunkt und tauscht den Autorisierungscode gegen ein Zugriffstoken aus.

   Hinweis: Diese Anfrage muss den PKCE-Parameter (code_verifier) enthalten, um zu beweisen, dass es sich um denselben Client handelt, der den Ablauf gestartet hat.

5. Zugriff gewährt: Ihr Token-Endpunkt überprüft den Code und die PKCE-Parameter, stellt ein Zugriffstoken und optional ein Aktualisierungstoken aus und gibt diese an Gemini zurück.

   Tipp: Aktualisierungstokens sind zwar optional, wir empfehlen jedoch dringend, Ihren Autorisierungsserver so zu konfigurieren, dass er sie ausgibt. Mit Aktualisierungstokens kann die Connected Apps Platform den Zugriff aufrechterhalten, ohne dass der Nutzer sich neu authentifizieren muss.

Wichtige PKCE-Anforderungen

PKCE bietet eine zusätzliche Sicherheitsebene, um das unbefugte Abfangen von Autorisierungscodes zu verhindern.

Achtung: Die Erfüllung dieser PKCE-Anforderungen ist für die ordnungsgemäße Verwaltung der Zugriffs- und Aktualisierungstokens von entscheidender Bedeutung. Dies trägt zum Schutz der Nutzerdaten und zur Wahrung der Integrität des Ökosystems bei.

• code_verifier: Ein kryptografisch zufälliger String, der von Gemini zu Beginn des Ablaufs generiert wird. Diese Informationen sind privat.
• code_challenge: Eine Transformation der code_verifier, normalerweise das SHA256-Hashing. Diese wird öffentlich gesendet, wie in Schritt 1 des Autorisierungscode-Vorgangs beschrieben.
• Validierung: Ihr Token-Endpunkt (beschrieben in Schritt 4 des Autorisierungscode-Vorgangs) muss prüfen, ob der empfangene code_verifier nach der Transformation mit dem ursprünglichen code_challenge übereinstimmt.

Debugging

Detaillierte Informationen zu Verknüpfungsfehlern finden Sie im Log-Explorer. Folgen Sie der Anleitung unter Fehler bei der Kontoverknüpfung in Ihrem Google Console-Projekt im Blick behalten, um Fehler zu aktivieren und anzusehen.

Anforderungen an die Konfiguration der Google-Kontoverknüpfung

In den folgenden API-Richtlinien finden Sie Informationen zur Konfiguration der Google-Kontoverknüpfung.

• Google-Kontoverknüpfung mit OAuth
• Ihre Account Linking API
• Google Account Linking API

Damit Sie Ihre OAuth-Integration erfolgreich registrieren können, müssen Sie bestimmte Details zu Ihrem Autorisierungsserver konfigurieren. Bereiten Sie die folgenden Endpunkte, Anmeldedaten und Assets vor.

Konfigurationsfeld	Beschreibung	Verantwortung des Entwicklers
Client-ID und Secret	Die eindeutigen Anmeldedaten, die Ihr Autorisierungsserver speziell für die Plattform für verbundene Apps generiert. Der Clientschlüssel sind die sicheren Sicherheitsanmeldedaten (Passwort), die mit der Client-ID verknüpft sind. Hinweis: Wenn der Entwickler die Client-ID ausgestellt hat, muss er sie angeben. Wenn Google die Client-ID ausgestellt hat, muss der Entwickler möglicherweise einen Clientschlüssel registrieren oder bestätigen.	Verwenden Sie die von der Plattform bereitgestellte ID in allen Autorisierungsanfragen.
Autorisierungsendpunkt	Die URL, zu der Nutzer weitergeleitet werden, um sich zu authentifizieren und ihre Einwilligung zu erteilen	Hosten Sie den Endpunkt, z. B. https://yourdomain.com/oauth/authorize.
Token-Endpunkt	Der Backend-Endpunkt, um Autorisierungscodes gegen Zugriffs-/Aktualisierungstokens auszutauschen und abgelaufene Tokens zu aktualisieren.	Hosten Sie diesen Endpunkt, z. B. https://yourdomain.com/oauth/token.
Widerrufsendpunkt Optional	Die URL, über die Ihr System benachrichtigt wird, dass ein Token ungültig gemacht werden soll, wenn ein Nutzer die Verbindung trennt. Wenn ein Nutzer die Verknüpfung oder Verbindung zu Ihrer Integration auf der Plattform für verbundene Apps aufhebt, senden wir eine POST-Anfrage an den Endpunkt „/revoke“, die das Zugriffs- oder Aktualisierungstoken enthält. Weitere Informationen finden Sie unter Verknüpfung von Konten aufheben.	Hosten Sie den Endpunkt, z. B. https://yourdomain.com/oauth/revoke. Ihr Server muss diese Anfrage verarbeiten, indem er das bereitgestellte Token dauerhaft ungültig macht. Dadurch schlagen alle nachfolgenden Versuche der Plattform für verbundene Apps, dieses Token zu verwenden, fehl und die Daten des Nutzers bleiben nach der Trennung geschützt.
Weiterleitungs-URI	Die spezifische Callback-URL, die von der Plattform bereitgestellt wird, an die der Autorisierungsserver den Code nach der Einwilligung zurücksendet.	Konfigurieren Sie Ihren Autorisierungsserver so, dass er nur den offiziellen, registrierten Weiterleitungs-URI von der Plattform akzeptiert.
Aktualisieren	/token mit grant_type=refresh_token Ein Mechanismus, mit dem die Connected Apps Platform ein neues Zugriffstoken erhalten kann, wenn das aktuelle abläuft. So bleibt die Integration nahtlos verbunden, ohne dass sich der Nutzer wiederholt anmelden muss. Wenn ein vorhandenes Zugriffstoken abläuft, sendet die Plattform für verbundene Apps automatisch eine POST-Anfrage an deinen /token-Endpunkt. Die Anfragenutzlast enthält grant_type=refresh_token und das Aktualisierungstoken, das Ihr Server zuvor ausgestellt hat.	Ihr Server muss das bereitgestellte Aktualisierungstoken validieren und ein neues Zugriffstoken in der JSON-Antwort zurückgeben. Wenn Sie die dauerhafte Verknüpfung implementieren möchten, dürfen Sie das Aktualisierungstoken während dieses Austauschs nicht rotieren. Anstatt ein neues Token auszustellen, geben Sie genau dasselbe Aktualisierungstoken in der JSON-Antwort zurück und verlängern Sie das Ablaufdatum im Backend.
Antworttyp	Dieser muss auf CODE konfiguriert sein, um den Autorisierungscode-Vorgang zu unterstützen.
Bereiche	Die spezifischen Berechtigungen und Zugriffsebenen, die festlegen, was mit dem Token autorisiert werden kann. Diese müssen in Ihrer Konfiguration vordefiniert sein, damit Google sie während des ersten Autorisierungs-Handshakes anfordern kann.	Sie müssen eine Liste der Standardbereiche (z. B. openid, profile, email) angeben, die die Plattform für verbundene Apps beim Initiieren des Ablaufs anfordern soll. Die angeforderten Bereiche sollten so weit wie möglich eingeschränkt sein (Prinzip der geringsten Berechtigung), aber für die Critical User Journeys (CUJs), die Ihre MCP-Integration unterstützt, vollständig ausreichen.
UI-Assets: Logo	Entwicklerlogo, das auf den Bildschirmen für die Kontoverknüpfung und die Einwilligung angezeigt werden soll.	Es muss ein quadratisches Vektor-Image (SVG) mit kreisförmigem Erscheinungsbild und mindestens 500 × 500 Pixeln sein. Beispiele finden Sie unter https://[partner-domain]/assets/logo.svg oder in der SVG-Rohdatei.
Verknüpfung mit systemeigenen Apps (App Flip)	Wenn Sie die Kontoverknüpfung direkt über Ihre nativen Android- oder iOS-Apps unterstützen möchten, sollten Sie keine Standard-WebViews verwenden. Stattdessen wird dringend empfohlen, App Flip zu implementieren, um eine nahtlose Nutzererfahrung zu ermöglichen. Weitere Informationen finden Sie unter Google-Kontoverknüpfung mit OAuth-basiertem App Flip.	Schließen Sie die Bestätigung im Google Play Store und App Store ab und binden Sie die Weiterleitungs-URIs von Google direkt in Ihre nativen Anwendungen ein, um eine sichere App-zu-App-Autorisierung zu ermöglichen.
Token-Lebensdauer	(Optional) Die Dauer, für die ein Zugriffstoken gültig ist, bevor eine Aktualisierung erforderlich ist. Nützlich zum Konfigurieren von Zeitlimitrichtlinien in GAL.	Übliche Ablaufzeiten reichen je nach Sicherheitsanforderungen von Minuten über Stunden bis hin zu Tagen, z. B. 30 days.

Häufige Integrationsfehler

Im Folgenden finden Sie eine Liste häufiger Fehler und möglicher Lösungen für den Integrationsprozess.

• Fehlende „code“-Berechtigung: Das automatisierte System der Gemini-Plattform prüft response_types_supported explizit auf den Wert „code“.
• Fehlender Registrierungsendpunkt: Auch wenn Ihr Server Client-ID-Metadatendokumente unterstützt, benötigt die Gemini App (die als OAuth-Client fungiert, der sich mit Ihrem Server verbindet) derzeit einen dedizierten „registration_endpoint“ im Discovery-JSON.
• Fehler, der nicht „200“ ist: Wenn der automatisierte Metadaten-Erkennungsmechanismus von Gemini auf Ihre well-known URL zugreift und einen 404- oder 500-Fehler erhält, wird nicht versucht, andere URLs zu erraten. Achten Sie darauf, dass die Discovery-URL öffentlich zugänglich ist.