Google-Kontoverknüpfung mit OAuth

Die Konten werden mithilfe von In-App-Käufen über den impliziten und Standard-Autorisierungscode von OAuth 2.0 verknüpft. Der Dienst muss die OAuth 2.0-konformen Endpunkte für die Autorisierung und den Tokenaustausch unterstützen.

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.

Note: Use the following buttons to choose which OAuth 2.0 flow you want to implement. If needed, the content of this guide will reload to match your choice.

Implicit flow Authorization code

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.

Figure 1. Account linking user sign in to Google and consent screens.

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.

Figure 2. Design guidelines for user sign in to Google and consent screens.

Create the project

Note: You can reuse an existing project and do not need to create a new project primarily for account linking.

To create your project to use account linking:

1. Go to the Google API Console.
2. Klicken Sie auf Projekt erstellen .
3. Geben Sie einen Namen ein oder akzeptieren Sie den generierten Vorschlag.
4. Bestätigen oder bearbeiten Sie alle verbleibenden Felder.
5. Klicken Sie auf Erstellen .

So zeigen Sie Ihre Projekt-ID an:

1. Go to the Google API Console.
2. Finden Sie Ihr Projekt in der Tabelle auf der Zielseite. Die Projekt - ID wird in der ID - Spalte.

Configure your OAuth Consent Screen

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

Ein OAuth 2.0 - Server - Implementierung des Autorisierungscodes Stromes besteht aus zwei Endpunkten, die Ihr Dienst von HTTPS zur Verfügung stellt. Der erste Endpunkt ist der Autorisierungsendpunkt, der dafür verantwortlich ist, die Zustimmung von Benutzern für den Datenzugriff zu finden oder einzuholen. Der Autorisierungsendpunkt stellt Ihren Benutzern, die noch nicht angemeldet sind, eine Benutzeroberfläche zur Anmeldung bereit und zeichnet die Zustimmung zum angeforderten Zugriff auf. Der zweite Endpunkt ist der Token-Austausch-Endpunkt, der verwendet wird, um verschlüsselte Zeichenfolgen, sogenannte Tokens, abzurufen, die einem Benutzer den Zugriff auf Ihren Dienst autorisieren.

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

Eine von Google initiierte OAuth 2.0-Autorisierungscodeflusssitzung hat den folgenden Ablauf:

1. Google öffnet Ihren Autorisierungsendpunkt im Browser des Nutzers. Wenn der Flow auf einem Nur-Sprachgerät für eine Aktion gestartet wurde, überträgt Google die Ausführung an ein Telefon.
2. Der Nutzer meldet sich an, falls er noch nicht angemeldet ist, und erteilt Google die Berechtigung, mit Ihrer API auf seine Daten zuzugreifen, sofern er noch keine Berechtigung erteilt hat.
3. Ihr Dienst erstellt einen Berechtigungscode und gibt sie an Google. Leiten Sie dazu den Browser des Nutzers mit dem an die Anfrage angehängten Autorisierungscode zurück zu Google.
4. Google sendet den Autorisierungscode zu Ihrem Token Austausch Endpunkt, die die Echtheit des Codes überprüft und gibt einen Zugriffstoken und ein Aktualisierungs - Token. Das Zugriffstoken ist ein kurzlebiges Token, das Ihr Dienst als Anmeldeinformationen für den Zugriff auf APIs akzeptiert. Das Aktualisierungstoken ist ein langlebiges Token, das Google speichern und verwenden kann, um neue Zugriffstokens zu erwerben, wenn diese ablaufen.
5. Nachdem der Nutzer die Kontoverknüpfung abgeschlossen hat, enthält jede nachfolgende von Google gesendete Anfrage ein Zugriffstoken.

Autorisierungsanfragen bearbeiten

Wenn Sie eine Kontoverknüpfung mithilfe des OAuth 2.0-Autorisierungscodeflusses durchführen müssen, sendet Google den Nutzer mit einer Anfrage, die die folgenden Parameter enthält, an Ihren Autorisierungsendpunkt:

Autorisierungsendpunktparameter
client_id	Die Client-ID, die Sie Google zugewiesen haben.
redirect_uri	Die URL, an die Sie die Antwort auf diese Anfrage senden.
state	Ein Buchhaltungswert, der unverändert im Weiterleitungs-URI an Google zurückgegeben wird.
scope	Optional: Ein Leerzeichen getrennte Satz von Rahmen - Strings, die die Daten angeben Google die Berechtigung für anfordert.
response_type	Der Typ des Werts, der in der Antwort zurückgegeben werden soll. Für den OAuth 2.0 Autorisierungscode Fluss ist der Antworttyp immer code .
user_locale	Die Google - Konto Spracheinstellung in RFC5646 - Format verwendet , um Ihre Inhalte in dem bevorzugten Sprache des Benutzers zu lokalisieren.

Zum Beispiel, wenn Ihre Berechtigung Endpunkt an verfügbar ist https://myservice.example.com/auth könnte eine Anfrage wie folgt aussehen:

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

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

1. Stellen Sie sicher , dass der client_id die Client - ID entspricht , die Sie bei Google zugewiesen, und dass der redirect_uri entspricht die Umleitungs - URL zur Verfügung gestellt von Google für Ihren Dienst. Diese Prüfungen sind wichtig, um zu verhindern, dass unbeabsichtigten oder falsch konfigurierten Client-Apps Zugriff gewährt wird. Wenn Sie mehr OAuth 2.0 Ströme unterstützen, bestätigt auch , dass die response_type ist code .
2. Überprüfen Sie, ob der Benutzer bei Ihrem Dienst angemeldet ist. Wenn der Benutzer nicht angemeldet ist, führen Sie den Anmelde- oder Anmeldevorgang Ihres Dienstes durch.
3. Generieren Sie einen Autorisierungscode, den Google für den Zugriff auf Ihre API verwenden kann. Der Autorisierungscode kann ein beliebiger Zeichenfolgenwert sein, muss jedoch den Benutzer, den Client, für den das Token bestimmt ist, sowie die Ablaufzeit des Codes eindeutig darstellen und darf nicht erraten werden. Normalerweise geben Sie Autorisierungscodes aus, die nach etwa 10 Minuten ablaufen.
4. Bestätigen , dass die URL von dem angegebenen redirect_uri Parameter hat die folgende Form:

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

5. Leiten Sie den Browser des Benutzers an die URL von dem angegebenen redirect_uri Parameter. Fügen Sie den Autorisierungscode Sie gerade erzeugt und die ursprünglichen, unveränderten Zustand Wert , wenn Sie durch Anhängen der Redirect - code und state Das Folgende ist ein Beispiel der resultierenden URL:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Bearbeitung von Token-Austausch-Anfragen

Der Token-Austausch-Endpunkt Ihres Dienstes ist für zwei Arten von Token-Austausch verantwortlich:

• Autorisierungscodes für Zugriffstoken und Aktualisierungstoken austauschen
• Aktualisierungstoken gegen Zugriffstoken austauschen

Token-Austausch-Anfragen umfassen die folgenden Parameter:

Endpunktparameter für Tokenaustausch
client_id	Eine Zeichenfolge, die den Ursprung der Anfrage als Google identifiziert. Diese Zeichenfolge muss in Ihrem System als eindeutige Kennung von Google registriert sein.
client_secret	Eine geheime Zeichenfolge, die Sie bei Google für Ihren Dienst registriert haben.
grant_type	Der Tokentyp, der ausgetauscht wird. Es ist entweder authorization_code oder refresh_token .
code	Wenn grant_type=authorization_code dieser Parameter ist der Code von Google entweder Anmelde-empfangen oder Token Austausch Endpunkt.
redirect_uri	Wenn grant_type=authorization_code ist dieser Parameter die URL in der ursprünglichen Genehmigungsanfrage verwendet.
refresh_token	Wenn grant_type=refresh_token Dieser Parameter ist die Aktualisierungs - Token Google von Ihrem Token Austausch Endpunkt empfangen.

Autorisierungscodes für Zugriffstoken und Aktualisierungstoken austauschen

Nachdem sich der Nutzer angemeldet hat und Ihr Autorisierungsendpunkt einen kurzlebigen Autorisierungscode an Google zurückgibt, sendet Google eine Anfrage an Ihren Token-Austausch-Endpunkt, um den Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken auszutauschen.

Für diese Anforderungen ist der Wert von grant_type ist authorization_code , und der Wert des code ist der Wert des Autorisierungscodes Sie zuvor auf Google gewährt. Im Folgenden finden Sie ein Beispiel für eine Anforderung zum Austausch eines Autorisierungscodes gegen ein Zugriffstoken und ein Aktualisierungstoken:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Um Berechtigungscodes für einen Zugriff Austausch - Token und ein Aktualisierungs - Token, Token Austausch Endpunkt reagiert auf POST - Anfragen durch die folgenden Schritte ausführen:

1. Stellen Sie sicher , dass die client_id identifiziert die Anforderung Ursprung als berechtigter Ursprung, und dass die client_secret den erwarteten Wert übereinstimmt.
2. Stellen Sie sicher, dass der Autorisierungscode gültig und nicht abgelaufen ist und dass die in der Anforderung angegebene Client-ID mit der Client-ID übereinstimmt, die dem Autorisierungscode zugeordnet ist.
3. Bestätigen , dass die URL von dem angegebenen redirect_uri Parameter ist identisch mit dem Wert in der anfänglichen Berechtigungsanforderung verwendet.
4. Wenn Sie nicht alle der oben genannten Kriterien überprüfen können, geben eine HTTP 400 Bad Request Fehler mit {"error": "invalid_grant"} wie der Körper.
5. Verwenden Sie andernfalls die Benutzer-ID aus dem Autorisierungscode, um ein Aktualisierungstoken und ein Zugriffstoken zu generieren. Bei diesen Token kann es sich um einen beliebigen Zeichenfolgenwert handeln, sie müssen jedoch den Benutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und dürfen nicht erraten werden. Notieren Sie bei Zugriffstoken auch die Ablaufzeit des Tokens, die normalerweise eine Stunde nach der Ausgabe des Tokens liegt. Aktualisierungstoken laufen nicht ab.
6. Bringen Sie das folgende JSON - Objekt in dem Körper der HTTPS - Antwort:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

Google speichert das Zugriffstoken und das Aktualisierungstoken für den Nutzer und protokolliert den Ablauf des Zugriffstokens. Wenn das Zugriffstoken abläuft, verwendet Google das Aktualisierungstoken, um ein neues Zugriffstoken von Ihrem Token-Austausch-Endpunkt abzurufen.

Aktualisierungstoken gegen Zugriffstoken austauschen

Wenn ein Zugriffstoken abläuft, sendet Google eine Anfrage an Ihren Token-Austausch-Endpunkt, um ein Aktualisierungstoken gegen ein neues Zugriffstoken auszutauschen.

Für diese Anforderungen ist der Wert von grant_type wird refresh_token , und der Wert von refresh_token ist der Wert des Aktualisierungs - Token Sie zuvor auf Google gewährt. Im Folgenden finden Sie ein Beispiel für eine Anforderung zum Austausch eines Aktualisierungstokens gegen ein Zugriffstoken:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Um ein Refresh - Austausch für ein Zugriffstoken Token, Token Austausch Endpunkt reagiert auf POST - Anfragen durch die folgenden Schritte ausführen:

1. Stellen Sie sicher , dass die client_id identifiziert die Anforderung Herkunft wie Google, und dass die client_secret den erwarteten Wert übereinstimmt.
2. Stellen Sie sicher, dass das Aktualisierungstoken gültig ist und dass die in der Anforderung angegebene Client-ID mit der Client-ID übereinstimmt, die dem Aktualisierungstoken zugeordnet ist.
3. Wenn Sie nicht alle der oben genannten Kriterien überprüfen können, geben eine HTTP 400 Bad Request Fehler mit {"error": "invalid_grant"} wie der Körper.
4. Verwenden Sie andernfalls die Benutzer-ID aus dem Aktualisierungstoken, um ein Zugriffstoken zu generieren. Bei diesen Token kann es sich um einen beliebigen Zeichenfolgenwert handeln, sie müssen jedoch den Benutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und dürfen nicht erraten werden. Notieren Sie bei Zugriffstoken auch die Ablaufzeit des Tokens, normalerweise eine Stunde nach der Ausgabe des Tokens.
5. Geben Sie das folgende JSON-Objekt im Hauptteil der HTTPS-Antwort zurück:

   {
   "token_type": "Bearer",
   "access_token": " ACCESS_TOKEN ",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Hinweis: Sie können optional einen neuen Rück refresh_token in Ihrer Antwort. Weitere Informationen darüber , wann eine neue Rückkehr refresh_token bevorzugt, siehe Arbeiten mit Token .

Benutzerinfo-Anfragen bearbeiten

Der Userinfo - Endpunkt ist eine OAuth 2.0 geschützte Ressource , die Rückkehr Anspruch über den verknüpften Benutzer. Das Implementieren und Hosten des userinfo-Endpunkts ist optional, mit Ausnahme der folgenden Anwendungsfälle:

• Linked Konto Sign-In mit Google One Tap.
• Reibungsfreihe Abonnement auf Android TV.

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

Userinfo-Endpunkt-Anforderungsheader
Authorization header	Das Zugriffstoken vom Typ Bearer.

Zum Beispiel, wenn Ihr Userinfo Endpunkt bei verfügbar ist https://myservice.example.com/userinfo könnte eine Anfrage wie folgt aussehen:

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

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

1. Extrahieren Sie das Zugriffstoken aus dem Authorization-Header und geben Sie Informationen für den Benutzer zurück, der dem Zugriffstoken zugeordnet ist.
2. Wenn der Zugriffstoken ungültig ist, der HTTP 401 Unauthorized Fehler bei der Verwendung von WWW-Authenticate Response - Header. Im Folgenden finden Sie ein Beispiel für eine userinfo Fehlerreaktion:

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

   Wenn ein 401 Unauthorized oder jede andere erfolglose Fehlerreaktion während des Verbindungsvorgangs zurückgeführt wird, wird der Fehler nicht mehr erzielbar ist, wird die abgerufene Token verworfen werden und der Benutzer wird um den Verknüpfungsvorgang erneut zu starten.

3. Wenn die Zugriffstoken gültig ist, Rückkehr und HTTP 200 - Antwort mit dem folgende JSON - Objekt in dem Körper der HTTPS - Antwort:

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

   Wenn Ihr Userinfo Endpunkt kehrt eine HTTP 200 Erfolgsantwort, werden die abgerufenen Token und Ansprüche registriert gegen den Benutzer Google Konto.

   Userinfo-Endpunktantwort
   sub	Eine eindeutige ID, die den Benutzer in Ihrem System identifiziert.
   email	E-Mail-Adresse des Benutzers.
   given_name	Optional: Vorname des Benutzers.
   family_name	Optional: Nachname des Benutzers.
   name	Optional: Vollständiger Name des Benutzers.
   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 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.