Biblioteka Google Identity Services umożliwia użytkownikom wysyłanie do Google żądań kodu autoryzacji za pomocą wyskakującego okienka w przeglądarce lub przepływu UX przekierowania. Rozpoczyna to bezpieczny proces OAuth 2.0 i generuje token dostępu, który służy do wywoływania interfejsów API Google w imieniu użytkownika.
Podsumowanie przepływu kodu autoryzacji OAuth 2.0:
- Właściciel konta Google wysyła do Google z przeglądarki żądanie kodu autoryzacji (np. klikając przycisk).
- Google odpowiada, wysyłając unikalny kod autoryzacji do wywołania zwrotnego w aplikacji internetowej JavaScript działającej w przeglądarce użytkownika lub bezpośrednio wywołując punkt końcowy kodu autoryzacji za pomocą przekierowania przeglądarki.
- Platforma backendu hostuje punkt końcowy kodu autoryzacji i otrzymuje kod. Po weryfikacji ten kod jest wymieniany na tokeny dostępu i odświeżania dla poszczególnych użytkowników za pomocą żądania wysyłanego do punktu końcowego tokena Google.
- Google weryfikuje kod autoryzacji, potwierdza, że żądanie pochodzi z Twojej bezpiecznej platformy, wydaje tokeny dostępu i odświeżania oraz zwraca je, wywołując punkt końcowy logowania hostowany przez Twoją platformę.
- Punkt końcowy logowania otrzymuje tokeny dostępu i odświeżania, bezpiecznie przechowując token odświeżania do późniejszego użycia.
Wymagania wstępne
Aby skonfigurować ekran zgody OAuth, uzyskać identyfikator klienta i wczytać bibliotekę klienta, wykonaj czynności opisane w sekcji Konfiguracja.
Inicjowanie klienta kodu
Metoda google.accounts.oauth2.initCodeClient() inicjuje klienta kodu.
Tryb wyskakującego okienka lub przekierowania
Kod autoryzacji możesz udostępnić za pomocą przepływu użytkownika w trybie Przekierowanie lub Wyskakujące okienko. W trybie przekierowania hostujesz na swoim serwerze punkt końcowy autoryzacji OAuth2, a Google przekierowuje do niego agenta użytkownika, udostępniając kod autoryzacji jako parametr URL. W przypadku trybu wyskakującego okienka definiujesz procedurę obsługi wywołania zwrotnego JavaScript, która wysyła kod autoryzacji na Twój serwer. Tryb wyskakującego okienka może być używany do zapewnienia użytkownikom wygody bez konieczności opuszczania Twojej witryny.
Aby zainicjować klienta w przypadku:
W przypadku przepływu UX przekierowania ustaw
ux_modenaredirect, a wartośćredirect_urina punkt końcowy kodu autoryzacji platformy. Wartość musi dokładnie pasować do jednego z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w Google Cloud Console. Musi on też być zgodny z regułami sprawdzania identyfikatora URI przekierowania.W przypadku przepływu UX w wyskakującym okienku ustaw wartość
ux_modenapopup, a wartośćcallbackna nazwę funkcji, której będziesz używać do wysyłania kodów autoryzacji na swoją platformę. Wartośćredirect_urijest domyślnie ustawiona na źródło strony, która wywołujeinitCodeClient. Ta wartość jest używana później w procesie, gdy kod autoryzacji jest wymieniany na token dostępu lub token odświeżania. Na przykład wywołaniehttps://www.example.com/index.htmlwywołujeinitCodeClient, a punkt początkowyhttps://www.example.comjest wartościąredirect_url.
Ochrona przed atakami typu CSRF
Aby zapobiegać atakom typu Cross-Site-Request-Forgery (CSRF), w przypadku przepływów UX w trybach przekierowania i wyskakującego okienka stosuje się nieco inne techniki. W przypadku trybu przekierowania używany jest parametr state OAuth 2.0. Więcej informacji o generowaniu i weryfikowaniu parametru state znajdziesz w sekcji 10.12 standardu RFC6749 dotyczącej fałszowania żądań między witrynami. W trybie wyskakującego okienka dodajesz do żądań niestandardowy nagłówek HTTP, a następnie na serwerze potwierdzasz, że pasuje on do oczekiwanej wartości i źródła.
Wybierz tryb UX, aby wyświetlić fragment kodu pokazujący obsługę kodu autoryzacji i CSRF:
Tryb przekierowania
Zainicjuj klienta, do którego Google przekieruje przeglądarkę użytkownika do Twojego punktu końcowego uwierzytelniania, udostępniając kod autoryzacji jako parametr adresu URL.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'redirect',
redirect_uri: 'https://oauth2.example.com/code',
state: 'YOUR_BINDING_VALUE'
});
Tryb wyskakującego okienka
Zainicjuj klienta, w przypadku którego użytkownik rozpoczyna proces autoryzacji w oknie wyskakującym. Po uzyskaniu zgody Google zwraca kod autoryzacji do przeglądarki użytkownika za pomocą funkcji wywołania zwrotnego. Żądanie POST z funkcji zwrotnej JS dostarcza kod autoryzacji do punktu końcowego na serwerze backendu, gdzie jest on najpierw weryfikowany, a następnie dokańczany jest pozostały proces OAuth.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'popup',
callback: (response) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', "https://oauth2.example.com/code", true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
// Set custom header for CRSF
xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
xhr.onload = function() {
console.log('Auth code response: ' + xhr.responseText);
};
xhr.send('code=' + response.code);
},
});
Uruchamianie procedury kodu OAuth 2.0
Wywołaj metodę requestCode() klienta kodu, aby uruchomić proces użytkownika:
<button onclick="client.requestCode();">Authorize with Google</button>
Wymaga to zalogowania się użytkownika na konto Google i wyrażenia zgody na udostępnianie poszczególnych zakresów przed zwróceniem kodu autoryzacji do punktu końcowego przekierowania lub do procedury obsługi wywołania zwrotnego.
Obsługa kodu autoryzacji
Google generuje unikalny kod autoryzacji dla każdego użytkownika, który otrzymujesz i weryfikujesz na serwerze backendu.
W przypadku trybu wyskakującego okienka moduł obsługi określony przez callback, działający w przeglądarce użytkownika, przekazuje kod autoryzacji do punktu końcowego hostowanego przez Twoją platformę.
W przypadku trybu przekierowania do punktu końcowego określonego przez GET wysyłane jest żądanie redirect_uri, które udostępnia kod autoryzacji w parametrze code adresu URL. Aby otrzymać kod autoryzacji:
Utwórz nowy punkt końcowy autoryzacji, jeśli nie masz jeszcze implementacji, lub
Zaktualizuj istniejący punkt końcowy, aby akceptował żądania
GETi parametry adresu URL. Wcześniej używano żądaniaPUTz wartością kodu autoryzacji w ładunku.
Punkt końcowy autoryzacji
Punkt końcowy kodu autoryzacji musi obsługiwać żądania GET z tymi parametrami ciągu zapytania adresu URL:
| Nazwa | Wartość |
|---|---|
| authuser | Prośba o uwierzytelnienie logowania użytkownika |
| kod | Kod autoryzacji OAuth2 wygenerowany przez Google |
| HD | Hostowana domena konta użytkownika |
| prompt | Okno z prośbą o zgodę użytkownika |
| zakres | Lista rozdzielonych spacjami zakresów OAuth2, które mają zostać autoryzowane |
| stan | Zmienna stanu CRSF |
Przykład żądania GET z parametrami adresu URL do punktu końcowego o nazwie auth-code hostowanego przez example.com:
Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent
Gdy proces kodu autoryzacji jest inicjowany przez starsze biblioteki JavaScript lub przez bezpośrednie wywołania punktów końcowych Google OAuth 2.0, używane jest żądanie POST.
Przykład żądania POST zawierającego kod autoryzacji jako ładunek w treści żądania HTTP:
Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw
Weryfikowanie żądania
Aby uniknąć ataków CSRF, na serwerze wykonaj te czynności:
Sprawdź wartość parametru state w przypadku trybu przekierowania.
Potwierdź, że nagłówek X-Requested-With: XmlHttpRequest jest ustawiony w trybie wyskakującego okienka.
Następnie możesz uzyskać tokeny odświeżania i dostępu od Google tylko wtedy, gdy najpierw pomyślnie zweryfikujesz żądanie kodu autoryzacji.
Uzyskiwanie tokenów dostępu i odświeżania
Gdy platforma backendu otrzyma od Google kod autoryzacji i zweryfikuje żądanie, użyj kodu autoryzacji, aby uzyskać od Google tokeny dostępu i odświeżania do wywoływania interfejsów API.
Postępuj zgodnie z instrukcjami, zaczynając od kroku 5: wymień kod autoryzacji na tokeny odświeżania i dostępu w przewodniku Używanie OAuth 2.0 w aplikacjach udostępnianych przez serwer WWW.
Zarządzanie tokenami
Twoja platforma bezpiecznie przechowuje tokeny odświeżania. Usuwaj zapisane tokeny odświeżania, gdy konta użytkowników są usuwane lub gdy użytkownik wycofuje zgodę w usłudze google.accounts.oauth2.revoke lub bezpośrednio na stronie https://myaccount.google.com/permissions.
Opcjonalnie możesz rozważyć użycie RISC, aby chronić konta użytkowników za pomocą ochrony międzykontowej.
Zwykle platforma backendu wywołuje interfejsy API Google za pomocą tokena dostępu. Jeśli Twoja aplikacja internetowa będzie też bezpośrednio wywoływać interfejsy API Google z przeglądarki użytkownika, musisz wdrożyć sposób udostępniania tokena dostępu aplikacji internetowej. Nie jest to jednak objęte zakresem tego przewodnika. Jeśli korzystasz z tego podejścia i używasz biblioteki klienta interfejsu API Google dla JavaScript, użyj gapi.client.SetToken(), aby tymczasowo zapisać token dostępu w pamięci przeglądarki i umożliwić bibliotece wywoływanie interfejsów API Google.