Google-Kontoverknüpfung mit OAuth

Konten werden über die Branchenstandard-OAuth 2.0-Vorgänge implizit und Autorisierungscode verknüpft.

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.

6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

Projekt erstellen

So erstellen Sie Ihr Projekt für die Kontoverknüpfung:

1. Gehen Sie zur Google API Console.
2. Klicken Sie auf Projekt erstellen.
3. Geben Sie einen Namen ein oder übernehmen Sie den generierten Vorschlag.
4. Bestätigen oder bearbeiten Sie die verbleibenden Felder.
5. Klicken Sie auf Erstellen.

So rufen Sie Ihre Projekt-ID auf:

1. Gehen Sie zur Google API Console.
2. Suchen Sie in der Tabelle auf der Landingpage nach Ihrem Projekt. Die Projekt-ID wird in der Spalte ID angezeigt.

OAuth-Zustimmungsbildschirm konfigurieren

Der Prozess zur Verknüpfung von Google-Konten umfasst einen Zustimmungsbildschirm, auf dem Nutzer darüber informiert werden, welche Anwendung Zugriff auf ihre Daten anfordert, welche Art von Daten angefordert werden und welche Nutzungsbedingungen gelten. Sie müssen den OAuth-Zustimmungsbildschirm konfigurieren, bevor Sie eine Google API-Client-ID generieren.

1. Öffnen Sie in der Google APIs Console die Seite OAuth-Zustimmungsbildschirm.
2. Wählen Sie bei Aufforderung das Projekt aus, das Sie gerade erstellt haben.

3. Füllen Sie auf der Seite „OAuth-Zustimmungsbildschirm“ das Formular aus und klicken Sie auf die Schaltfläche „Speichern“.

   Anwendungsname:Der Name der Anwendung, die um Einwilligung bittet. Der Name sollte Ihre Anwendung korrekt widerspiegeln und mit dem Anwendungsnamen übereinstimmen, den Nutzer an anderer Stelle sehen. Der Anwendungsname wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung angezeigt.

   App-Logo:Ein Bild auf dem Zustimmungsbildschirm, das Nutzern hilft, Ihre App zu erkennen. Das Logo wird auf dem Zustimmungsbildschirm für die Kontoverknüpfung und in den Kontoeinstellungen angezeigt.

   Support-E-Mail-Adresse:Für Nutzer, die Sie wegen Fragen zu ihrer Einwilligung kontaktieren möchten.

   Bereiche für Google-APIs:Mit Bereichen kann Ihre Anwendung auf die privaten Google-Daten Ihrer Nutzer zugreifen. Für die Verknüpfung von Google-Konten reicht der Standardbereich („email“, „profile“, „openid“) aus. Sie müssen keine sensiblen Bereiche hinzufügen. Es empfiehlt sich, Bereiche inkrementell anzufordern, wenn der Zugriff erforderlich ist, und nicht im Voraus. Weitere Informationen

   Autorisierte Domains:Um Sie und Ihre Nutzer zu schützen, erlaubt Google die Nutzung autorisierter Domains nur Anwendungen, die sich mit OAuth authentifizieren. Die Links Ihrer Anwendungen müssen auf autorisierten Domains gehostet werden. Weitere Informationen

   Link zur Startseite der Anwendung:Startseite Ihrer Anwendung. Muss auf einer autorisierten Domain gehostet werden.

   Link zur Datenschutzerklärung der Anwendung:Wird auf dem Zustimmungsbildschirm für die Verknüpfung von Google-Konten angezeigt. Muss auf einer autorisierten Domain gehostet werden.

   Link zu den Nutzungsbedingungen der Anwendung (optional): Muss auf einer autorisierten Domain gehostet werden.

   

   Abbildung 1. Zustimmungsbildschirm für die Google-Kontoverknüpfung für die fiktive App „Tunery“

4. Prüfen Sie den „Überprüfungsstatus“. Wenn Ihre Anwendung überprüft werden muss, klicken Sie auf die Schaltfläche „Zur Überprüfung einreichen“, um sie zur Überprüfung einzureichen. Weitere Informationen finden Sie unter Voraussetzungen für die OAuth-Überprüfung.

OAuth-Server implementieren

n

Zur Unterstützung des impliziten OAuth 2.0-Vorgangs stellt Ihr Dienst einen Autorisierungsendpunkt per HTTPS zur Verfügung. Dieser Endpunkt ist für die Authentifizierung und die Einholung der Einwilligung von Nutzern für den Datenzugriff verantwortlich. Der Autorisierungsendpunkt präsentiert Nutzern, die noch nicht angemeldet sind, eine Anmeldeoberfläche und erfasst die Einwilligung für den angeforderten Zugriff.

Wenn eine Google-Anwendung eine der autorisierten APIs Ihres Dienstes aufrufen muss, verwendet Google diesen Endpunkt, um die Berechtigung von Ihren Nutzern zu erhalten, diese APIs in ihrem Namen aufzurufen.

Google-Kontoverknüpfung: Impliziter OAuth-Vorgang

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

Rollen und Verantwortlichkeiten

In der folgenden Tabelle werden die Rollen und Verantwortlichkeiten der Akteure im impliziten OAuth-Vorgang für die Google-Kontoverknüpfung (Google Account Linking, GAL) definiert. Bei GAL fungiert Google als OAuth-Client, während Ihr Dienst als Identitäts-/Dienstanbieter fungiert.

Eine typische implizite OAuth 2.0-Vorgangssitzung, die von Google initiiert wurde, läuft so ab:

1. Google öffnet Ihren Autorisierungsendpunkt im Browser des Nutzers. Der Nutzer meldet sich an, falls er noch nicht angemeldet ist, und erteilt Google die Berechtigung, mit Ihrer API auf seine Daten zuzugreifen, falls er die Berechtigung noch nicht erteilt hat.
2. Ihr Dienst erstellt ein Zugriffstoken und gibt es an Google zurück. Leiten Sie dazu den Browser des Nutzers mit dem an die Anfrage angehängten Zugriffstoken zu Google weiter.
3. Google ruft die APIs Ihres Dienstes auf und hängt jeder Anfrage das Zugriffstoken an. Ihr Dienst prüft, ob das Zugriffstoken Google die Autorisierung für den Zugriff auf die API gewährt, und schließt dann den API-Aufruf ab.

Autorisierungsanfragen verarbeiten

Wenn eine Google-Anwendung eine Kontoverknüpfung mit einem impliziten OAuth 2.0-Vorgang durchführen muss, sendet Google den Nutzer mit einer Anfrage, die die folgenden Parameter enthält, an Ihren Autorisierungsendpunkt:

Wenn Ihr Autorisierungsendpunkt beispielsweise unter https://myservice.example.com/auth verfügbar ist, könnte eine Anfrage so aussehen:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

Führen Sie die folgenden Schritte aus, damit Ihr Autorisierungsendpunkt Anmeldeanfragen verarbeiten kann:

1. Prüfen Sie die Werte client_id und redirect_uri, um zu verhindern, dass nicht beabsichtigten oder falsch konfigurierten Client-Apps Zugriff gewährt wird:

   • Bestätigen Sie, dass client_id mit der Client-ID übereinstimmt, die Sie Google zugewiesen haben.
   • Bestätigen Sie, dass die durch den Parameter redirect_uri angegebene URL das folgende Format hat:

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

2. Prüfen Sie, ob der Nutzer in Ihrem Dienst angemeldet ist. Wenn der Nutzer nicht angemeldet ist, führen Sie den Anmelde- oder Registrierungsvorgang Ihres Dienstes aus.

3. Generieren Sie ein Zugriffstoken, das Google für den Zugriff auf Ihre API verwenden kann. Das Zugriffstoken kann ein beliebiger Stringwert sein, muss aber den Nutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und darf nicht erraten werden können.

4. Senden Sie eine HTTP-Antwort, die den Browser des Nutzers an die durch den redirect_uri Parameter angegebene URL weiterleitet. Fügen Sie alle folgenden Parameter in das URL-Fragment ein:

   • access_token: Das gerade generierte Zugriffstoken
   • token_type: Der String bearer
   • state: Der unveränderte Statuswert aus der ursprünglichen Anfrage

   Dies ist ein Beispiel für die resultierende URL:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Der OAuth 2.0-Weiterleitungshandler von Google empfängt das Zugriffstoken und bestätigt, dass sich der Wert state nicht geändert hat. Nachdem Google ein Zugriffstoken für Ihren Dienst erhalten hat, hängt Google das Token an nachfolgende Aufrufe Ihrer Dienst-APIs an.

userinfo-Anfragen verarbeiten

Der userinfo-Endpunkt ist eine geschützte OAuth 2.0-Ressource, die Ansprüche über den verknüpften Nutzer zurückgibt. Die Implementierung und das Hosten des userinfo-Endpunkts sind mit Ausnahme der folgenden Anwendungsfälle optional:

• Anmeldung in einem verknüpften Konto über Google One Tap.
• Reibungsloses Abo auf Android TV

Nachdem das Zugriffstoken erfolgreich von Ihrem Tokenendpunkt abgerufen wurde, sendet Google eine Anfrage an Ihren userinfo-Endpunkt, um grundlegende Profilinformationen über den verknüpften Nutzer abzurufen.

Wenn Ihr userinfo-Endpunkt beispielsweise unter https://myservice.example.com/userinfo, kann eine Anfrage so aussehen:

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

Führen Sie die folgenden Schritte aus, damit der userinfo-Endpunkt Anfragen verarbeiten kann:

1. Extrahieren Sie das Zugriffstoken aus dem Autorisierungs-Header und geben Sie Informationen für den Nutzer zurück, der mit dem Zugriffstoken verknüpft ist.
2. Wenn das Zugriffstoken ungültig ist, gib den Fehler „HTTP 401 Unauthorized“ mit dem Antwortheader WWW-Authenticate zurück. Hier ist ein Beispiel für eine Userinfo-Fehlerantwort:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Wenn während des Verknüpfungsvorgangs der Fehler „401 Nicht autorisiert“ oder eine andere fehlgeschlagene Fehlermeldung zurückgegeben wird, kann der Fehler nicht behoben werden. Das abgerufene Token wird verworfen und der Nutzer muss den Verknüpfungsvorgang noch einmal starten.

3. Wenn das Zugriffstoken gültig ist, geben Sie eine HTTP 200-Antwort mit dem folgenden JSON-Objekt im Text des HTTPS-Objekts zurück. Antwort:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   Wenn der userinfo-Endpunkt eine HTTP 200-Erfolgsantwort zurückgibt, werden das abgerufene Token und die Anforderungen im Google-Konto des Nutzers registriert.

   Userinfo-Endpunktantwort
   sub	Eine eindeutige ID, die den Nutzer in Ihrem System identifiziert.
   email	E-Mail-Adresse des Nutzers
   given_name	Optional:Vorname des Nutzers.
   family_name	Optional:Nachname des Nutzers.
   name	Optional:Vollständiger Name des Nutzers.
   picture	Optional:Profilbild des Nutzers.

Implementierung validieren

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.