Łą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.

W ramach procesu domyślnego Google otwiera punkt końcowy autoryzacji w przeglądarce użytkownika. Po udanym logowaniu zwracasz do Google token dostępu o dłuższej długości. Ten token dostępu jest teraz dołączany do każdego żądania wysyłanego przez Google.

W procesie kodu autoryzacji potrzebujesz 2 punktów końcowych:

  • Punkt końcowy autoryzacji, który wyświetla interfejs logowania użytkownikom, którzy jeszcze nie są zalogowani. Punkt końcowy autoryzacji tworzy też krótki kod autoryzacji do rejestrowania użytkowników i uzyskiwania zgody na żądany dostęp.

  • Punkt końcowy token Exchange, który jest odpowiedzialny za 2 typy giełd:

    1. Wymiana kodu autoryzacji dla długotrwałego tokenu odświeżania i krótkoterminowego tokena dostępu. Wymiana następuje, gdy użytkownik przeprowadzi proces łączenia kont.
    2. Wymiana tokenu odświeżania o długim czasie ważności na token dostępu o krótkim czasie ważności. Ta wymiana ma miejsce, gdy Google potrzebuje nowego tokena dostępu, ponieważ wygasł.

Wybierz przepływ OAuth 2.0

Chociaż procedura domyślna jest prostsza, zalecamy, by tokeny dostępu domyślnie ustały. Dzieje się tak, ponieważ użytkownik jest zmuszony ponownie połączyć swoje konto po wygaśnięciu tokena w wynikowy sposób. Jeśli ze względów bezpieczeństwa zależy Ci na wygaśnięciu tokena, zdecydowanie zalecamy użycie procesu kodu autoryzacji.

Wskazówki dotyczące wyglądu

W tej sekcji opisano wymagania projektowe i zalecenia dotyczące ekranu użytkownika hostowanego przez proces łączenia OAuth. Po wywołaniu jej przez aplikację Google na Twojej platformie wyświetla się ekran logowania na stronie Google, a użytkownik wyraża zgodę na połączenie konta. Gdy użytkownik wyrazi zgodę na połączenie kont, zostanie przekierowany z powrotem do aplikacji Google.

Ten wykres przedstawia czynności, jakie musi wykonać użytkownik, aby połączyć swoje konto Google z Twoim systemem uwierzytelniania. Pierwszy zrzut ekranu przedstawia linki inicjowane przez użytkownika na Twojej platformie. Drugi obraz przedstawia logowanie użytkownika w Google, a trzeci – zgodę użytkownika i jego potwierdzenie na potrzeby połączenia konta Google z aplikacją. Ostatni zrzut ekranu przedstawia połączone konto użytkownika w aplikacji Google.
Rysunek 1. Łączenie kont loguje się w Google i na ekranach zgody.

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.

Zalecenia

Zalecamy wykonanie tych czynności:

  1. Wyświetl Politykę prywatności Google Podaj na ekranie zgody link do Polityki prywatności Google.

  2. Dane do udostępnienia. Stosuj jasne i zwięzłe sformułowania, których użytkownik potrzebuje, i wyjaśnij, jakich danych Google potrzebuje i dlaczego.

  3. Stosuj jednoznaczne wezwania do działania. Jasno umieść wezwanie do działania na ekranie zgody, np. „Zgadzam się i łączę”. Użytkownicy muszą wiedzieć, jakie dane muszą udostępnić Google, by połączyć swoje konta.

  4. Możliwość anulowania. Zapewnij użytkownikom możliwość powrotu lub anulowania subskrypcji, jeśli nie chcą tworzyć linków.

  5. Przejrzysty proces logowania. Upewnij się, że użytkownicy mają wyraźną metodę logowania się na swoje konto Google, np. pola do wpisania nazwy użytkownika i hasła lub logowania się przez Google.

  6. Możliwość odłączenia. Udostępnij użytkownikom mechanizm odłączenia kont, na przykład URL do ustawień ich konta na Twojej platformie. Możesz też podać link do konta Google, na którym użytkownicy mogą zarządzać swoim połączonym kontem.

  7. Możliwość zmiany konta użytkownika. Zasugeruj użytkownikom zmianę swojego konta. Jest to szczególnie przydatne, gdy użytkownicy mają zwykle kilka kont.

    • Jeśli użytkownik musi zamknąć ekran zgody, aby przełączyć konta, wyślij do Google opis możliwego do odzyskania błędu, aby mógł zalogować się na wybrane konto przy użyciu łączenia OAuth i procesu domyślnego.

  8. Logo. Wyświetlaj logo swojej firmy na ekranie zgody. Umieść swoje logo zgodnie ze wskazówkami dotyczącymi stylu. Jeśli chcesz też wyświetlać logo Google, zobacz Logo i znaki towarowe.

Tworzenie projektu

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 .

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

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:

Parametry punktu końcowego autoryzacji
client_id Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri Adres URL, na który została wysłana odpowiedź na to żądanie.
state wartości księgowej, która jest przesyłana do Google bez zmian w identyfikator URI przekierowania.
scope Opcjonalnie: rozdzielany spacjami zestaw ciągów tekstowych zakresu, które określają danych, w przypadku których Google żąda autoryzacji.
response_type Typ wartości do zwrócenia w odpowiedzi. Protokół OAuth 2.0 przepływu kodu autoryzacji, typ odpowiedzi to zawsze code.
user_locale Ustawienia języka konta Google w RFC5646 używany do lokalizowania treści na język preferowany przez użytkownika.

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:

Parametry punktu końcowego wymiany tokenów
client_id Ciąg tekstowy identyfikujący źródło żądania jako Google. Ten ciąg musi: być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret Ciąg znaków tajny zarejestrowany w Google na potrzeby usługi.
grant_type Typ wymienianego tokena. Jest albo authorization_code lub refresh_token.
code Jeśli parametr ma wartość grant_type=authorization_code, tym parametrem jest kod otrzymany przez Google z Twojego loginu lub wymiany tokenów punktu końcowego.
redirect_uri Jeśli parametr ma wartość grant_type=authorization_code, tym parametrem jest Adres URL użyty w wstępnym żądaniu autoryzacji.
refresh_token Jeśli parametr ma wartość grant_type=refresh_token, tym parametrem jest odśwież token odebrany przez Google z punktu końcowego wymiany tokenów.
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:

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.

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

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.

Sprawdzanie poprawności implementacji

Można sprawdzić poprawność implementacji za pomocą OAuth 2.0 Playground narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij konfiguracji , aby otworzyć okno konfiguracji OAuth 2.0.
  2. W dziedzinie przepływu OAuth, wybierz Client-side.
  3. W polu OAuth Endpoints wybierz Niestandardowy.
  4. W odpowiednich polach określ punkt końcowy OAuth 2.0 i identyfikator klienta przypisany do Google.
  5. W sekcji Krok 1, nie zaznaczaj żadnych zakresów Google. Zamiast tego pozostaw to pole puste lub wpisz zakres poprawny dla Twojego serwera (lub dowolny ciąg, jeśli nie używasz zakresów OAuth). Kiedy skończysz, kliknij autoryzacji API.
  6. W etapie 2 i etapem 3 części, przechodzą przepływu OAuth 2.0 i upewnić się, że każdy etap działa zgodnie z zamierzeniem.

Można sprawdzić poprawność implementacji za pomocą konta Google Linking Demo narzędzia.

W narzędziu wykonaj następujące czynności:

  1. Kliknij Sign-in z przycisku Google.
  2. Wybierz konto, które chcesz połączyć.
  3. Wprowadź identyfikator usługi.
  4. Opcjonalnie wprowadź co najmniej jeden zakres, do którego poprosisz o dostęp.
  5. Kliknij Start Demo.
  6. Po wyświetleniu monitu potwierdź, że możesz wyrazić zgodę i odrzucić prośbę o połączenie.
  7. Potwierdź, że zostałeś przekierowany na swoją platformę.