Użyj modelu kodu

Biblioteka Google Identity Services umożliwia użytkownikom żądanie kodu autoryzacji od Google za pomocą wyskakującego okienka w przeglądarce lub przepływu przekierowania. Rozpoczyna to bezpieczny przepływ OAuth 2.0 i powoduje wygenerowanie tokena 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 przeglądarce właściciel konta Google żąda od Google kodu autoryzacji, wykonując gest, 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łuje punkt końcowy kodu autoryzacji za pomocą przekierowania w przeglądarce.
• Platforma backendu hostuje punkt końcowy kodu autoryzacji i odbiera kod. Po weryfikacji platforma wymienia ten kod na tokeny dostępu i odświeżania dla każdego użytkownika, wysyłając żądanie do punktu końcowego tokena Google.
• Google weryfikuje kod autoryzacji, potwierdza, że żądanie pochodzi z bezpiecznej platformy, wydaje tokeny dostępu i odświeżania oraz zwraca je, wywołując punkt końcowy logowania hostowany przez platformę.
• Punkt końcowy logowania otrzymuje tokeny dostępu i odświeżania oraz bezpiecznie przechowuje token odświeżania do późniejszego użycia.

Ważne: na serwerze backendu wymieniasz kod autoryzacji na tokeny odświeżania i tokeny dostępu, wywołując punkt końcowy tokena Google.

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

Możesz udostępnić kod autoryzacji, korzystając z przepływu użytkownika w trybie przekierowania lub wyskakującego okienka. W trybie przekierowania hostujesz punkt końcowy autoryzacji OAuth2 na swoim serwerze, a Google przekierowuje agenta użytkownika do tego punktu końcowego, udostępniając kod autoryzacji jako parametr adresu URL. W trybie wyskakującego okienka definiujesz procedurę obsługi wywołania zwrotnego JavaScript, która wysyła kod autoryzacji na Twój serwer. Możesz użyć trybu wyskakującego okienka, aby zapewnić użytkownikom płynną obsługę bez konieczności opuszczania Twojej witryny.

Aby zainicjować klienta w przypadku:

• przepływu przekierowania, ustaw ux_mode na redirect, a wartość redirect_uri na punkt końcowy kodu autoryzacji platformy. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w konsoli Google Cloud. Musi też być zgodna z regułami weryfikacji identyfikatora URI przekierowania.

• przepływu wyskakującego okienka, ustaw ux_mode na popup, a wartość callback na nazwę funkcji, której będziesz używać do wysyłania kodów autoryzacji na swoją platformę. Wartość redirect_uri domyślnie jest ustawiona na źródło strony, która wywołuje initCodeClient. Przepływ używa tej wartości później, gdy wymieniasz kod autoryzacji na token dostępu lub token odświeżania. Na przykład https://www.example.com/index.html wywołuje initCodeClient, a źródło https://www.example.com jest wartością redirect_url.

Ważne: aby zapewnić najlepszą równowagę między użytecznością a bezpieczeństwem, zalecamy używanie przepływu wyskakującego okienka z modelem kodu autoryzacji.

Ochrona przed atakami CSRF

Przepływy przekierowania i wyskakującego okienka używają nieco innych technik, aby zapobiegać atakom typu Cross-Site-Request-Forgery (CSRF). W trybie przekierowania użyj parametru state OAuth 2.0. Więcej informacji o generowaniu i weryfikowaniu parametru state znajdziesz w sekcji 10.12 RFC6749 Cross-Site Request Forgery. 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, w którym Google przekierowuje przeglądarkę użytkownika do 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'
});

Ważne: punkt końcowy na serwerze backendu odbiera i weryfikuje kod autoryzacji, wymieniając go na tokeny dostępu i odświeżania.

Tryb wyskakującego okienka

Zainicjuj klienta, w którym użytkownik rozpoczyna przepływ autoryzacji w wyskakującym okienku. Po wyrażeniu zgody Google zwraca kod autoryzacji do przeglądarki użytkownika za pomocą funkcji wywołania zwrotnego. Żądanie POST z procedury obsługi wywołania zwrotnego JS dostarcza kod autoryzacji do punktu końcowego na serwerze backendu, gdzie najpierw go weryfikujesz, a następnie kończysz pozostałą część przepływu 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);
  },
});

Ważne: punkt końcowy na serwerze backendu odbiera i weryfikuje kod autoryzacji, wymieniając go na tokeny dostępu i odświeżania.

Wywoływanie przepływu kodu OAuth 2.0

Aby wywołać przepływ użytkownika, wywołaj metodę requestCode() klienta kodu:

<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 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 trybie wyskakującego okienka procedura obsługi określona przez callback, działająca w przeglądarce użytkownika, przekazuje kod autoryzacji do punktu końcowego hostowanego przez Twoją platformę.

W trybie przekierowania Google wysyła żądanie GET do punktu końcowego określonego przez redirect_uri, udostępniając kod autoryzacji w parametrze code adresu URL. Aby otrzymać kod autoryzacji:

• utwórz nowy punkt końcowy autoryzacji, jeśli nie masz istniejącej implementacji, lub

• zaktualizuj istniejący punkt końcowy, aby akceptował żądania GET i parametry adresu URL. Wcześniej Google wysyłało żądanie PUT z 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	Żądanie uwierzytelnienia logowania użytkownika
kod	Kod autoryzacji OAuth2 wygenerowany przez Google
hd	Domena hostowana konta użytkownika
prompt	Okno z prośbą o zgodę użytkownika
zakres	Rozdzielona spacjami lista co najmniej 1 zakresu OAuth2, który ma zostać autoryzowany
stan	Zmienna stanu CRSF

Zgodnie z RFC 6749 klienci MUSZĄ ignorować nierozpoznane parametry odpowiedzi, niezależnie od tego, czy są one wymienione w poprzedniej tabeli.

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 inicjujesz przepływ kodu autoryzacji za pomocą starszych bibliotek JavaScript lub przez bezpośrednie wywoływanie punktów końcowych Google OAuth 2.0, Google wysyła żą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

Ważne: wcześniej do żądań używano metody POST. Zaktualizuj procedurę obsługi, aby akceptowała żądania GET i POST, lub rozważ hostowanie 2 różnych punktów końcowych, jeśli planujesz nadal używać starszych bibliotek JS lub bezpośrednio wywoływać punkty końcowe Google OAuth 2.0 podczas korzystania z biblioteki Google Identity Services.

Weryfikowanie żądania

Aby uniknąć ataków CSRF, wykonaj na serwerze te czynności.

Sprawdź wartość parametru state w trybie przekierowania.

Potwierdź , że w trybie wyskakującego okienka jest obecny nagłówek X-Requested-With: XmlHttpRequest.

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: Wymiana kodu autoryzacji na tokeny odświeżania i dostępu w przewodniku Korzystanie z protokołu OAuth 2.0 w aplikacjach udostępnianych przez serwer WWW.

Uwaga: gdy używasz trybu wyskakującego okienka, wartość redirect_uri używana w kroku 5 i później jest pochodzeniem strony wywołującej. Na przykład https://www.example.com/index.html wywołuje initCodeClient, a źródło: https://www.example.com jest wartością redirect_url.

Zarządzanie tokenami

Twoja platforma bezpiecznie przechowuje tokeny odświeżania. Usuń zapisane tokeny odświeżania, gdy usuniesz konta użytkowników lub gdy użytkownik cofnie zgodę za pomocą google.accounts.oauth2.revoke albo bezpośrednio na stronie https://myaccount.google.com/permissions.

Opcjonalnie możesz użyć RISC, aby chronić konta użytkowników za pomocą ochrony międzykontowej.

Zazwyczaj 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 zaimplementować sposób udostępniania tokena dostępu aplikacji internetowej. Nie jest to jednak opisane w tym przewodniku. 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.