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:
- 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.
- 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.
Wymagania
- 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:
Wyświetl Politykę prywatności Google Podaj na ekranie zgody link do Polityki prywatności Google.
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.
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.
Możliwość anulowania. Zapewnij użytkownikom możliwość powrotu lub anulowania subskrypcji, jeśli nie chcą tworzyć linków.
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.
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.
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.
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:
- Go to the Google API Console.
- Kliknij Utwórz projekt .
- Wpisz nazwę lub zaakceptuj wygenerowaną sugestię.
- Potwierdź lub edytuj pozostałe pola.
- Kliknij Utwórz .
Aby wyświetlić identyfikator projektu:
- Go to the Google API Console.
- 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.
- Otwórz stronę Ekran zgody OAuth w konsoli interfejsów API Google.
- Jeśli pojawi się taka prośba, wybierz właśnie utworzony projekt.
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
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:
- 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.
- 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ń.
- 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.
- 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ść.
- 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:
- Sprawdź, czy identyfikator
client_id
jest zgodny z identyfikatorem klienta przypisanym do Google i czyredirect_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ż, czyresponse_type
tocode
. - 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.
- 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.
- 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
- 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 parametrycode
istate
. 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:
- Sprawdź, czy
client_id
identyfikuje źródło żądania jako autoryzowane origin oraz żeclient_secret
jest zgodny z oczekiwaną wartością. - 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.
- Sprawdź, czy adres URL określony przez parametr
redirect_uri
jest identyczny do wartości użytej we wstępnym żądaniu autoryzacji. - 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"}
. - 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.
- 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:
- Sprawdź, czy
client_id
identyfikuje źródło żądania jako Google oraz żeclient_secret
jest zgodna z oczekiwaną wartością. - 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.
- 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"}
. - 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.
- 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.
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:
- Wyodrębnij token dostępu z nagłówka autoryzacji i zwróć informacje o użytkowniku powiązanym z tym tokenem.
- 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. 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:
- Kliknij konfiguracji , aby otworzyć okno konfiguracji OAuth 2.0.
- W dziedzinie przepływu OAuth, wybierz Client-side.
- W polu OAuth Endpoints wybierz Niestandardowy.
- W odpowiednich polach określ punkt końcowy OAuth 2.0 i identyfikator klienta przypisany do Google.
- 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.
- 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:
- Kliknij Sign-in z przycisku Google.
- Wybierz konto, które chcesz połączyć.
- Wprowadź identyfikator usługi.
- Opcjonalnie wprowadź co najmniej jeden zakres, do którego poprosisz o dostęp.
- Kliknij Start Demo.
- Po wyświetleniu monitu potwierdź, że możesz wyrazić zgodę i odrzucić prośbę o połączenie.
- Potwierdź, że zostałeś przekierowany na swoją platformę.