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

Ilustracja pokazująca, jak użytkownik może 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 potwierdzenie połączenia konta Google z Twoją aplikacją. Ostatni zrzut ekranu przedstawia konto użytkownika w aplikacji Google.
Rysunek 1. Ekrany logowania użytkownika do Google i ekrany 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.

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 .

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:

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.

Weryfikowanie implementacji

Własną implementację możesz sprawdzić za pomocą narzędzia OAuth 2.0 Playground.

W narzędziu wykonaj te czynności:

  1. Kliknij Konfiguracja , aby otworzyć okno konfiguracji OAuth 2.0.
  2. W polu Procedura OAuth wybierz Po stronie klienta.
  3. W polu Punkty końcowe OAuth wybierz Niestandardowe.
  4. W odpowiednich polach podaj punkt końcowy OAuth 2.0 i identyfikator klienta przypisany do Google.
  5. W sekcji Krok 1 nie wybieraj żadnych zakresów uprawnień Google. Zamiast tego pozostaw to pole puste lub wpisz zakres prawidłowy dla Twojego serwera (lub dowolny ciąg znaków, jeśli nie używasz zakresów OAuth). Gdy skończysz, kliknij Autoryzuj interfejsy API.
  6. W sekcji Krok 2 i Krok 3 przejdź przez proces OAuth 2.0 i sprawdź, czy każdy krok działa prawidłowo.

Implementację możesz zweryfikować za pomocą narzędzia Demo łączenia kont Google.

W narzędziu wykonaj te czynności:

  1. Kliknij przycisk Zaloguj się przez Google.
  2. Wybierz konto, które chcesz połączyć.
  3. Wpisz identyfikator usługi.
  4. Opcjonalnie wpisz co najmniej 1 zakres, do którego chcesz uzyskać dostęp.
  5. Kliknij Uruchom wersję pokazową.
  6. Gdy pojawi się odpowiedni komunikat, potwierdź, że możesz wyrazić zgodę lub odrzucić prośbę o połączenie.
  7. Sprawdź, czy nastąpiło przekierowanie na Twoją platformę.