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-Verknü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 unverändert in der Weiterleitungs-URI 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 von Google angeforderten Daten.
user_locale Optional. Die Spracheinstellung des Google-Kontos, angegeben mit einem BCP-47-Sprachtag (z. B. en-US).
code_challenge (Erforderlich für OAuth 2.1) Die aus dem Code-Verifier abgeleitete Challenge.
code_challenge_method (Optional) Die Methode, mit der die Challenge abgeleitet wurde (z.B. S256).

Token Exchange-Endpunkt

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

  • 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.
code_verifier (Für PKCE erforderlich) Der ursprüngliche kryptografische Zufallsstring.

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.

OpenAPI 3.1-Schema

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • 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.

Streamlined Linking-Intents verarbeiten

Wenn Ihr Dienst Streamlined Account Linking (OAuth mit „Mit Google anmelden“) unterstützt, muss Ihr Token-Austausch-Endpunkt zusätzlich JWT-Assertions (JSON Web Token) unterstützen und die erforderlichen Intents check und get sowie optional den Intent create 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 optional 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 Kriterien im Abschnitt JWT-Validierung 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 der erfolgreichen 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 die Intention create (optional)

Die Intention create ist optional. Wenn Ihr Dienst die Kontoerstellung über die vereinfachte Verknüpfung unterstützt, wird mit einer Anfrage mit intent=create die Erstellung eines neuen Nutzerkontos mit den im JWT bereitgestellten Informationen initiiert.

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

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

Wenn der Nutzer bereits vorhanden ist oder Ihr Dienst die Kontoerstellung nicht unterstützt, wird ein HTTP 401-Fehler zurückgegeben, damit Google auf den standardmäßigen OAuth-Verknüpfungsablauf zurückgreift.

  • 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 „Optimierte Verknüpfung“ oder „Anmeldung mit nur einem Fingertipp“ 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 erfolglosen 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>