Google-Kontoverknüpfung mit OAuth

Konten werden über den Branchenstandard-OAuth 2.0-Vorgang mit Autorisierungscode verknüpft.

OAuth 2.1 und PKCE für Agents

Für zustandslose KI-Agents und multimodale Pipelines wird die OAuth 2.1-Durchsetzung empfohlen.

  • PKCE (Proof Key for Code Exchange): Muss verwendet werden, um den Autorisierungscode-Vorgang zu schützen und Abfangangriffe zu verhindern.
  • Kein impliziter Ablauf: Beim impliziten Ablauf werden Zugriffstokens in der URL verfügbar gemacht, was ein Sicherheitsrisiko für Agent-Umgebungen darstellt.

Ihr Dienst muss OAuth 2.0-/2.1-konforme Autorisierungs- und Tokenaustausch-Endpunkte unterstützen.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

    Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

    Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

    Support email: For users to contact you with questions about their consent.

    Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

    Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

    Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

    Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

    Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

    Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

  4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

OAuth-Server implementieren

Eine OAuth 2.0-Serverimplementierung des Autorisierungscode-Ablaufs besteht aus zwei Endpunkten, die Ihr Dienst über HTTPS zur Verfügung stellt. Der erste Endpunkt ist der Autorisierungsendpunkt, der dafür zuständig ist, die Einwilligung von Nutzern für den Datenzugriff zu finden oder einzuholen. Der Autorisierungsendpunkt präsentiert Nutzern, die noch nicht angemeldet sind, eine Anmeldeoberfläche und erfasst die Einwilligung für den angeforderten Zugriff. Der zweite Endpunkt ist der Tokenaustausch-Endpunkt, der verwendet wird, um verschlüsselte Strings (Tokens) zu erhalten, die einen Nutzer zum Zugriff auf Ihren Dienst autorisieren.

Wenn eine Google-Anwendung eine der APIs Ihres Dienstes aufrufen muss, verwendet Google diese Endpunkte zusammen, um die Erlaubnis Ihrer Nutzer zu erhalten, diese APIs in ihrem Namen aufzurufen.

Google-Kontoverknüpfung: OAuth-Ablauf mit Autorisierungscode

Das folgende Sequenzdiagramm zeigt die Interaktionen zwischen dem Nutzer, Google und den Endpunkten Ihres Dienstes.

User Google App / Browser Google Server Your Auth Endpoint Your Token Endpoint 1. User initiates linking 2. Redirect to Auth Endpoint (GET) client_id, redirect_uri, state, scope 3. Display Sign-in & Consent Screen 4. User Authenticates & Grants Consent 5. Redirect back to Google (GET) code, state 6. Handle redirect & pass code/state 7. Token Exchange (POST) grant_type=authorization_code, code 8. Return Tokens (200 OK) access_token, refresh_token 9. Store user tokens 10. Access user resources
Figure 1. Die Abfolge der Ereignisse im OAuth 2.0-Autorisierungscode-Vorgang für die Google-Kontoverknüpfung.

Rollen und Verantwortlichkeiten

In der folgenden Tabelle sind die Rollen und Verantwortlichkeiten der Akteure im OAuth-Ablauf für die Google-Kontoverknüpfung (GAL) definiert. Beachten Sie, dass in der GAL Google als der OAuth Client fungiert, während Ihr Dienst als der Identitäts-/Dienstanbieter fungiert.

Akteur / Komponente GAL-Rolle Zuständigkeiten
Google-App / Server OAuth-Client Leitet den Ablauf ein, empfängt den Autorisierungscode, tauscht ihn gegen Tokens ein und speichert sie sicher, um auf die APIs Ihres Dienstes zuzugreifen.
Ihr Autorisierungsendpunkt Autorisierungsserver Authentifiziert Ihre Nutzer und holt ihre Einwilligung ein, den Zugriff auf ihre Daten für Google freizugeben.
Ihr Tokenaustausch-Endpunkt Autorisierungsserver Validiert Autorisierungscodes und Aktualisierungstokens und stellt dem Google-Server Zugriffstokens aus.
Google-Weiterleitungs-URI Callback-Endpunkt Empfängt die Nutzerweiterleitung von Ihrem Autorisierungsdienst mit den code und state Werten.

Eine von Google initiierte OAuth 2.0-Sitzung mit Autorisierungscode hat folgenden Ablauf:

  1. Google öffnet Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn der Ablauf auf einem reinen Sprachgerät für eine Aktion gestartet wurde, überträgt Google die Ausführung auf ein Smartphone.
  2. Der Nutzer meldet sich an, falls er noch nicht angemeldet ist, und gewährt Google die Berechtigung, mit Ihrer API auf seine Daten zuzugreifen, falls er die Berechtigung noch nicht erteilt hat.
  3. Ihr Dienst erstellt einen Autorisierungscode und gibt ihn an Google zurück. Dazu leiten Sie den Browser des Nutzers mit dem Autorisierungscode, der an die Anfrage angehängt ist, zurück zu Google.
  4. Google sendet den Autorisierungscode an Ihren Tokenaustausch-Endpunkt, der die Authentizität des Codes überprüft und ein Zugriffstoken und ein Aktualisierungstoken zurückgibt. Das Zugriffstoken ist ein kurzlebiges Token, das Ihr Dienst als Anmeldedaten für den Zugriff auf APIs akzeptiert. Das Aktualisierungstoken ist ein langlebiges Token, das Google speichern und verwenden kann, um neue Zugriffstokens zu erhalten, wenn sie ablaufen.
  5. Nachdem der Nutzer den Ablauf für die Kontoverknüpfung abgeschlossen hat, enthält jede nachfolgende Anfrage von Google ein Zugriffstoken.

Implementierungsrezept

Folgen Sie dieser Anleitung, um den Autorisierungscode-Vorgang zu implementieren.

Schritt 1: Autorisierungsanfragen verarbeiten

Wenn Google die Kontoverknüpfung initiiert, wird der Nutzer zu Ihrem Autorisierungsendpunkt weitergeleitet. Ausführliche Protokollverträge und Parameteranforderungen finden Sie unter dem Autorisierungsendpunkt.

So verarbeiten Sie die Anfrage:

  1. Anfrage validieren:

    • Prüfen Sie, ob die client_id mit der Google zugewiesenen Client-ID übereinstimmt.
    • Prüfen Sie, ob die redirect_uri mit der erwarteten Google-Weiterleitungs URL: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID übereinstimmt
    • Prüfen Sie, ob response_type gleich code ist.

  2. Nutzer authentifizieren:

    • Prüfen Sie, ob der Nutzer in Ihrem Dienst angemeldet ist.
    • Wenn der Nutzer nicht angemeldet ist, fordern Sie ihn auf, den Anmelde- oder Registrierungsablauf zu durchlaufen.

  3. Autorisierungscode generieren:

    • Erstellen Sie einen eindeutigen, nicht erratbaren Autorisierungscode, der mit dem Nutzer und dem Client verknüpft ist.
    • Legen Sie fest, dass der Code in etwa 10 Minuten abläuft.

  4. Zurück zu Google weiterleiten:

    • Leiten Sie den Browser zur URL weiter, die in redirect_uri angegeben ist.
    • Hängen Sie die folgenden Suchparameter an:
      • code: Der von Ihnen generierte Autorisierungscode.
      • state: Der unveränderte Statuswert, der von Google empfangen wurde.

Schritt 2: Tokenaustauschanfragen verarbeiten

Ihr Tokenaustausch-Endpunkt verarbeitet zwei Arten von Anfragen: Austausch von Codes gegen Tokens und Aktualisierung abgelaufener Zugriffstokens. Ausführliche Protokollverträge und Parameteranforderungen finden Sie unter dem Tokenaustausch-Endpunkt.

A. Autorisierungscodes gegen Tokens austauschen

Wenn Google den Autorisierungscode empfängt, ruft es Ihren Tokenaustausch-Endpunkt (POST) auf, um Tokens abzurufen.

  1. Anfrage validieren:

    • Prüfen Sie client_id und client_secret.
    • Prüfen Sie, ob der Autorisierungscode gültig und nicht abgelaufen ist.
    • Prüfen Sie, ob redirect_uri mit dem in Schritt 1 verwendeten Wert übereinstimmt.
    • Wenn die Validierung fehlschlägt, geben Sie eine HTTP-Antwort 400 Bad Request mit {"error": "invalid_grant"} zurück.

  2. Tokens ausstellen:

    • Generieren Sie ein langlebiges refresh_token und ein kurzlebiges access_token (in der Regel 1 Stunde).
    • Geben Sie eine HTTP-Antwort 200 OK mit der Standard-JSON-Tokenantwort zurück.

B. Zugriffstokens aktualisieren

Wenn das Zugriffstoken abläuft, fordert Google mit dem Aktualisierungstoken ein neues an.

  1. Anfrage validieren:

    • Prüfen Sie client_id, client_secret und refresh_token.
    • Wenn die Validierung fehlschlägt, geben Sie eine HTTP-Antwort 400 Bad Request mit {"error": "invalid_grant"} zurück.

  2. Neues Zugriffstoken ausstellen:

    • Generieren Sie ein neues kurzlebiges access_token.
    • Geben Sie eine HTTP-Antwort 200 OK mit der JSON-Tokenantwort zurück (optional mit einem neuen Aktualisierungstoken).
Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

Implementierung validieren

Sie können Ihre Implementierung mit dem OAuth 2.0 Playground Tool validieren.

Führen Sie im Tool die folgenden Schritte aus:

  1. Klicken Sie auf die Konfigurationseinstellungen , um das Fenster „OAuth 2.0-Konfiguration“ zu öffnen.
  2. Wählen Sie im Feld OAuth-Ablauf die Option Clientseitig aus.
  3. Wählen Sie im Feld OAuth-Endpunkte die Option Benutzerdefiniert aus.
  4. Geben Sie in den entsprechenden Feldern Ihren OAuth 2.0-Endpunkt und die Client-ID an, die Sie Google zugewiesen haben.
  5. Wählen Sie im Abschnitt Schritt 1 keine Google-Bereiche aus. Lassen Sie dieses Feld stattdessen leer oder geben Sie einen für Ihren Server gültigen Bereich ein (oder eine beliebige Zeichenfolge, wenn Sie keine OAuth-Bereiche verwenden). Klicken Sie anschließend auf APIs autorisieren.
  6. Führen Sie in den Abschnitten Schritt 2 und Schritt 3 den OAuth 2.0-Ablauf durch und prüfen Sie, ob jeder Schritt wie vorgesehen funktioniert.

Sie können Ihre Implementierung mit dem Tool „Google-Kontoverknüpfung – Demo“ validieren.

Führen Sie im Tool die folgenden Schritte aus:

  1. Klicken Sie auf die Schaltfläche Mit Google anmelden.
  2. Wählen Sie das Konto aus, das Sie verknüpfen möchten.
  3. Geben Sie die Dienst-ID ein.
  4. Optional können Sie einen oder mehrere Bereiche eingeben, für die Sie Zugriff anfordern möchten.
  5. Klicken Sie auf Demo starten.
  6. Bestätigen Sie bei Aufforderung, dass Sie der Verknüpfungsanfrage zustimmen und sie ablehnen können.
  7. Bestätigen Sie, dass Sie zu Ihrer Plattform weitergeleitet werden.