Übersicht

Integrationspfad auswählen

Wählen Sie den Pfad aus, der Ihren Anforderungen am besten entspricht:

Pfad	Optimal für	Weitere Informationen
Universal Commerce Protocol (UCP)	Händler und Einzelhändler	UCP-Dokumentation
Standardkontoverknüpfung	Smart Home, TV und YouTube	Google Docs

Hinweis:Diese Integrationspfade ergänzen sich. Wenn Sie UCP implementieren, empfehlen wir Ihnen, sowohl die Anleitung zur UCP-Identitätsverknüpfung für produktspezifische Anforderungen als auch diese Dokumentation mit Details zur OAuth-Kernimplementierung zu lesen.

Mit der Kontoverknüpfung können Inhaber von Google-Konten schnell, nahtlos und sicher eine Verbindung zu Ihren Diensten herstellen. Sie können die Google-Kontoverknüpfung implementieren, um die Daten eines Nutzers von Ihrer Plattform für Google-Apps und ‑Dienste freizugeben.

Mit dem sicheren OAuth 2.0-Protokoll können Sie das Google-Konto eines Nutzers sicher mit seinem Konto auf Ihrer Plattform verknüpfen und so Google-Anwendungen und ‑Geräten Zugriff auf Ihre Dienste gewähren.

Nutzer können ihre Konten verknüpfen oder die Verknüpfung aufheben und optional beim Drittanbieterdienst ein neues Konto mit einer Google-Kontoverknüpfung erstellen.

Anwendungsfälle

Hier sind einige Gründe für die Implementierung der Google-Kontoverknüpfung:

• Daten eines Nutzers von Ihrer Plattform für Google-Apps und ‑Dienste freigeben

• Mit Google Shopping und KI-Oberflächen (Suche, Gemini) über das Universal Commerce Protocol (UCP) integrieren

• Video- und Filminhalte mit Google TV wiedergeben

• Mit dem Smart Home verbundene Geräte von Google mit der Google Home App und Google Assistant verwalten und steuern, z. B. „Hey Google, schalte das Licht ein“

• Benutzerdefinierte Google Assistant-Erlebnisse und ‑Funktionen mit Conversational Actions erstellen, z. B. „Hey Google, bestelle mein übliches Getränk bei Starbucks“

• Nutzer können Belohnungen erhalten, wenn sie sich bestimmte Livestreams auf YouTube ansehen, nachdem sie ihr Google-Konto mit einem Belohnungspartnerkonto verknüpft haben.

• Neue Konten bei der Registrierung mit einvernehmlich freigegebenen Daten aus einem Google-Kontoprofil vorab ausfüllen

Funktionen und Anforderungen

In der folgenden Matrix sind die Unterstützung und Empfehlungen für jeden Verknüpfungsvorgang definiert.

Verknüpfungsvorgang	Standardfunktionen	UCP-Funktionen
App-Flip	Empfohlen	Empfohlen
Optimierte Verknüpfung	Empfohlen	Empfohlen
Web-OAuth	Erforderlich (Fallback)	Erforderlich (Fallback)
OAuth 2.1	Empfohlen	Empfohlen

• Datenschutz der Nutzer verbessern, indem benutzerdefinierte Bereiche definiert werden, um nur die erforderlichen Daten freizugeben. Das Vertrauen der Nutzer stärken, indem klar definiert wird, wie ihre Daten verwendet werden.

• Der Zugriff auf Daten und Dienste, die auf Ihrer Plattform gehostet werden, kann durch Aufheben der Kontoverknüpfung widerrufen werden. Durch die Implementierung eines optionalen Endpunkts für den Widerruf von Tokens bleiben Sie mit von Google initiierten Ereignissen synchron. Mit Cross-Account Protection (RISC) können Sie Google über alle Ereignisse zum Aufheben der Verknüpfung informieren, die auf Ihrer Plattform stattfinden.

Hinweis: In der meisten OAuth 2.0-Dokumentation für die Google Identity Platform wird beschrieben, wie Sie Nutzer mit ihren Google-Konten anmelden und die Autorisierung zum Aufrufen von Google APIs in ihrem Namen erhalten. Die Google-Kontoverknüpfung deckt den umgekehrten Fall ab, in dem der Nutzer eines Google-Dienstes sich bei Ihrer Plattform authentifizieren und die APIs Ihres Dienstes aufrufen kann. Wenn Sie OAuth 2.0 für den Zugriff auf Google APIs verwenden möchten, lesen Sie die Dokumentation zum OAuth 2.0-Client.

Kontoverknüpfungsvorgänge

Es gibt drei Google-Kontoverknüpfungsvorgänge, die alle auf OAuth basieren und bei denen Sie OAuth 2.0-konforme Autorisierungs- und Tokenaustausch-Endpunkte verwalten oder steuern müssen.

Während des Verknüpfungsvorgangs stellen Sie Zugriffstokens für einzelne Google-Konten aus, nachdem Sie die Zustimmung der Kontoinhaber erhalten haben, ihre Konten zu verknüpfen und Daten freizugeben.

OAuth-Verknüpfung („Web-OAuth“)

Dies ist der grundlegende OAuth-Vorgang, bei dem Nutzer zum Verknüpfen auf Ihre Website weitergeleitet werden. Der Nutzer wird auf Ihre Website weitergeleitet, um sich in seinem Konto anzumelden. Nach der Anmeldung stimmt der Nutzer zu, seine Daten in Ihrem Dienst für Google freizugeben. An diesem Punkt werden das Google-Konto des Nutzers und Ihr Dienst verknüpft.

Die OAuth-Verknüpfung unterstützt die OAuth-Vorgänge mit Autorisierungscode und implizitem Ablauf. Ihr Dienst muss einen OAuth 2.0-konformen Autorisierungsendpunkt für den impliziten Ablauf hosten und sowohl einen Autorisierungs- als auch einen Tokenaustausch-Endpunkt bereitstellen, wenn der Ablauf mit Autorisierungscode verwendet wird.

Achtung:Für MCP-, UCP- und agentengesteuerte Abläufe ist OAuth 2.1 obligatorisch und der implizite Ablauf wird nicht unterstützt. Verwenden Sie stattdessen den Ablauf mit Autorisierungscode.

Hinweis: Die Implementierung von Web-OAuth ist für alle Kontoverknüpfungsintegrationen erforderlich, da es die Fallback-Methode für App-Flip- und optimierte Abläufe ist.

Abbildung 1. Kontoverknüpfung auf dem Smartphone eines Nutzers mit Web-OAuth

OAuth-basierte App-Flip-Verknüpfung („App-Flip“)

Ein OAuth-Vorgang, bei dem Nutzer zum Verknüpfen zu Ihrer App weitergeleitet werden.

Bei der OAuth-basierten App-Flip-Verknüpfung werden Nutzer zwischen Ihren verifizierten Android- oder iOS-Apps und der Google-Plattform hin- und hergeleitet, um die vorgeschlagenen Änderungen beim Datenzugriff zu prüfen und ihre Zustimmung zu erteilen, ihr Konto auf Ihrer Plattform mit ihrem Google-Konto zu verknüpfen. Damit App-Flip funktioniert, muss Ihr Dienst die OAuth-Verknüpfung oder die OAuth-basierte Verknüpfung mit „Über Google anmelden“ mit dem Autorisierungscode -Ablauf unterstützen.

App-Flip wird sowohl für Android als auch für iOS unterstützt.

So gehts :

Die Google App prüft, ob Ihre App auf dem Gerät des Nutzers installiert ist:

• Wenn die App gefunden wird, wird der Nutzer zu Ihrer App weitergeleitet. Ihre App holt die Zustimmung des Nutzers ein, das Konto mit Google zu verknüpfen, und leitet den Nutzer dann wieder zur Google-Oberfläche weiter.
• Wenn die App nicht gefunden wird oder ein Fehler während des App-Flip-Verknüpfungsvorgangs auftritt, wird der Nutzer zum optimierten oder Web-OAuth-Ablauf weitergeleitet.

Abbildung 2. Kontoverknüpfung auf dem Smartphone eines Nutzers mit App-Flip

OAuth-basierte optimierte Verknüpfung („Optimiert“)

Bei der OAuth-basierten optimierten Verknüpfung mit „Über Google anmelden“ wird „Über Google anmelden“ zusätzlich zur OAuth-Verknüpfung verwendet. So können Nutzer den Verknüpfungsvorgang abschließen, ohne die Google-Oberfläche zu verlassen. Dadurch werden Reibungsverluste und Abbrüche reduziert. Die OAuth-basierte optimierte Verknüpfung bietet die beste Nutzererfahrung mit nahtloser Anmeldung, Kontoerstellung und Kontoverknüpfung, indem „Über Google anmelden“ mit der OAuth-Verknüpfung kombiniert wird. Ihr Dienst muss OAuth 2.0-konforme Autorisierungs- und Tokenaustausch-Endpunkte unterstützen. Außerdem muss Ihr Tokenaustausch-Endpunkt JSON Web Token (JWT)-Assertionen unterstützen und die check, create und get -Intents implementieren.

Hinweis: Der Nutzer verlässt die Google-Oberfläche während dieses Vorgangs nie. Daher muss Google im Namen des Drittanbieters die Zustimmung einholen, damit der Vorgang ordnungsgemäß funktioniert.

So gehts :

Google bestätigt das Nutzerkonto und gibt diese Informationen an Sie weiter:

• Wenn in Ihrer Datenbank ein Konto für den Nutzer vorhanden ist, verknüpft der Nutzer sein Google-Konto erfolgreich mit seinem Konto in Ihrem Dienst.
• Wenn in Ihrer Datenbank kein Konto für den Nutzer vorhanden ist, kann der Nutzer entweder ein neues Drittanbieterkonto mit den von Google bestätigten Informationen erstellen : E-Mail-Adresse, Name und Profilbild oder sich anmelden und mit einer anderen E-Mail-Adresse verknüpfen. Dazu muss er sich mit Web-OAuth in Ihrem Dienst anmelden.

Abbildung 3. Kontoverknüpfung auf dem Smartphone eines Nutzers mit optimierter Verknüpfung

Welchen Vorgang sollten Sie verwenden?

Wir empfehlen, alle Abläufe zu implementieren, damit Nutzer die bestmögliche Verknüpfungserfahrung erhalten. Die optimierten und App-Flip-Abläufe reduzieren Reibungsverluste bei der Verknüpfung, da Nutzer den Verknüpfungsvorgang in nur wenigen Schritten abschließen können. Die Web-OAuth-Verknüpfung erfordert den geringsten Aufwand und ist ein guter Ausgangspunkt. Danach können Sie die anderen Verknüpfungsvorgänge hinzufügen.

**Hinweis**: Der Web-OAuth-Vorgang ist für alle Integrationen erforderlich, da er als Fallback für die anderen Vorgänge dient.

Mit Tokens arbeiten

Die Google-Kontoverknüpfung basiert auf dem OAuth 2.0-Branchenstandard.

Mit Tokens arbeiten

Sie stellen Zugriffstokens für einzelne Google-Konten aus, nachdem Sie die Zustimmung der Kontoinhaber erhalten haben, ihre Konten zu verknüpfen und Daten freizugeben.

Arten von Tokens

Bei OAuth 2.0 werden Strings, sogenannte Tokens, verwendet, um zwischen dem User-Agent, der Clientanwendung und dem OAuth 2.0-Server zu kommunizieren.

Bei der Kontoverknüpfung können drei Arten von OAuth 2.0-Tokens verwendet werden:

• Autorisierungscode: Ein kurzlebiges Token, das gegen ein Zugriffs- und ein Aktualisierungstoken eingetauscht werden kann. Aus Sicherheitsgründen ruft Google Ihren Autorisierungsendpunkt auf, um einen einmaligen oder sehr kurzlebigen Code abzurufen.

• Zugriffstoken: Ein Token, das dem Inhaber Zugriff auf eine Ressource gewährt. Um das Risiko zu begrenzen, das durch den Verlust dieses Tokens entstehen könnte, hat es eine begrenzte Lebensdauer, die in der Regel nach etwa einer Stunde abläuft.

• Aktualisierungstoken Ein langlebiges Token, das gegen ein neues Zugriffstoken eingetauscht werden kann, wenn ein Zugriffstoken abläuft. Bei der Einbindung Ihres Dienstes in Google wird dieses Token ausschließlich von Google gespeichert und verwendet. Google ruft Ihren Tokenaustausch-Endpunkt auf, um Aktualisierungstokens gegen Zugriffstokens auszutauschen, die wiederum für den Zugriff auf Nutzerdaten verwendet werden.

Token-Verarbeitung

Race-Bedingungen in geclusterten Umgebungen und Client-Server-Austauschen können bei der Arbeit mit Tokens zu komplexen Timing- und Fehlerbehandlungsszenarien führen. Beispiel:

• Sie erhalten eine Anfrage für ein neues Zugriffstoken und stellen ein neues aus. Gleichzeitig erhalten Sie eine Anfrage für den Zugriff auf die Ressource Ihres Dienstes mit dem vorherigen, nicht abgelaufenen Zugriffstoken.
• Google hat die Antwort auf deine Aktualisierungstokenanfrage noch nicht erhalten (oder wird sie nie erhalten). In der Zwischenzeit wird in einer Anfrage von Google das zuvor gültige Aktualisierungstoken verwendet.

Anfragen und Antworten können in beliebiger Reihenfolge oder gar nicht eintreffen, weil asynchrone Dienste in einem Cluster ausgeführt werden, aufgrund von Netzwerkverhalten oder aus anderen Gründen.

Ein sofortiger und vollständig konsistenter gemeinsamer Status sowohl innerhalb als auch zwischen den Token-Verarbeitungssystemen von Ihnen und Google kann nicht garantiert werden. Mehrere gültige, nicht abgelaufene Tokens können innerhalb oder zwischen Systemen innerhalb kurzer Zeit nebeneinander existieren. Um negative Auswirkungen auf die Nutzer zu minimieren, empfehlen wir Folgendes:

• Nicht abgelaufene Zugriffstokens akzeptieren, auch wenn ein neueres Token ausgestellt wurde.
• Alternativen zur Tokenrotation verwenden
• Unterstützung mehrerer gleichzeitig gültiger Zugriffs- und Aktualisierungstokens. Aus Sicherheitsgründen sollten Sie die Anzahl der Tokens und die Tokenlebensdauer begrenzen.

Wartungs- und Ausfallbehandlung

Bei Wartungsarbeiten oder unerwarteten Ausfällen kann Google Ihre Autorisierungs- oder Token-Austauschendpunkte möglicherweise nicht aufrufen, um Zugriffs- und Aktualisierungstokens zu erhalten.

Ihre Endpunkte sollten mit einem 503-Fehlercode und einem leeren Text antworten. In diesem Fall wiederholt Google fehlgeschlagene Tokentauschanfragen für eine begrenzte Zeit. Wenn Google später Aktualisierungs- und Zugriffstokens abrufen kann, sind fehlgeschlagene Anfragen für Nutzer nicht sichtbar.

Warnung: Geben Sie während Wartungsarbeiten oder Ausfällen keinen 400-Fehlercode und keinen {"error": "invalid_grant"}-Text zurück. Dadurch werden zuvor ausgestellte Tokens gelöscht und Nutzer müssen ihre Konten neu verknüpfen.

Fehlgeschlagene Anfragen für ein Zugriffstoken führen zu einem sichtbaren Fehler, wenn sie von einem Nutzer initiiert werden. Wenn der implizite OAuth 2.0-Vorgang verwendet wird, müssen Nutzer noch einmal versuchen, eine Verknüpfung herzustellen.

Empfehlungen

Es gibt viele Lösungen, um die Auswirkungen auf die Wartung zu minimieren. Hier sind einige Optionen:

• Behalten Sie Ihren vorhandenen Dienst bei und leiten Sie eine begrenzte Anzahl von Anfragen an Ihren neu aktualisierten Dienst weiter. Migrieren Sie alle Anfragen erst, nachdem Sie die erwartete Funktionalität bestätigt haben.

• Reduzieren Sie die Anzahl der Tokenanfragen während der Wartungszeit:

  • Begrenzen Sie Wartungszeiträume auf eine kürzere Dauer als die Lebensdauer des Zugriffstokens.

  • Lebensdauer des Zugriffstokens vorübergehend verlängern:

    1. Tokenlebensdauer auf länger als den Wartungszeitraum erhöhen.
    2. Warten Sie doppelt so lange wie die Lebensdauer des Zugriffstokens, damit Nutzer kurzlebige Tokens gegen Tokens mit längerer Gültigkeitsdauer eintauschen können.
    3. Wartung eingeben
    4. Antworten Sie auf Tokenanfragen mit dem Fehlercode 503 und einem leeren Textkörper.
    5. Beenden Sie die Wartung.
    6. Verringern Sie die Tokenlebensdauer wieder auf den Normalwert.

Persistente Verknüpfung

Die persistente Verknüpfung ist eine grundlegende Voraussetzung für stabile Integrationen. Sie sorgt dafür, dass Nutzerkonten auch bei vorübergehenden Netzwerkausfällen oder regelmäßigen Aktualisierungen der Anmeldedaten verknüpft bleiben.

Verwenden Sie für die Implementierung der persistenten Verknüpfung einen Ansatz mit „gleitendem Fenster“: Verlängern Sie das Ablaufdatum des vorhandenen Aktualisierungstokens, anstatt es zu rotieren (siehe RFC 6749, Abschnitt 6). So werden Race-Bedingungen und unbeabsichtigte Aufhebungen der Verknüpfung verhindert, die auftreten können, wenn ein neues Aktualisierungstoken ausgestellt, aber nicht erfolgreich von Google empfangen oder gespeichert wird.

Bei Google registrieren

Wir benötigen Details zu Ihrer OAuth 2.0-Einrichtung und müssen Anmeldedaten freigeben, um die Kontoverknüpfung zu aktivieren. Weitere Informationen finden Sie unter Registrierung.