Użyj modelu kodu

Biblioteka Google Identity Services umożliwia użytkownikom żądanie kodu autoryzacji od Google za pomocą wyskakującego okienka lub przekierowania w interfejsie użytkownika. W ten sposób rozpoczyna się bezpieczny proces OAuth 2.0, który kończy się wygenerowaniem tokena dostępu używanego 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 może poprosić Google o kod autoryzacji, wykonując gest, np. klikając przycisk.
• Google odpowiada, wysyłając unikalny kod autoryzacyjny do funkcji 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 autoryzacyjnego za pomocą przekierowania w przeglądarce.
• Platforma backendowa hostuje punkt końcowy kodu autoryzacji i odbiera kod. Po weryfikacji kod jest wymieniany na tokeny dostępu i odświeżania na podstawie użytkownika za pomocą żądania do punktu końcowego tokenów Google.
• Google weryfikuje kod autoryzacji, potwierdza, że żądanie pochodzi z Twojej bezpiecznej platformy, wydaje tokeny dostępu i odświeżania oraz zwraca tokeny, 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 na później.

Ważna informacja: na serwerze backendu wymieniasz kod autoryzacji na tokeny odświeżania i tokeny dostępu, wywołując punkt końcowy tokenów 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

Kod autoryzacji możesz udostępnić, używając przepływu użytkownika w trybie przekierowania lub wyskakującego okienka. W trybie przekierowania na serwerze hostujesz punkt końcowy autoryzacji OAuth 2, a Google przekierowuje agenta użytkownika do tego punktu końcowego, przekazując kod autoryzacji jako parametr URL. W przypadku trybu wyskakującego okienka definiujesz w JavaScriptzie funkcję wywołania zwrotnego, która wysyła kod autoryzacji na serwer. Tryb wyskakujących okienek można wykorzystać, aby zapewnić użytkownikom płynne wrażenia bez konieczności opuszczania witryny.

Aby zainicjować klienta w przypadku:

• Przekieruj UX, ustaw ux_mode na redirect, a wartość redirect_uri na punkt końcowy kodu autoryzacji Twojej platformy. Ta wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w Konsoli API. Musi też być zgodny z zasadami sprawdzania adresów URI przekierowania.

• W procesie obsługi użytkownika dotyczącej wyskakujących okienek ustaw wartość ux_mode na popup, a wartość callback na nazwę funkcji, której użyjesz do wysyłania kodów autoryzacji do swojej platformy.

Ważne: aby zapewnić najlepszy kompromis między użytecznością a bezpieczeństwem, zalecamy korzystanie z przepływu UX w trybie wyskakującego okienka z modelem kodu autoryzacji.

Ochrona przed atakami CSRF

Aby zapobiegać atakom polegającym na fałszowaniu żądań między witrynami (CSRF), w przypadku przekierowań i wyskakujących okienek stosujemy 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 RFC 6749 Cross-Site Request Forgery. W trybie wyskakującego okienka dodasz do żądań niestandardowy nagłówek HTTP, a następnie na serwerze potwierdzisz, że odpowiada on oczekiwanej wartości i pochodzie z oczekiwanego źródła.

Wybierz tryb interfejsu użytkownika, aby wyświetlić fragment kodu zawierający kod uwierzytelniający i obsługę CSRF:

Tryb przekierowania

Inicjowanie klienta, w którym Google przekierowuje przeglądarkę użytkownika do punktu uwierzytelniania, udostępniając kod uwierzytelniania jako parametr adresu URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

Tryb wyskakującego okienka

Inicjuje klienta, w którym przeglądarka użytkownika otrzymuje od Google kod uwierzytelniający i przesyła go na Twój serwer.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, 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

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

<button onclick="client.requestCode();">Authorize with Google</button>

W tym celu użytkownik musi zalogować się na konto Google i zezwolić na udostępnianie poszczególnych zakresów, zanim kod autoryzacji zostanie zwrócony do punktu końcowego przekierowania lub do obsługi wywołania zwrotnego.

Obsługa kodu autoryzacji

Google generuje unikalny kod autoryzacji dla każdego użytkownika, który otrzymasz i potwierdzisz na serwerze zaplecza.

W przypadku trybu wyskakującego okienka menedżer wskazany przez callback, działający w przeglądarce użytkownika, przekazuje kod autoryzacji do punktu końcowego obsługiwanego przez Twoją platformę.

W przypadku trybu przekierowania żądanie GET jest wysyłane do punktu końcowego określonego przez redirect_url, przekazując kod autoryzacji w parametrze adresu URL code. Aby otrzymać kod autoryzacji:

• Utwórz nowy punkt końcowy autoryzacji, jeśli nie masz dotychczasowej implementacji.

• Zaktualizuj istniejący punkt końcowy, aby akceptował żądania GET i parametry adresu URL. Wcześniej używano żądania PUT z wartością kodu autoryzacji w danych.

Punkt końcowy autoryzacji

Punkt końcowy kodu autoryzacji musi obsługiwać żądania GET z tymi parametrami ciągu zapytania URL:

Nazwa	Wartość
authuser	Prośba o uwierzytelnianie użytkownika podczas logowania
kod	Kod autoryzacji OAuth2 wygenerowany przez Google
HD	Hostowana domena konta użytkownika
prompt	Okno z prośbą o zgodę użytkownika
zakres	Lista oddzielonych spacjami zakresów OAuth 2 do autoryzacji
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 uzyskiwania kodu autoryzacji jest inicjowany przez wcześniejsze biblioteki JavaScript lub bezpośrednie wywołania punktów końcowych OAuth 2.0 Google, 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

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

Weryfikowanie prośby

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

Sprawdź wartość parametru state w przypadku trybu przekierowania.

Sprawdź, czy nagłówek X-Requested-With: XmlHttpRequest jest ustawiony na tryb wyskakującego okienka.

Dopiero po pomyślnym zweryfikowaniu żądania kodu uwierzytelniania możesz przejść do uzyskiwania tokenów odświeżania i dostępu od Google.

Pobieranie tokenów dostępu i odświeżania

Gdy platforma backendowa otrzyma od Google kod autoryzacji i potwierdzi żądanie, użyj tego kodu, aby uzyskać od Google tokeny dostępu i odświeżania, które umożliwią Ci wywoływanie interfejsu API.

Postępuj zgodnie z instrukcjami od kroku 5: Wymień kod autoryzacji na tokeny odświeżania i dostępu w przewodniku Używanie protokołu OAuth 2.0 w internetowych aplikacjach serwerowych.

Zarządzanie tokenami

Twoja platforma bezpiecznie przechowuje tokeny odświeżania. usuwać zapisane tokeny odświeżania, gdy konta użytkowników zostaną usunięte lub użytkownik cofnie zgodęgoogle.accounts.oauth2.revoke lub bezpośrednio na stronie https://myaccount.google.com/permissions.

Opcjonalnie możesz użyć RISC, aby chronić konta użytkowników za pomocą ochrony na wielu kontach.

Zwykle platforma backendowa wywołuje interfejsy Google API 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 niniejszym przewodnikiem. W tym przypadku, używając biblioteki klienta interfejsu API Google dla JavaScriptu, użyj elementu gapi.client.SetToken(), aby tymczasowo przechowywać token dostępu w pamięci przeglądarki, i zezwól bibliotece na wywoływanie interfejsów API Google.