Łączenie konta Google z OAuth

Konta są łączone za pomocą standardowych w branży przepływów niejawnych i kodów autoryzacji OAuth 2.0. Twoja usługa musi obsługiwać punkty końcowe autoryzacji i wymiany tokenów zgodne z OAuth 2.0.

W procesie domyślnym Google otwiera Twój punkt końcowy autoryzacji w przeglądarce użytkownika. Po zalogowaniu się zwracasz do Google długotrwały token dostępu. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego z Google.

W przepływie kodu autoryzacji musisz użyć 2 punktów końcowych:

• Punkt końcowy autoryzacji, który wyświetla interfejs logowania użytkownikom, którzy nie są jeszcze zalogowani. Punkt końcowy autoryzacji tworzy też krótkotrwały kod autoryzacji, aby zarejestrować zgodę użytkownika na żądany dostęp.

• Punkt końcowy wymiany tokenów, który odpowiada za 2 rodzaje wymiany:

  1. Wymienia kod autoryzacji na długotrwały token odświeżania i token dostępu o ograniczonym czasie ważności. Wymiana ta następuje, gdy użytkownik przechodzi przez proces łączenia kont.
  2. Wymiana długoterminowego tokena odświeżania na krótkoterminowy token dostępu. Wymiana ta ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ poprzedni wygasł.

Wybierz przepływ OAuth 2.0

Chociaż przepływ domyślnie jest prostszy do wdrożenia, Google zaleca, aby tokeny dostępu wydane w ramach procesu niejawnego nigdy nie wygasały. Dzieje się tak, ponieważ użytkownik musi ponownie połączyć swoje konto po wygaśnięciu tokena w ramach procesu niejawnego. Jeśli ze względów bezpieczeństwa potrzebujesz tokenu z terminem ważności, zdecydowanie zalecamy użycie przepływu kodu autoryzacji.

Wskazówki dotyczące wyglądu

W tej sekcji znajdziesz wymagania dotyczące projektu i zalecenia dotyczące ekranu użytkownika, który hostujesz w ramach procesów łączenia OAuth. Gdy wywoła go aplikacja Google, Twoja platforma wyświetli użytkownikowi stronę logowania do Google i ekran z prośbą o zgodę na połączenie kont. Po wyrażeniu zgody na połączenie kont użytkownik zostaje przekierowany z powrotem do aplikacji Google.

Wymagania

1. Musisz poinformować, że konto użytkownika zostanie połączone z Google, a nie z konkretną usługą Google, taką jak Google Home czy Asystent Google.

Rekomendacje

Zalecamy wykonanie tych czynności:

1. Wyświetlanie Polityki prywatności Google Dodaj link do Polityki prywatności Google na ekranie zgody.

2. Dane do udostępnienia. Używaj jasnego i zwięzłego języka, aby poinformować użytkownika, jakich danych wymaga Google i dlaczego.

3. Wyraźne wezwanie do działania. Na ekranie z prośbą o zgodę umieść wyraźne wezwanie do działania, np. „Zgadzam się i chcę połączyć”. Użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, aby połączyć swoje konta.

4. Możliwość anulowania. zapewnienie użytkownikom możliwości powrotu do poprzedniego ekranu lub anulowania połączenia, jeśli nie chcą go nawiązać;

5. Jednoznaczny proces logowania. Zadbaj o to, aby użytkownicy mieli jasną metodę logowania się na konto Google, np. pola na nazwę użytkownika i hasło lub przycisk Zaloguj się przez Google.

6. Możliwość odłączenia. Udostępnij użytkownikom mechanizm umożliwiający odłączenie konta, np. adres URL do ustawień konta na Twojej platformie. Możesz też dołączyć link do konta Google, na którym użytkownicy mogą zarządzać połączonym kontem.

7. Możliwość zmiany konta użytkownika. Zaproponuj użytkownikom sposób przełączania kont. Jest to szczególnie korzystne, jeśli użytkownicy mają tendencję do tworzenia wielu kont.

   • Jeśli użytkownik musi zamknąć ekran akceptacji, aby przełączyć się na inne konto, prześlij do Google nieodwracalny błąd, aby użytkownik mógł zalogować się na odpowiednie konto za pomocą linkowania OAuth i przepływu utajonego.

8. Dołącz logo. Wyświetlać logo firmy na ekranie zgody. Umieść logo na podstawie wytycznych dotyczących stylu. Jeśli chcesz wyświetlać też logo Google, zapoznaj się z artykułem Logotypy i znaki towarowe.

Tworzenie projektu

Aby utworzyć projekt, w którym będzie można używać łą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 .

Konfigurowanie ekranu akceptacji OAuth

Proces łączenia z kontem Google obejmuje ekran zgody, na którym użytkownicy są informowani, że aplikacja prosi o dostęp do ich danych, jakiego rodzaju dane są wymagane i jakie zasady obowiązują. Przed wygenerowaniem identyfikatora klienta interfejsu API Google musisz skonfigurować ekran zgody OAuth.

1. Otwórz w konsoli interfejsów API Google stronę Ekran zgody OAuth.
2. Jeśli pojawi się taka prośba, wybierz utworzony przed chwilą 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ą aplikacji, którą użytkownicy widzą w innych miejscach. Nazwa aplikacji będzie widoczna na ekranie zgody na połączenie kont.

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

   Adres e-mail zespołu pomocy:użytkownicy mogą się z Tobą kontaktować w sprawie zgody.

   Zakresy interfejsów API Google: zakresy umożliwiają aplikacji dostęp do prywatnych danych użytkownika Google. W przypadku łączenia kont Google wystarcza zakres domyślny (e-mail, profil, openid). Nie musisz dodawać żadnych zakresów związanych z danymi wrażliwymi. Zwykle zaleca się, aby prośby o zakresy były wysyłane stopniowo, w momencie, gdy jest potrzebny dostęp, a nie z wyprzedzeniem. Więcej informacji

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

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

   Link do polityki prywatności aplikacji: wyświetlany na ekranie zgody na łączenie z kontem Google. Musi być hostowana w autoryzowanej domenie.

   Link do warunków korzystania z aplikacji (opcjonalnie): musi być hostowany w autoryzowanej domenie.

   

   Rysunek 1 Ekran zgody na łączenie z kontem Google w fikcyjnym zgłoszeniu Tunery

4. Sprawdź „Stan weryfikacji”. Jeśli Twoja aplikacja wymaga weryfikacji, kliknij przycisk „Prześlij do weryfikacji”. Więcej informacji znajdziesz w artykule Wymagania dotyczące weryfikacji OAuth.

Wdrożenie serwera OAuth

Implementacja procesu kodu autoryzacji na serwerze OAuth 2.0 składa się z tych elementów: dwa punkty końcowe, które Twoja usługa udostępnia przez HTTPS. Pierwszy punkt końcowy to punkt końcowy autoryzacji, który odpowiada za znalezienie lub uzyskanie zgody użytkowników na dostęp do danych. Punkt końcowy autoryzacji przedstawia niezalogowanym użytkownikom i rejestrujący zgodę na o dostęp, którego dotyczy prośba. Drugi punkt końcowy to punkt końcowy wymiany tokenów, jest używany do uzyskiwania zaszyfrowanych ciągów znaków (nazywanych tokenami), które upoważniają użytkownika do dostęp do usługi.

Gdy aplikacja Google musi wywołać jeden z interfejsów API Twojej usługi, te punkty końcowe razem, aby uzyskać od użytkowników uprawnienia do wywoływania tych interfejsów API w ich imieniu.

Sesja przepływu kodu autoryzacji OAuth 2.0 zainicjowana przez Google ma następujący przepływ:

1. Google otworzy punkt końcowy autoryzacji w przeglądarce użytkownika. Jeśli przepływ na urządzeniu z włączonym głosem dla akcji, Google przesyła na telefon.
2. Użytkownik loguje się (jeśli jeszcze nie jest zalogowany) i zezwala Google na uzyskać dostęp do swoich danych za pomocą Twojego interfejsu API, jeśli nie przyznał on jeszcze odpowiednich uprawnień.
3. Usługa tworzy kod autoryzacji i zwraca go do Google. Do zrobienia więc przekieruj przeglądarkę użytkownika z powrotem do Google, podając kod autoryzacji do żądania.
4. Google wysyła kod autoryzacji do punktu końcowego wymiany tokenów, który weryfikuje autentyczność kodu i zwraca token dostępu oraz token odświeżania. Token dostępu to token o ograniczonym czasie ważności, który jest blokowany to dane logowania umożliwiające dostęp do interfejsów API. Token odświeżania jest trwały który Google może przechowywać i wykorzystywać do pozyskiwania nowych tokenów dostępu, gdy tracą ważność.
5. Gdy użytkownik zakończy proces łączenia kont, każdy kolejny żądanie wysłane z Google zawiera token dostępu.

Obsługa żądań autoryzacji

Gdy chcesz połączyć konta, korzystając z kodu autoryzacji OAuth 2.0 Google wysyła użytkownika do punktu końcowego autoryzacji z żądaniem, które zawiera następujące parametry:

Jeśli na przykład punkt końcowy autoryzacji jest dostępny pod adresem https://myservice.example.com/auth, żądanie może wyglądać tak:

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

Aby punkt końcowy autoryzacji mógł obsługiwać żądania logowania, wykonaj te czynności kroki:

1. Sprawdź, czy identyfikator client_id jest zgodny z identyfikatorem klienta przypisanym do Google i czy redirect_uri odpowiada adresowi URL przekierowania dostarczonemu przez Google dla Twojej usługi. Te kontrole są ważne, ponieważ uniemożliwiają przyznawanie dostępu do niezamierzonych lub błędnie skonfigurowanych aplikacji klienckich. Jeśli obsługujesz kilka dla przepływów OAuth 2.0, sprawdź też, czy response_type to code.
2. Sprawdź, czy użytkownik jest zalogowany w Twojej usłudze. Jeśli użytkownik nie jest zalogowany, zalogować się w usłudze lub zarejestrować się w niej.
3. Wygeneruj kod autoryzacji, którego Google będzie używać do uzyskiwania dostępu do Twojego interfejsu API. Kod autoryzacji może być dowolnym ciągiem znaków, ale musi być unikalny reprezentuje użytkownika, klienta, dla którego jest przeznaczony token, i datę ważności kodu. i nie może być odgadywany. Zwykle zajmujesz się autoryzacją które wygasają po około 10 minutach.
4. Sprawdź, czy adres URL określony przez parametr redirect_uri zawiera parametr ten formularz:

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

5. Przekieruj przeglądarkę użytkownika do adresu URL określonego w atrybucie redirect_uri. Dołącz kod autoryzacji właśnie wygenerowano oraz pierwotną, niezmodyfikowaną wartość stanu w przypadku przekierowania. , dołączając parametry code i state. Oto przykład otrzymanego adresu URL:

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

Obsługa żądań wymiany tokenów

Punkt końcowy wymiany tokenów Twojej usługi odpowiada za 2 rodzaje tokenów giełdy:

• Wymiana kodów autoryzacji dla tokenów dostępu i tokenów odświeżania
• Wymiana tokenów odświeżania tokenów dostępu

Żądania wymiany tokenów zawierają te parametry:

Wymiana kodów autoryzacji dla tokenów dostępu i tokenów odświeżania

Gdy użytkownik się zaloguje, a punkt końcowy autoryzacji zwróci krótkotrwały błąd kod autoryzacji do Google, wyślemy żądanie do systemu wymiany tokenów punktu końcowego do wymiany kodu autoryzacji na token dostępu i odświeżenia token.

Dla tych żądań wartość grant_type wynosi authorization_code, a parametr wartość code to wartość wcześniej przypisanego kodu autoryzacji o korzystaniu. Oto przykład żądania wymiany dla tokena dostępu i tokena odświeżania:

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

Aby wymienić kody autoryzacji na token dostępu i token odświeżania, Punkt końcowy wymiany tokenów odpowiada na żądania POST, wykonując to kroki:

1. Sprawdź, czy client_id identyfikuje źródło żądania jako autoryzowane origin oraz że client_secret jest zgodny z oczekiwaną wartością.
2. Sprawdź, czy kod autoryzacji jest prawidłowy i nie stracił ważności Client-ID określony w żądaniu jest zgodny z identyfikatorem klienta powiązanym z kodu autoryzacji.
3. Sprawdź, czy adres URL określony przez parametr redirect_uri jest identyczny do wartości użytej we wstępnym żądaniu autoryzacji.
4. Jeśli nie możesz sprawdzić wszystkich powyższych kryteriów, zwróć żądanie HTTP Błąd 400 Nieprawidłowe żądanie z treścią {"error": "invalid_grant"}.
5. W innym przypadku użyj identyfikatora użytkownika z kodu autoryzacji, aby wygenerować odświeżenie token i token dostępu. Tokenami mogą być dowolne wartości ciągu znaków, ale musi jednoznacznie reprezentować użytkownika i klienta, dla którego jest przeznaczony token. muszą być trudne do odgadnięcia. W przypadku tokenów dostępu zanotuj również zazwyczaj w ciągu godziny od jego wydania. Tokeny odświeżania nie tracą ważności.
6. Zwróć następujący obiekt JSON w treści odpowiedzi HTTPS:

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

Google przechowuje token dostępu oraz token odświeżania użytkownika i rekordów wygaśnięcie tokenu dostępu. Po wygaśnięciu tokena dostępu Google używa token odświeżania, aby uzyskać nowy token dostępu z punktu końcowego wymiany tokenów.

Wymiana tokenów odświeżania tokenów dostępu

Gdy token dostępu wygaśnie, Google wysyła żądanie do systemu wymiany tokenów w punkcie końcowym, aby wymienić token odświeżania na nowy token dostępu.

W przypadku tych żądań wartość grant_type wynosi refresh_token, a wartość z refresh_token to wartość tokena odświeżania, który został przez Ciebie wcześniej przydzielony Google. Poniżej znajdziesz przykład żądania wymiany tokena odświeżania dla tokena dostępu:

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

Aby można było wymienić token odświeżania na token dostępu, punkt końcowy wymiany tokenów odpowiada na żądania POST, wykonując te czynności:

1. Sprawdź, czy client_id identyfikuje źródło żądania jako Google oraz że client_secret jest zgodna z oczekiwaną wartością.
2. Sprawdź, czy token odświeżania jest prawidłowy i czy identyfikator klienta określony w żądanie pasuje do identyfikatora klienta powiązanego z tokenem odświeżania.
3. Jeśli nie możesz sprawdzić wszystkich powyższych kryteriów, zwróć kod HTTP 400 Błąd nieprawidłowego żądania z treścią {"error": "invalid_grant"}.
4. W przeciwnym razie użyj identyfikatora użytkownika z tokena odświeżania, aby wygenerować dostęp token. Tokeny te mogą mieć dowolną wartość w postaci ciągu, ale muszą być unikatowe reprezentują użytkownika i klienta, dla którego jest przeznaczony token. Nie mogą zgadywać. W przypadku tokenów dostępu zanotuj też czas ich ważności. zwykle godzinę po wydaniu tokena.
5. Zwróć następujący obiekt JSON w treści protokołu HTTPS odpowiedź:

   {
   "token_type": "Nośnik",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   

Obsługa żądań informacji o użytkowniku

Punkt końcowy informacji o użytkowniku jest chronionym przez OAuth 2.0 zasobem, który zwraca deklaracje dotyczące połączonego użytkownika. Wdrożenie i hosting punktu końcowego informacji o użytkowniku jest opcjonalne. Wyjątkiem są te przypadki użycia:

• Logowanie się na połączone konto za pomocą Google One Tap
• Bezproblemowa subskrypcja na AndroidTV.

Po pobraniu tokena dostępu z punktu końcowego tokena Google wysyła żądanie do punktu końcowego informacji o użytkowniku, aby pobrać podstawowe informacje profilowe połączonego użytkownika.

Jeśli na przykład punkt końcowy informacji o użytkowniku jest dostępny pod adresem https://myservice.example.com/userinfo, żądanie może wyglądać tak:

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

Aby punkt końcowy informacji o użytkowniku mógł obsługiwać żądania, wykonaj te czynności:

1. Wyodrębnij token dostępu z nagłówka autoryzacji i zwróć informacje o użytkowniku powiązanym z tym tokenem.
2. Jeśli token dostępu jest nieprawidłowy, zwróć błąd HTTP 401 (Brak autoryzacji) i użyj nagłówka odpowiedzi WWW-Authenticate. Poniżej znajduje się przykładowa odpowiedź na pytanie o błąd w informacjach o użytkowniku:

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

   Jeśli podczas procesu łączenia pojawi się błąd 401 (Brak autoryzacji) lub inna nieudana próba połączenia, błędu nie będzie można odzyskać, pobrany token zostanie odrzucony, a użytkownik będzie musiał ponownie zainicjować proces łączenia.

3. Jeśli token dostępu jest prawidłowy, zwróć odpowiedź HTTP 200 z podanym niżej obiektem JSON w treści HTTPS odpowiedź:

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

   Jeśli punkt końcowy informacji o użytkowniku zwraca odpowiedź HTTP 200, pobrany token i żądania są rejestrowane dla konta Google użytkownika.

   odpowiedź dotycząca punktu końcowego informacji o użytkowniku
   sub	Unikalny identyfikator, który identyfikuje użytkownika w Twoim 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	Opcjonalnie: zdjęcie profilowe użytkownika.

Weryfikowanie implementacji

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.