Google Account Linking API

Auf dieser Referenzseite werden die von Google angebotenen Endpunkte und Schnittstellen dokumentiert, die von Ihrer App während der OAuth-basierten Kontoverknüpfung verwendet werden.

Voraussetzungen und Standards

Damit Ihre Integration erfolgreich mit diesen Google-Endpunkten interagieren kann, muss sie die folgenden Standards erfüllen:

  • OAuth 2.0: Entspricht RFC 6749.
  • JSON Web Tokens (JWT): Entsprechen RFC 7519 (für Streamlined Linking und RISC).
  • Sicherheitstokens: Entsprechen RFC 8417 (für RISC).
  • HTTPS: Alle Anfragen müssen über eine sichere HTTPS-Verbindung erfolgen.

OAuth-Weiterleitungs-URI

Der Endpunkt, an den der Browser des Nutzers nach erfolgreicher Authentifizierung und Einwilligung weitergeleitet wird. Der Pfadparameter YOUR_PROJECT_ID ist die ID, die Sie bei der Registrierung konfigurieren.

  • URL:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • Sandbox-URL:https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • Methode:GET (Browserweiterleitung)

Anfrageparameter

Wenn Sie den Nutzer zurück zu Google weiterleiten, müssen der URL Parameter angehängt werden. Je nach verwendetem OAuth-Ablauf werden diese Parameter entweder als Abfragestring (Vorgang mit Autorisierungscode) oder als URL-Fragment (impliziter Vorgang) formatiert.

Parameter Beschreibung
code (Erforderlich für den Autorisierungscode-Ablauf) Der von Ihrem Dienst generierte Autorisierungscode.
state (Erforderlich) Der unveränderte Statuswert, der ursprünglich von Google empfangen wurde.
access_token (Erforderlich für den impliziten Ablauf) Das von Ihrem Dienst generierte langlebige Zugriffstoken.
token_type (Erforderlich für den impliziten Ablauf) Muss bearer sein.

Fehlerantworten

Wenn die Anfrage an den OAuth-Weiterleitungs-URI fehlerhaft ist, erhalten Sie den Fehler HTTP 400 Bad Request. Der Antworttext enthält ein JSON-Objekt mit der folgenden Struktur:

Feld Beschreibung
sendPostBody Bestimmt, ob das JS mit POST zum redirectUri weiterleiten soll. Normalerweise false in diesem Szenario.
errorMessage Eine Fehlermeldung, die dem Client angezeigt wird, wenn die Weiterleitung nicht abgeschlossen werden kann. Bei fehlenden Fragmenten ist das "A URI fragment or query string must be set.".

OAuth 2.0-Fehlerantworten

Wenn der Nutzer die Einwilligung verweigert oder in Ihrem Dienst ein Fehler auftritt, muss Ihr Dienst den Nutzer mit Standard-OAuth 2.0-Fehlerparametern (z. B. error=access_denied) zurück zur OAuth-Weiterleitungs-URI weiterleiten. Google verarbeitet diese Parameter und zeigt dem Nutzer einen entsprechenden Fehlerbildschirm an.

RISC API (optional)

Wird von Ihrem Dienst verwendet, um Google proaktiv zu benachrichtigen, wenn ein Nutzer sein Konto auf Ihrer Plattform über das RISC-Protokoll trennt. So wird dafür gesorgt, dass beide Plattformen synchronisiert bleiben.

  • URL:https://risc.googleapis.com/v1/events:publish
  • Methode:POST
  • Authentifizierung:Erfordert ein Google-Dienstkonto-Token mit den entsprechenden Berechtigungen.
  • Content-Type:application/json

Security Event Token-Claims

Security Event Tokens, mit denen Sie Google über Ereignisse zum Widerruf von Tokens benachrichtigen, müssen den Anforderungen in der folgenden Tabelle entsprechen:

Anspruch Beschreibung
iss Aussteller-Anspruch:Dies ist eine URL, die Sie hosten und die bei der Registrierung an Google weitergegeben wird.
aud Anforderung „Zielgruppe“:Damit wird Google als JWT-Empfänger identifiziert. Es muss auf google_account_linking gesetzt sein.
jti JWT-ID-Anspruch:Dies ist eine eindeutige ID, die Sie für jedes Sicherheitsereignistoken generieren.
iat „Issued At“-Anspruch:Dies ist ein NumericDate-Wert, der den Zeitpunkt angibt, zu dem dieses Sicherheitstoken erstellt wurde.
toe Zeitpunkt der Ereignisbehauptung:Dies ist ein optionaler NumericDate-Wert, der den Zeitpunkt angibt, zu dem das Token widerrufen wurde.
exp Ablaufzeitpunkt des Anspruchs:Dieses Feld nicht angeben, da das Ereignis, das zu dieser Benachrichtigung geführt hat, bereits stattgefunden hat.
events Security Events Claim:Dies ist ein JSON-Objekt, das nur ein einzelnes Ereignis zum Widerrufen von Tokens mit den folgenden Feldern enthalten darf:

  • subject_type: Muss auf oauth_token festgelegt werden.
  • token_type: Der Typ des Tokens, das widerrufen wird, entweder access_token oder refresh_token.
  • token_identifier_alg: Dies ist der Algorithmus, der zum Codieren des Tokens verwendet wird. Er muss hash_SHA512_double sein.
  • token: Dies ist die ID des widerrufenen Tokens.

Weitere Informationen zu Feldtypen und ‑formaten finden Sie unter JSON Web Token (JWT).

„Flip-Back“-Schnittstelle für App-Flip

Beim App Flip muss Ihre mobile App den Autorisierungscode oder das Zugriffstoken an die Google-App zurückgeben.

Android (Intent-Ergebnis)

Ihre App wird über einen Intent geöffnet. Nach der Einwilligung wird der Vorgang abgeschlossen und ein Ergebnis an Google zurückgegeben. Weitere Informationen finden Sie im Android-Implementierungsleitfaden.

  • Aktion:com.google.android.gms.auth.CODE_AVAILABLE
  • Extras:code, state, access_token, token_type.

Ihre App öffnet Google entweder über ein benutzerdefiniertes URL-Schema oder einen universellen HTTPS-Link. Weitere Informationen finden Sie im Implementierungsleitfaden für iOS.

  • Format:<return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING