Ihre Account Linking API

Auf dieser Referenzseite werden die API-Endpunkte dokumentiert, die Ihr Dienst implementieren muss, um die Kontoverknüpfung mit Google zu unterstützen. Dazu gehören die OAuth-basierte Kontoverknüpfung, die vereinfachte Kontoverknüpfung und App-Flip.

Voraussetzungen und Standards

Damit Sie diese Endpunkte erfolgreich implementieren können, muss Ihr Dienst die folgenden Standards erfüllen:

  • OAuth 2.0: Entspricht RFC 6749.
  • Token-Widerruf: Entspricht RFC 7009.
  • JSON Web Tokens (JWT): Entsprechen RFC 7519 (für die vereinfachte Verknüpfung erforderlich).
  • HTTPS: Alle Endpunkte müssen über eine sichere HTTPS-Verbindung bereitgestellt werden.

Autorisierungsendpunkt

Der Autorisierungs-Endpunkt ist für die Authentifizierung von Nutzern und die Einholung ihrer Einwilligung zur Verknüpfung ihrer Konten mit Google zuständig.

  • URL:In der Actions Console oder Google Cloud Console konfiguriert.
  • Methode:GET

Anfrageparameter

Parameter Beschreibung
client_id Die Client-ID, die Sie Google zugewiesen haben.
redirect_uri Die URL, an die Sie die Antwort auf diese Anfrage senden.
state Nachverfolgungswert, der im Weiterleitungs-URI unverändert an Google zurückgegeben wird.
response_type Muss code für den Autorisierungscode-Vorgang sein.
scope (Optional) Durch Leerzeichen getrennte Liste der Bereiche für die Daten, die Google anfordert.
user_locale (Optional) Die Spracheinstellung des Google-Kontos, angegeben mit einem BCP-47-Sprachtag (z.B. en-US).

Token-Exchange-Endpunkt

Dieser Endpunkt ist für den Austausch von Autorisierungscodes gegen Tokens und das Aktualisieren abgelaufener Zugriffstokens zuständig.

  • URL:In der Actions Console oder Google Cloud Console konfiguriert.
  • Methode:POST
  • Content-Type:application/x-www-form-urlencoded

Autorisierungscode gegen Tokens tauschen

Die folgenden Parameter werden in der ursprünglichen Anfrage zum Tauschen von Tokens verwendet.

Anfrageparameter

Parameter Beschreibung
client_id Die Client-ID, die Sie Google zugewiesen haben.
client_secret Der Clientschlüssel, den Sie Google zugewiesen haben.
grant_type Muss authorization_code lauten.
code Der vom Autorisierungsendpunkt empfangene Autorisierungscode.
redirect_uri Derselbe Weiterleitungs-URI, der in der ursprünglichen Anfrage verwendet wurde.

Aktualisierungstoken gegen Zugriffstoken eintauschen

Die folgenden Parameter werden verwendet, wenn ein Zugriffstoken aktualisiert wird.

Anfrageparameter

Parameter Beschreibung
client_id Die Client-ID, die Sie Google zugewiesen haben.
client_secret Der Clientschlüssel, den Sie Google zugewiesen haben.
grant_type Muss refresh_token lauten.
refresh_token Das zuvor an Google ausgegebene Aktualisierungstoken.

Antwort (JSON)

Geben Sie eine erfolgreiche Antwort mit einem JSON-Objekt im Text der HTTPS-Antwort zurück.

  • HTTP-Status:200 OK
  • Content-Type:application/json;charset=UTF-8
Felder Beschreibung
token_type Erforderlich. Muss bearer lauten.
access_token Erforderlich. Ein kurzlebiges Token, das für den Zugriff auf die APIs Ihres Dienstes verwendet wird.
refresh_token Erforderlich für authorization_code grant_type. Ein langlebiges Token, mit dem neue Zugriffstokens abgerufen werden.
expires_in Erforderlich. Die verbleibende Lebensdauer des Zugriffstokens in Sekunden.

Fehlerantworten

Wenn eine Anfrage an den Token-Endpunkt fehlschlägt, geben Sie den Fehler HTTP 400 Bad Request zusammen mit einer JSON-Antwort mit den folgenden Feldern zurück:

  • HTTP-Status:400 Bad Request
  • Content-Type:application/json;charset=UTF-8
Fehlerfelder (JSON) Beschreibung
error Erforderlich. Muss invalid_grant lauten.
error_description (Optional) Für Menschen lesbarer Text mit zusätzlichen Informationen.

Optimierte Verknüpfungs-Intents verarbeiten

Wenn Ihr Dienst Streamlined Account Linking (OAuth mit „Mit Google anmelden“) unterstützt, muss Ihr Token-Austausch-Endpunkt zusätzlich JSON Web Token-Assertions (JWT) unterstützen und die Intents check, create und get implementieren.

In diesen Anfragen werden die folgenden Parameter verwendet:

Anfrageparameter

Parameter Beschreibung
intent Die spezifische Intention für die vereinfachte Verknüpfung, die angefordert wird: check, get oder create.
grant_type Bei diesen Anfragen hat dieser Parameter immer den Wert urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Ein JSON Web Token (JWT), das eine signierte Behauptung der Identität des Google-Nutzers enthält. Das JWT enthält Informationen wie die Google-Konto-ID, den Namen und die E-Mail-Adresse des Nutzers.

 Ihr Server muss dieses JWT anhand der im Abschnitt JWT-Validierung aufgeführten Kriterien validieren.
client_id Die Client-ID, die Sie Google zugewiesen haben.
client_secret Der Clientschlüssel, den Sie Google zugewiesen haben.
scope Optional:Alle Bereiche, die Sie für Google konfiguriert haben, um sie von Nutzern anzufordern. Normalerweise bei den Intents get und create vorhanden.
response_type Erforderlich für die Intention create:Muss auf token festgelegt sein.

JWT-Validierung

Damit die Sicherheit der vereinfachten Verknüpfung gewährleistet ist, muss Ihr Server das assertion (JWT) anhand der folgenden Kriterien validieren:

  • Signatur: Prüfen Sie die Signatur anhand der öffentlichen Schlüssel von Google (verfügbar am JWK-Endpunkt von Google).
  • Aussteller (iss): Muss https://accounts.google.com sein.
  • Zielgruppe (aud): Muss mit der Google API-Client-ID übereinstimmen, die Ihrer Integration zugewiesen ist.
  • Ablaufdatum (exp): Muss in der Zukunft liegen.

Antwort für den Intent check

Mit einer Anfrage mit intent=check wird geprüft, ob das Google-Konto (identifiziert durch die Anforderung sub oder email in der decodierten JWT-Assertion) in Ihrer Nutzerdatenbank vorhanden ist.

  • HTTP-Status:200 OK (Konto gefunden) oder 404 Not Found (Konto nicht gefunden)
  • Content-Type:application/json;charset=UTF-8
Felder Beschreibung
account_found Erforderlich. true, wenn das Konto vorhanden ist, andernfalls false.

Antwort für den Intent get

Bei einer Anfrage mit intent=get wird ein Zugriffstoken für ein bestehendes Google-Konto angefordert.

  • HTTP-Status:200 OK
  • Content-Type:application/json;charset=UTF-8

Das JSON-Objekt für eine erfolgreiche Antwort hat genau dieselbe Struktur wie eine Standardantwort für den Tokenaustausch (mit access_token, refresh_token usw.).

Wenn das Konto nicht verknüpft werden kann, wird ein HTTP-Fehler 401 zurückgegeben.

  • HTTP-Status:401 Unauthorized
  • Content-Type:application/json;charset=UTF-8
Fehlerfelder (JSON) Beschreibung
error Erforderlich. Muss linking_error lauten.
login_hint Optional: Die E-Mail-Adresse des Nutzers, die an den Fallback-OAuth-Verknüpfungsablauf übergeben werden soll.

Antwort für den Intent create

Bei einer Anfrage mit intent=create wird ein neues Nutzerkonto mit den im JWT angegebenen Informationen erstellt.

  • HTTP-Status:200 OK
  • Content-Type:application/json;charset=UTF-8

Das JSON-Objekt für eine erfolgreiche Antwort hat genau dieselbe Struktur wie eine Standardantwort für den Tokenaustausch (mit access_token, refresh_token usw.).

Wenn der Nutzer bereits vorhanden ist, wird ein HTTP 401-Fehler zurückgegeben, um den Nutzer aufzufordern, sein bestehendes Konto zu verknüpfen.

  • HTTP-Status:401 Unauthorized
  • Content-Type:application/json;charset=UTF-8
Fehlerfelder (JSON) Beschreibung
error Erforderlich. Muss linking_error lauten.
login_hint Die E-Mail-Adresse des Nutzers, die an den Fallback-OAuth-Verknüpfungsablauf übergeben werden soll.

UserInfo-Endpunkt (optional)

Wird verwendet, um grundlegende Profilinformationen zum verknüpften Nutzer abzurufen, wie in der OpenID Connect Core 1.0-Spezifikation beschrieben. Dies ist für Funktionen wie „Vereinfachte Verknüpfung“ oder „Anmelden mit nur einem Tippen“ erforderlich.

  • Methode:GET
  • Authentifizierung:Authorization: Bearer ACCESS_TOKEN

Antwort (JSON)

Geben Sie eine erfolgreiche Antwort mit einem JSON-Objekt im Text der HTTPS-Antwort zurück.

  • HTTP-Status:200 OK
  • Content-Type:application/json;charset=UTF-8

Antwortfelder

Felder Beschreibung
sub Erforderlich. Eine eindeutige ID, die den Nutzer in Ihrem System identifiziert.
email Erforderlich. Die E-Mail-Adresse des Nutzers.
email_verified Erforderlich. Ein boolescher Wert, der angibt, ob die E‑Mail-Adresse bestätigt wurde.
given_name Optional: Der Vorname des Nutzers.
family_name Optional: Der Nachname des Nutzers.
name Optional: Der vollständige Name des Nutzers.
picture (Optional) Eine URL zum Profilbild des Nutzers.

Fehlerantworten

Wenn das Zugriffstoken ungültig oder abgelaufen ist, gib den Fehler HTTP 401 Unauthorized zurück. Sie sollten auch den Antwortheader WWW-Authenticate angeben.

Alle nicht erfolgreichen Antworten (4xx oder 5xx), die während des Verknüpfungsvorgangs zurückgegeben werden, gelten als nicht behebbar. In diesen Fällen verwirft Google alle abgerufenen Tokens und der Nutzer muss den Konto-Verknüpfungsprozess noch einmal starten.

Endpunkt zum Widerrufen des Tokens (optional)

Ermöglicht es Google, Ihren Dienst zu benachrichtigen, wenn ein Nutzer die Verknüpfung seines Kontos mit der Google-Oberfläche aufhebt. Dieser Endpunkt muss den in RFC 7009 beschriebenen Anforderungen entsprechen.

  • Methode:POST
  • Content-Type:application/x-www-form-urlencoded

Anfrageparameter

Parameter Beschreibung
client_id Ein String, der Google als Ursprung der Anfrage identifiziert. Dieser String muss in Ihrem System als eindeutige Kennung von Google registriert sein.
client_secret Ein geheimer String, den Sie bei Google für Ihren Dienst registriert haben.
token Das zu widerrufende Token.
token_type_hint Optional: Ein Hinweis zum Typ des widerrufenen Tokens, entweder access_token oder refresh_token. Wenn nicht angegeben, lautet die Standardeinstellung access_token.

Antworten

Geben Sie eine erfolgreiche Antwort zurück, wenn das Token erfolgreich gelöscht wurde oder wenn das Token bereits ungültig ist.

  • HTTP-Status:200 OK
  • Content-Type:application/json;charset=UTF-8

Fehlerantworten

Wenn das Token aus irgendeinem Grund nicht gelöscht werden kann (z.B. weil die Datenbank nicht verfügbar ist), gib einen HTTP-Fehler 503 zurück. Google wird die Anfrage später oder gemäß dem Retry-After-Header noch einmal versuchen.

  • HTTP-Status:503 Service Unavailable
  • Content-Type:application/json;charset=UTF-8
  • Header: Retry-After: <HTTP-date / delay-seconds>