Łączenie konta Google z protokołem OAuth

Konta są łączone przy użyciu standardowych przepływów protokołu OAuth 2.0 i kodu autoryzacji. Twoja usługa musi obsługiwać punkty końcowe autoryzacji zgodnej z protokołem OAuth 2.0 i punkty końcowe tokena.

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.

Tworzenie projektu

Uwaga: możesz wykorzystać istniejący projekt. Nie musisz tworzyć nowego projektu, którego głównym celem jest łączenie kont.

Aby utworzyć projekt z funkcją łączenia kont:

1. Go to the Google API Console.
2. Kliknij Utwórz projekt .
3. Wpisz nazwę lub zaakceptuj wygenerowaną sugestię.
4. Potwierdź lub edytuj pozostałe pola.
5. Kliknij Utwórz .

Aby wyświetlić identyfikator projektu:

1. Go to the Google API Console.
2. Znajdź swój projekt w tabeli na landing page. Identyfikator projektu pojawia się w kolumnie ID .

Skonfiguruj ekran zgody OAuth

Proces łączenia kont Google obejmuje ekran zgody, na którym aplikacja prosi o dostęp do ich danych, rodzaj danych, o które proszą, oraz obowiązujące warunki. Przed wygenerowaniem identyfikatora klienta interfejsu API Google musisz skonfigurować ekran zgody OAuth.

1. Otwórz stronę Ekran zgody OAuth w konsoli interfejsów API Google.
2. Jeśli pojawi się taka prośba, wybierz właśnie utworzony projekt.

3. Na stronie „Ekran zgody OAuth” wypełnij formularz i kliknij przycisk „Zapisz”.

   Nazwa aplikacji: nazwa aplikacji, która prosi o zgodę. Nazwa powinna dokładnie odzwierciedlać Twoją aplikację i być zgodna z nazwą, którą użytkownicy widzą w innych miejscach. Nazwa aplikacji będzie widoczna na ekranie zgody na łączenie kont.

   Logo aplikacji: obraz na ekranie zgody, który pomoże użytkownikom rozpoznać Twoją aplikację. Logo jest widoczne na ekranie zgody łączenia kont oraz w ustawieniach konta.

   Adres e-mail zespołu pomocy: umożliwia użytkownikom kontaktowanie się z Tobą w razie pytań o udzielenie zgody.

   Zakresy dla interfejsów API Google: zakresy umożliwiają aplikacji dostęp do prywatnych danych Google użytkownika. W przypadku łączenia kont Google wystarczy ustawić domyślny zakres (adres e-mail, profil, identyfikator openid) i nie musisz dodawać żadnych poufnych zakresów. Ogólnie sprawdzoną metodą jest stopniowe zgłaszanie żądań zakresów w momencie, gdy jest wymagany dostęp, a nie z góry. Więcej informacji

   Autoryzowane domeny: aby chronić Ciebie i Twoich użytkowników, Google zezwala na korzystanie z autoryzowanych domen tylko aplikacjom, które uwierzytelniają się za pomocą protokołu OAuth. Linki Twoich aplikacji muszą być hostowane w autoryzowanych domenach. Więcej informacji

   Link do strony głównej aplikacji: strona główna Twojej aplikacji. Musi być hostowany w autoryzowanej domenie.

   Link do polityki prywatności aplikacji: wyświetlany na ekranie zgody dotyczącej łączenia konta Google. Musi być hostowany w autoryzowanej domenie.

   Link do Warunków korzystania z usługi (opcjonalny): musi być hostowany w autoryzowanej domenie.

   

   Rysunek 1. Ekran ze zgodą na łączenie konta Google dla fikcyjnej aplikacji, Tunery

4. Sprawdź „Stan weryfikacji”, jeśli zgłoszenie wymaga weryfikacji, a następnie kliknij przycisk „Prześlij do weryfikacji”, aby przesłać zgłoszenie do weryfikacji. Szczegółowe informacje znajdziesz w artykule Wymagania dotyczące weryfikacji OAuth.

Implementowanie serwera OAuth

Aby wspierać przepływ niejawny OAuth 2.0, usługa sprawia, że końcowy autoryzacji dostępne przez HTTPS. Ten punkt końcowy jest odpowiedzialny za uwierzytelnianie i uzyskiwanie zgody użytkowników na dostęp do danych. Punkt końcowy autoryzacji przedstawia interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani, i rejestruje zgodę na żądany dostęp.

Gdy aplikacja Google musi wywołać jeden z autoryzowanych interfejsów API Twojej usługi, Google używa tego punktu końcowego, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w ich imieniu.

Typowa niejawna sesja przepływu OAuth 2.0 zainicjowana przez Google ma następujący przepływ:

1. Google otwiera Twój punkt końcowy autoryzacji w przeglądarce użytkownika. Użytkownik loguje się, jeśli jeszcze się nie zalogował, i udziela Google pozwolenia na dostęp do swoich danych za pomocą Twojego interfejsu API, jeśli jeszcze nie udzielił pozwolenia.
2. Usługa tworzy token dostępu i zwraca go do Google. Aby to zrobić, przekieruj przeglądarkę użytkownika z powrotem do Google za pomocą tokena dostępu dołączonego do żądania.
3. Google wywołuje interfejsy API Twojej usługi i dołącza token dostępu do każdego żądania. Twoja usługa sprawdza, czy token dostępu udziela Google autoryzacji na dostęp do interfejsu API, a następnie wykonuje wywołanie interfejsu API.

Obsługuj żądania autoryzacji

Gdy aplikacja Google musi wykonać połączenie kont za pomocą niejawnego przepływu OAuth 2.0, Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem zawierającym następujące parametry:

Parametry punktu końcowego autoryzacji
client_id	Identyfikator klienta przypisany do Google.
redirect_uri	Adres URL, na który wysyłasz odpowiedź na to żądanie.
state	Wartość księgowa przekazywana z powrotem do Google bez zmian w identyfikatorze URI przekierowania.
response_type	Typ wartości do zwrócenia w odpowiedzi. Dla przepływu niejawny OAuth 2.0, typ odpowiedzi jest zawsze token .
user_locale	Ustawienie języka konto Google w RFC5646 format używany do zlokalizować swoją zawartość w preferowanym języku użytkownika.

Na przykład, jeśli końcowy autoryzacji jest dostępny na https://myservice.example.com/auth , wniosek może wyglądać następująco:

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

Aby punkt końcowy autoryzacji obsługiwał żądania logowania, wykonaj następujące czynności:

1. Zweryfikować client_id i redirect_uri wartości, aby zapobiec udostępnianiu niezamierzonych lub źle skonfigurowanych aplikacji klienckich:

   • Potwierdź, że client_id dopasowuje identyfikator klienta przypisany do Google.
   • Potwierdź, że adres URL podany przez redirect_uri parametr ma następującą postać:

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

2. Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, dokończ proces logowania lub rejestracji w usłudze.

3. Wygeneruj token dostępu, którego Google użyje do uzyskania dostępu do Twojego interfejsu API. Token dostępu może być dowolną wartością ciągu, ale musi jednoznacznie reprezentować użytkownika i klienta, dla którego jest przeznaczony, i nie może być możliwy do odgadnięcia.

4. Wyślij odpowiedź HTTP, który przekierowuje przeglądarkę użytkownika do adresu URL określonego przez redirect_uri parametru. Uwzględnij wszystkie następujące parametry we fragmencie adresu URL:

   • access_token : Dostęp żeton ciebie właśnie generowane
   • token_type : Ciąg bearer
   • state : Niemodyfikowany wartość stanu z pierwotnego wniosku

   Poniżej znajduje się przykład powstałego URL:

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

OAuth 2.0 przekierowanie obsługi Google otrzymuje token dostępu i potwierdza, że state wartość nie uległa zmianie. Gdy Google uzyska token dostępu do Twojej usługi, dołączy go do kolejnych wywołań interfejsów API Twojej usługi.

Obsługuj prośby o informacje o użytkowniku

Końcowy userinfo jest 2,0 OAuth chronione zasoby, zwrot należności o połączonego użytkownika. Implementacja i hostowanie punktu końcowego informacji o użytkowniku jest opcjonalne, z wyjątkiem następujących przypadków użycia:

• Związany konto Logowanie z Google One Tap.
• Tarcia subskrypcja na AndroidTV.

Po pomyślnym pobraniu tokena dostępu z punktu końcowego tokena Google wysyła do punktu końcowego informacji o użytkowniku żądanie pobrania podstawowych informacji o profilu powiązanego użytkownika.

nagłówki żądania punktu końcowego informacji o użytkowniku
Authorization header	Token dostępu typu Bearer.

Na przykład, jeśli userinfo końcowy jest dostępny w https://myservice.example.com/userinfo , wniosek może wyglądać następująco:

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

Aby punkt końcowy informacji o użytkowniku obsługiwał żądania, wykonaj następujące czynności:

1. Wyodrębnij token dostępu z nagłówka Authorization i zwróć informacje dla użytkownika powiązanego z tokenem dostępu.
2. Jeśli token dostępu jest nieważny, zwróci błąd HTTP 401 z nieautoryzowanemu użyciu WWW-Authenticate nagłówku odpowiedzi. Poniżej znajduje się przykład odpowiedzi błędu userinfo:

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

   Jeśli 401 Nieuprawnione lub inny nieudana odpowiedź zwracany jest błąd podczas procesu łączącego, błąd będzie nienaprawialny, pobranego żeton zostaną odrzucone, a użytkownik będzie miał aby ponownie zainicjować proces łączenia.

3. Jeśli token dostępu jest ważne, zwrot i HTTP 200 odpowiedzi z poniższej obiekt JSON w organizmie odpowiedzi https:

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

   jeśli Twój userinfo końcowych zwraca HTTP 200 sukcesem odpowiedzi, pobierane żeton i roszczenia są zarejestrowane na użytkownika Google konto.

   odpowiedź punktu końcowego informacji o użytkowniku
   sub	Unikalny identyfikator, który identyfikuje użytkownika w systemie.
   email	Adres e-mail użytkownika.
   given_name	Opcjonalnie: Imię użytkownika.
   family_name	Opcjonalnie: nazwisko użytkownika.
   name	Opcjonalnie: Pełna nazwa użytkownika.
   picture	Obraz Profil użytkownika: opcjonalny.

Sprawdzanie poprawności implementacji

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.