Ü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
Standard-Kontoverknüpfung	Smart Home, TV und YouTube.	Google Docs

Hinweis:Diese Integrationspfade ergänzen sich. Wenn Sie UCP implementieren, empfehlen wir Ihnen, sowohl den Leitfaden UCP-Identitätsverknüpfung für produktspezifische Anforderungen als auch diese Dokumentation für wichtige OAuth-Implementierungsdetails zu lesen.

Durch die Kontoverknüpfung können Google-Kontoinhaber 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 mit Google-Apps und ‑Diensten zu teilen.

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 auf Ihrer Plattform ein neues Konto mit einer Google-Kontoverknüpfung erstellen.

Anwendungsfälle

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

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

• Integration mit Google Shopping und KI-Plattformen (Suche, Gemini) über das Universal Commerce Protocol (UCP).

• Du kannst deine Video- und Filminhalte mit Google TV abspielen.

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

• Mit Conversational Actions können Sie benutzerdefinierte Google Assistant-Funktionen und ‑Funktionalitäten 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 weitergegebenen Daten aus einem Google-Konto-Profil vorab ausfüllen.

Funktionen und Anforderungen

In der folgenden Tabelle sind die Unterstützung und Empfehlungen für die einzelnen Verknüpfungsabläufe definiert.

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

• Verbessern Sie den Datenschutz der Nutzer, indem Sie benutzerdefinierte Bereiche definieren, um nur die erforderlichen Daten freizugeben. Steigern Sie das Vertrauen der Nutzer, indem Sie klar definieren, wie ihre Daten verwendet werden.

• Der Zugriff auf Daten und Dienste, die auf Ihrer Plattform gehostet werden, kann durch Aufheben der Verknüpfung von Konten widerrufen werden. Durch die Implementierung eines optionalen Endpunkts für den Widerruf von Tokens können Sie mit von Google initiierten Ereignissen synchron bleiben. Mit 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-Kontoanmeldung deckt den umgekehrten Fall ab, in dem ein Nutzer eines Google-Dienstes sich bei Ihrer Plattform authentifizieren und die APIs Ihres Dienstes aufrufen kann. Wenn Sie mit OAuth 2.0 auf Google APIs zugreifen möchten, lesen Sie die Dokumentation zu OAuth 2.0-Clients.

Kontoverknüpfungsvorgänge

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

Während der Verknüpfung stellen Sie Google Zugriffstokens für einzelne Google-Konten aus, nachdem Sie die Einwilligung der Kontoinhaber zum Verknüpfen ihrer Konten und zum Freigeben von Daten eingeholt haben.

OAuth-Verknüpfung

Dies ist der OAuth-Verknüpfungsvorgang, 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, dass seine Daten in Ihrem Dienst an Google weitergegeben werden. Zu diesem Zeitpunkt sind das Google-Konto des Nutzers und Ihr Dienst verknüpft.

OAuth-Verknüpfung unterstützt die OAuth-Abläufe mit Autorisierungscode und implizit. Ihr Dienst muss einen OAuth 2.0-kompatiblen Autorisierungsendpunkt für den impliziten Ablauf hosten und sowohl einen Autorisierungs- als auch einen Token-Austauschendpunkt verfügbar machen, wenn der Autorisierungscode-Vorgang verwendet wird.

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

Hinweis: Die Implementierung der OAuth-Verknüpfung ist für alle Integrationen zur Kontoverknüpfung erforderlich, da sie die Fallback-Methode für App Flip- und optimierte Abläufe ist.

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

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

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

OAuth-basierte App Flip Linking führt Nutzer durch den Vorgang, wenn sie zwischen Ihren bestätigten mobilen Android- oder iOS-Apps und der Google-Plattform wechseln, um die vorgeschlagenen Änderungen beim Datenzugriff zu prüfen und ihre Einwilligung zur Verknüpfung ihres Kontos auf Ihrer Plattform mit ihrem Google-Konto zu erteilen. Damit App Flip funktioniert, muss Ihr Dienst OAuth-Verknüpfung oder OAuth-basierte Über Google anmelden-Verknüpfung 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 Einwilligung des Nutzers ein, das Konto mit Google zu verknüpfen, und leitet den Nutzer dann zurück zur Google-Oberfläche.
• Wenn die App nicht gefunden wird oder beim Verknüpfen über App-Flip ein Fehler auftritt, wird der Nutzer zum vereinfachten oder OAuth-Verknüpfungsablauf weitergeleitet.

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

Vereinfachte Verknüpfung auf OAuth-Basis („vereinfacht“)

Mit der OAuth-basierten Anmeldung mit Google und der optimierten Verknüpfung wird die Anmeldung mit Google zusätzlich zur OAuth-Verknüpfung eingeführt. Nutzer können den Verknüpfungsprozess abschließen, ohne die Google-Oberfläche zu verlassen. So werden Reibungspunkte und Abbrüche reduziert. Die OAuth-basierte vereinfachte Verknüpfung bietet die beste Nutzerfreundlichkeit mit nahtloser Anmeldung, Kontoerstellung und Kontoverknüpfung, indem die Anmeldung mit Google mit der OAuth-Verknüpfung kombiniert wird. Ihr Dienst muss Autorisierungs- und Tokenaustauschendpunkte unterstützen, die mit OAuth 2.0 kompatibel sind. Außerdem muss Ihr Token-Austausch-Endpunkt JSON Web Token (JWT)-Assertions unterstützen und die Intents check, create und get implementieren.

Hinweis :Der Nutzer verlässt die Google-Oberfläche während dieses Ablaufs nie. Damit der Ablauf ordnungsgemäß funktioniert, muss Google daher die Einwilligung im Namen des Drittanbieters einholen.

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, hat der Nutzer sein Google-Konto erfolgreich mit seinem Konto in Ihrem Dienst verknüpft.
• Wenn in Ihrer Datenbank kein Konto für den Nutzer vorhanden ist, kann er entweder ein neues Drittanbieterkonto mit den von Google bereitgestellten Informationen E-Mail-Adresse, Name und Profilbild erstellen oder sich mit einer anderen E-Mail-Adresse anmelden und verknüpfen (dazu muss er sich über die OAuth-Verknüpfung in Ihrem Dienst anmelden).

Abbildung 3. Kontoverknüpfung auf dem Smartphone eines Nutzers mit Streamlined Linking

Welchen Ablauf sollten Sie verwenden?

Wir empfehlen, alle Abläufe zu implementieren, damit Nutzer die bestmögliche Verknüpfung erhalten. Die optimierten und App-Flip-Abläufe reduzieren die Reibung bei der Verknüpfung, da Nutzer den Verknüpfungsprozess in wenigen Schritten abschließen können. Der OAuth-Verknüpfungsablauf erfordert den geringsten Aufwand und ist ein guter Ausgangspunkt, bevor Sie die anderen Verknüpfungsabläufe hinzufügen.

Hinweis :Der OAuth-Verknüpfungsvorgang ist für alle Integrationen erforderlich, da er der Fallback für die anderen Vorgänge ist.

Mit Tokens arbeiten

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

Sie stellen Google Zugriffstokens für einzelne Google-Konten aus, nachdem Sie die Einwilligung der Kontoinhaber zum Verknüpfen ihrer Konten und zum Freigeben von Daten eingeholt haben.

Arten von Tokens

OAuth 2.0 verwendet Strings, sogenannte Tokens, für die Kommunikation zwischen dem User-Agent, der Clientanwendung und dem OAuth 2.0-Server.

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 einmal verwendbaren oder sehr kurzlebigen Code zu erhalten.

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

• Aktualisierungstoken. Ein langlebiges Token, das gegen ein neues Zugriffstoken eingetauscht werden kann, wenn ein Zugriffstoken abläuft. Wenn Ihr Dienst in Google eingebunden ist, wird dieses Token ausschließlich von Google gespeichert und verwendet. Google ruft Ihren Token-Austausch-Endpunkt auf, um Aktualisierungstokens gegen Zugriffstokens einzutauschen, die wiederum für den Zugriff auf Nutzerdaten verwendet werden.

Token-Verwaltung

Race-Bedingungen in Clusterumgebungen und Client-Server-Austausch können zu komplexen Szenarien für das Timing und die Fehlerbehandlung führen, wenn Sie mit Tokens arbeiten. Beispiel:

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

Anfragen und Antworten können in beliebiger Reihenfolge oder gar nicht eintreffen, da asynchrone Dienste in einem Cluster ausgeführt werden, das Netzwerkverhalten oder andere Faktoren eine Rolle spielen.

Ein sofortiger und vollständig konsistenter gemeinsamer Status kann weder in Ihren noch in den Token-Verwaltungssystemen von Google garantiert werden. Mehrere gültige, nicht abgelaufene Tokens können für kurze Zeit in oder zwischen Systemen vorhanden sein. Um negative Auswirkungen auf Nutzer zu minimieren, empfehlen wir Folgendes:

• Akzeptieren Sie nicht abgelaufene Zugriffstokens, auch nachdem ein neueres Token ausgestellt wurde.
• Verwenden Sie Alternativen zu Aktualisierungstoken-Rotation.
• Unterstützen Sie mehrere gleichzeitig gültige Zugriffs- und Aktualisierungstokens. Aus Sicherheitsgründen sollten Sie die Anzahl der Tokens und die Lebensdauer der Tokens begrenzen.

Wartung und Ausfallbehandlung

Während der Wartung oder bei ungeplanten Ausfällen kann Google möglicherweise Ihre Autorisierungs- oder Token-Austausch-Endpunkte nicht aufrufen, um Zugriffs- und Aktualisierungstokens zu erhalten.

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

Warnung: Geben Sie während der Wartung oder bei Ausfällen nicht den Fehlercode 400 und den Text {"error": "invalid_grant"} 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. Nutzer müssen Verknüpfungsfehler wiederholen, wenn der implizite OAuth 2.0-Ablauf verwendet wird.

Empfehlungen

Es gibt viele Lösungen, um die Auswirkungen der Wartung zu minimieren. Einige Optionen:

• Behalten Sie Ihren bestehenden 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 Token-Anfragen während des Wartungszeitraums:

  • Begrenzen Sie die Wartungszeiträume auf weniger als die Lebensdauer des Zugriffstokens.

  • Verlängern Sie die Lebensdauer des Zugriffstokens vorübergehend:

    1. Verlängern Sie die Lebensdauer des Tokens auf mehr als den Wartungszeitraum.
    2. Warten Sie doppelt so lange wie die Lebensdauer Ihres Zugriffstokens, damit Nutzer kurzlebige Tokens gegen Tokens mit längerer Lebensdauer austauschen können.
    3. Starten Sie die Wartung.
    4. Antworten Sie auf Token-Anfragen mit dem Fehlercode 503 und einem leeren Text.
    5. Beenden Sie die Wartung.
    6. Verringern Sie die Lebensdauer des Tokens wieder auf den Normalwert.

Persistente Verknüpfung

Die dauerhafte Verknüpfung ist eine grundlegende Voraussetzung für stabile Integrationen. So bleiben Nutzerkonten auch bei vorübergehenden Netzwerkfehlern oder regelmäßigen Aktualisierungen der Anmeldedaten verknüpft.

Verwenden Sie für die Implementierung von persistenten Links einen „Sliding Window“-Ansatz: Verlängern Sie das Ablaufdatum des vorhandenen Aktualisierungstokens, anstatt es zu rotieren (siehe RFC 6749, Abschnitt 6). Dadurch werden Race-Bedingungen und unbeabsichtigte Verknüpfungsaufhebungen 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 Anmeldedaten, um die Kontoverknüpfung zu ermöglichen. Weitere Informationen finden Sie unter Registrierung.