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

Um den OAuth 2.0 impliziten Fluss zu unterstützen, Ihr Dienst macht einen Berechtigungs Endpunkt verfügbar von HTTPS. Dieser Endpunkt ist für die Authentifizierung und das Einholen der Zustimmung der Benutzer für den Datenzugriff verantwortlich. Der Autorisierungsendpunkt stellt Ihren Benutzern, die noch nicht angemeldet sind, eine Benutzeroberfläche zur Anmeldung bereit und zeichnet die Zustimmung zum angeforderten Zugriff auf.

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

Eine typische von Google initiierte implizite OAuth 2.0-Flow-Sitzung hat den folgenden Ablauf:

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, sofern er noch keine Berechtigung erteilt hat.
2. Ihr Dienst erstellt ein Zugriffstoken und gibt sie an Google. Leiten Sie dazu den Browser des Nutzers mit dem an die Anfrage angehängten Zugriffstoken zurück zu Google.
3. Google ruft die APIs Ihres Dienstes auf und hängt das Zugriffstoken an jede Anfrage an. Ihr Dienst überprü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 bearbeiten

Wenn eine Google-Anwendung eine Kontoverknüpfung über einen impliziten OAuth 2.0-Flow durchführen muss, 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.
response_type	Der Typ des Werts, der in der Antwort zurückgegeben werden soll. Für die OAuth 2.0 implizite Strömung wird der Antworttyp immer token .
user_locale	Die Google - Konto Spracheinstellung in RFC5646 - Format verwendet , um Ihre Inhalte in dem vom Benutzer bevorzugten Sprache 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&response_type=token&user_locale=LOCALE

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

1. Überprüfen Sie die client_id und redirect_uri Werte Zugriff zu verhindern Gewährung unbeabsichtigte oder falsch konfigurierte Client - Anwendungen:

   • Bestätigen Sie, dass der client_id entspricht die Client - ID an Google zugewiesen.
   • 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
     

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 ein Zugriffstoken, mit dem Google auf Ihre API zugreifen kann. Das Zugriffstoken kann ein beliebiger Zeichenfolgenwert sein, muss jedoch den Benutzer und den Client, für den das Token bestimmt ist, eindeutig darstellen und darf nicht erraten werden.

4. Senden Sie eine HTTP - Antwort , die den Browser des Benutzers an die URL von der angegebenen Umleitungen redirect_uri Parameter. Fügen Sie alle der folgenden Parameter in das URL-Fragment ein:

   • access_token : Das Zugriffstoken Sie gerade erzeugt
   • token_type : Der String bearer
   • state : Der unmodifizierte Zustandswert aus der ursprünglichen Anforderung

   Das Folgende ist ein Beispiel der resultierenden URL:

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

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

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

Sie können Ihre Implementierung mithilfe der Validierung OAuth 2.0 Spielplatz - Tool.

Führen Sie im Tool die folgenden Schritte aus:

1. Klicken Sie auf das OAuth 2.0 - Konfigurationsfenster zu öffnen.
2. Im OAuth Strömungsfeld, wählen Sie Client-Seite.
3. Im OAuth Endpunkte Feld wählen Sie Benutzerdefiniert.
4. Geben Sie Ihren OAuth 2.0-Endpunkt und die Client-ID, die Sie Google zugewiesen haben, in die entsprechenden Felder ein.
5. Im Schritt 1 Wählen Sie im Abschnitt keine Google Bereiche. Lassen Sie stattdessen dieses Feld leer oder geben Sie einen für Ihren Server gültigen Bereich ein (oder eine beliebige Zeichenfolge, wenn Sie keine OAuth-Bereiche verwenden). Wenn Sie fertig sind, klicken Sie auf Autorisieren APIs.
6. In der Stufe 2 und Stufe 3 Abschnitte, geht durch die OAuth 2.0 fließen und sicherzustellen , dass jeder Schritt wie vorgesehen funktioniert.

Sie können Ihre Implementierung mithilfe der Validierung Google - Konto verknüpfen Demo - Tool.

Führen Sie im Tool die folgenden Schritte aus:

1. Klicken Sie auf die Sign-in mit Google - Taste.
2. Wählen Sie das Konto aus, das Sie verknüpfen möchten.
3. Geben Sie die Service-ID ein.
4. Geben Sie optional einen oder mehrere Bereiche ein, für die Sie Zugriff anfordern.
5. Klicken Sie auf Start Demo.
6. Wenn Sie dazu aufgefordert werden, bestätigen Sie, dass Sie der Verknüpfungsanfrage zustimmen und diese ablehnen können.
7. Bestätigen Sie, dass Sie zu Ihrer Plattform weitergeleitet werden.