OpenID Connect

Interfejsy API Google OAuth 2.0 mogą być używane do uwierzytelniania i autoryzacji. Ten dokument opisuje nasz sposób uwierzytelniania OAuth 2.0 zgodny ze specyfikacją OpenID Connect oraz certyfikat OpenID. Zastosowana jest również dokumentacja o używaniu dostępu przez OAuth 2.0 do interfejsów API Google. Jeśli chcesz korzystać z tego protokołu w interaktywny sposób, zalecamy stronę Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą usługi Stack Overflow, oznacz swoje pytania tagiem „google-oauth”.

Konfigurowanie protokołu OAuth 2.0

Zanim Twoja aplikacja będzie mogła używać systemu uwierzytelniania Google OAuth 2.0 do logowania się użytkowników, musisz skonfigurować projekt w Google API Console uzyskiwaniu danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania oraz (opcjonalnie) dostosować informacje o marce, które użytkownicy zobaczą na ekranie zgody użytkownika. Możesz też użyć API Console , aby utworzyć konto usługi, włączyć płatności, skonfigurować filtrowanie i wykonywać inne zadania. Więcej informacji znajdziesz w Centrum pomocyGoogle API Console.

Uzyskiwanie danych logowania OAuth 2.0

Aby uwierzytelnić użytkowników i uzyskać dostęp do interfejsów API Google, potrzebujesz danych logowania OAuth 2.0, w tym identyfikatora klienta i tajnego klucza klienta.

要查看给定OAuth 2.0凭据的客户端ID和客户端密钥,请单击以下文本: 选择凭据 。在打开的窗口中,选择您的项目和所需的凭证,然后单击“ 查看”

或者,从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥:

  1. Go to the Credentials page.
  2. 单击您的凭证名称或铅笔( )图标。您的客户ID和密码位于页面顶部。

Ustaw identyfikator URI przekierowania

Identyfikator URI przekierowania ustawiony w API Console określa, gdzie Google wysyła odpowiedzi na żądania uwierzytelniania.

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

  1. Go to the Credentials page.
  2. In the OAuth 2.0 client IDs section of the page, click a credential.
  3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Dostosowywanie ekranu zgody użytkownika

W przypadku użytkowników uwierzytelnianie OAuth 2.0 obejmuje ekran zgody, który opisuje informacje udostępniane przez użytkownika oraz obowiązujące warunki. Na przykład po zalogowaniu się użytkownik może zobaczyć prośbę o przyznanie aplikacji dostępu do swojego adresu e-mail i podstawowych informacji o koncie. Prosisz o dostęp do tych informacji za pomocą parametru scope, który Twoja aplikacja uwzględnia w żądaniu uwierzytelniania. Zakresy możesz też wykorzystać, aby żądać dostępu do innych interfejsów Google API.

Na ekranie zgody użytkownika są też wyświetlane informacje o marce, takie jak nazwa produktu, logo i adres URL strony głównej. Ty zarządzasz informacjami o marce w API Console.

要启用项目的同意屏幕:

  1. Consent Screen page中打开Google API Console 。
  2. If prompted, select a project, or create a new one.
  3. 填写表格,然后点击保存

Podane niżej okno z prośbą o zgodę pokazuje, co zobaczy użytkownik po połączeniu w żądaniu zakresów protokołu OAuth 2.0 i Dysku Google. To ogólne okno dialogowe zostało utworzone za pomocą platformy Google OAuth 2.0 Playground, więc nie zawiera informacji o marce, które byłyby API Console.

Zrzut ekranu strony zgody

Uzyskiwanie dostępu do usługi

Google i inne firmy udostępniają biblioteki, których możesz używać do obsługi wielu szczegółów dotyczących uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów API Google. Przykłady obejmują usługi Google Identity i biblioteki klienta Google, które są dostępne na różnych platformach.

Jeśli nie chcesz korzystać z biblioteki, postępuj zgodnie z instrukcjami w pozostałej części tego dokumentu, które opisują przepływy żądań HTTP, które udostępniają przestarzałe biblioteki.

Uwierzytelnianie użytkownika

Uwierzytelnianie użytkownika wymaga jego uzyskania i zweryfikowania. Tokeny identyfikatorów to standardowa funkcja OpenID Connect przeznaczona do udostępniania potwierdzeń tożsamości w internecie.

Najczęściej stosowanym sposobem uwierzytelniania użytkowników i uzyskiwania tokena identyfikatora jest proces „serwer” i „domyślny”. Przepływ serwera pozwala serwerowi backendu aplikacji na weryfikację tożsamości osoby przy użyciu przeglądarki lub urządzenia mobilnego. Przepływ niejawny jest używany, gdy aplikacja po stronie klienta (zazwyczaj aplikacja JavaScript działająca w przeglądarce) potrzebuje dostępu do interfejsów API bezpośrednio zamiast przez serwer backendu.

Ten dokument zawiera opis sposobu wykonywania procesu na serwerze w celu uwierzytelniania użytkownika. Przepływ niejawny jest znacznie bardziej skomplikowany ze względu na zagrożenia związane z obsługą i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć komunikat pośredni, zalecamy użycie usług tożsamości Google.

Przepływ serwera

Pamiętaj, aby skonfigurować aplikację w: API Console, aby umożliwić jej korzystanie z tych protokołów i uwierzytelnianie użytkowników. Gdy użytkownik próbuje zalogować się przez Google, musisz:

  1. Tworzenie tokena stanu antyfałszerstwa
  2. Wyślij do Google prośbę o uwierzytelnienie
  3. Potwierdzanie tokena stanu fałszowania
  4. Wymień code na token dostępu i token tożsamości
  5. Pobieranie informacji o użytkowniku z tokena identyfikatora
  6. Uwierzytelnianie użytkownika

1. Tworzenie tokena stanu antyfałszerstwa

Musisz chronić bezpieczeństwo użytkowników, zapobiegając atakom polegającym na fałszowaniu wyników. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który zachowuje stan między aplikacją a klientem użytkownika. Później dopasowujesz ten unikalny token sesji do odpowiedzi uwierzytelniania zwróconej przez usługę logowania Google OAuth, aby potwierdzić, że użytkownik wysyła żądanie, a nie złośliwe oprogramowanie. Tokeny te są często określane jako tokeny fałszowania żądań z innej witryny (CSRF).

Jednym z porządków w przypadku tokena stanu jest ciąg 30 znaków utworzony przy użyciu wysokiej jakości generatora liczb losowych. Inny jest skrót wygenerowany przez podpisanie niektórych zmiennych stanu sesji kluczem, który jest tajny w backendzie.

Ten kod pokazuje generowanie unikalnych tokenów sesji.

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla PHP.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Python.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Wyślij żądanie uwierzytelniania do Google

W następnym kroku utwórz żądanie HTTPS GET z odpowiednimi parametrami URI. Pamiętaj, że na każdym etapie tego procesu używane jest HTTPS, a nie HTTP. Połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint. W poniższej dyskusji założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth.

W przypadku żądania podstawowego określ te parametry:

  • client_id uzyskany z API ConsoleCredentials page.
  • response_type, które w podstawowym żądaniu kodu autoryzacji powinno mieć postać code. (Więcej informacji znajdziesz na stronie response_type).
  • scope, które w podstawowym żądaniu powinno mieć wartość openid email. (Więcej informacji znajdziesz na scope).
  • redirect_uri powinien być punktem końcowym HTTP na serwerze, który będzie otrzymywać odpowiedzi od Google. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials page. Jeśli ta wartość nie będzie pasować do autoryzowanego identyfikatora URI, żądanie zakończy się niepowodzeniem i wyświetli się błąd redirect_uri_mismatch.
  • Pole state powinno zawierać wartość tokena zapobiegającego fałszowaniu identyfikatorów sesji oraz wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wróci do aplikacji, np. początkowy adres URL. (Więcej informacji znajdziesz na state).
  • nonce to losowa wartość generowana przez aplikację, która umożliwia ochronę przed ponownym odtwarzaniem, jeśli jest włączona.
  • login_hint może być adresem e-mail użytkownika lub ciągiem znaków sub, który jest odpowiednikiem identyfikatora Google użytkownika. Jeśli nie podasz danych login_hint, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zgodę na zwolnienie adresu e-mail użytkownika Twojej aplikacji. (Więcej informacji: login_hint).
  • Użyj parametru hd, aby zoptymalizować procedurę OpenID Connect dla użytkowników określonej domeny powiązanej z organizacją Google Cloud. (Więcej informacji znajdziesz na stronie hd).

Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect z podziałami wiersza i miejscami do odczytania:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Użytkownicy muszą wyrazić zgodę, jeśli aplikacja będzie prosić o nowe informacje na ich temat lub z prośbą o dostęp do konta, który wcześniej nie został zatwierdzony.

3. Potwierdź token stanu fałszowania

Odpowiedź jest wysyłana do redirect_uri wskazanego w żądaniu. Wszystkie odpowiedzi są zwracane w ciągu zapytania, jak pokazano poniżej:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Na serwerze musisz potwierdzić, czy state otrzymany od Google jest zgodny z tokenem sesji utworzonym w kroku 1. Ta weryfikacja w obie strony pomaga upewnić się, że żądanie wykonuje użytkownik, a nie złośliwy skrypt.

Ten kod potwierdza tokeny sesji utworzone w kroku 1:

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla PHP.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Python.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Wymień code na token dostępu i token tożsamości

Odpowiedź zawiera parametr code – jednorazowy kod autoryzacji, który Twój serwer może wymienić na token dostępu i token tożsamości. Serwer dokonuje tej wymiany, wysyłając żądanie HTTPS POST. Żądanie POST jest wysyłane do punktu końcowego tokena, który należy pobrać z dokumentu wykrywania za pomocą wartości metadanych token_endpoint. W tej dyskusji zakładamy, że punkt końcowy to https://oauth2.googleapis.com/token. Żądanie musi zawierać te parametry w treści POST:

Pola
code Kod autoryzacji zwracany z wstępnego żądania.
client_id Identyfikator klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
client_secret Tajny klucz klienta uzyskany z API ConsoleCredentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
redirect_uri Autoryzowany identyfikator URI przekierowania dla danego atrybutu client_id określony w API ConsoleCredentials page, zgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania.
grant_type To pole musi zawierać wartość authorization_code zdefiniowaną w specyfikacji OAuth 2.0.

Rzeczywiste żądanie może wyglądać tak:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Pomyślna odpowiedź na to żądanie zawiera następujące pola w tablicy JSON:

Pola
access_token Token, który można wysłać do interfejsu API Google.
expires_in Pozostały okres dostępu do tokena dostępu (w sekundach).
id_token JWT zawierający informacje o tożsamości użytkownika podpisanego cyfrowo przez Google.
scope Zakresy dostępu przyznawane przez access_token mają postać listy ciągów znaków rozdzielanych spacjami, w których jest rozróżniana wielkość liter.
token_type Określa typ zwróconego tokena. Obecnie to pole ma zawsze wartość Bearer.
refresh_token (opcjonalnie)

To pole jest widoczne tylko wtedy, gdy w żądaniu uwierzytelniania parametr access_type jest ustawiony na offline. Szczegółowe informacje znajdziesz w artykule Tokeny odświeżania.

5. Uzyskiwanie informacji o użytkowniku z tokena tożsamości

Token identyfikatora to JWT (token sieciowy JSON), czyli zaszyfrowany kryptograficznie obiekt JSON zakodowany w standardzie Base64. Zwykle ważne jest, aby przed użyciem tokena identyfikatora zweryfikować go. Ponieważ komunikujesz się bezpośrednio z Google przez kanał HTTPS bez pośredników i używasz swojego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token naprawdę pochodzi od Google i jest prawidłowy. Jeśli serwer przekazuje token identyfikatora do innych komponentów aplikacji, bardzo ważne jest, aby przed sprawdzeniem każdy z nich sprawdził token.

Większość bibliotek interfejsów API łączy weryfikację z procesem dekodowania wartości zakodowanych w formacie base64url i analizowania wewnątrz kodu JSON, więc prawdopodobnie ostatecznie okaże się, że token zostanie uruchomiony podczas uzyskiwania dostępu do tokenów.

Ładunek tokena tożsamości

Token identyfikatora to obiekt JSON zawierający zbiór par nazwa/wartość. Oto przykład sformatowany pod kątem czytelności:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Tokeny identyfikatorów Google mogą zawierać te pola (nazywane deklaracjami):

Roszczenie zapisana karta Opis
aud zawsze Lista odbiorców, do której jest przypisany ten token tożsamości. Musi to być jeden z identyfikatorów klienta OAuth 2.0 Twojej aplikacji.
exp zawsze Data ważności, po której token tożsamości nie może zostać przyjęty. Wartość jest podawana w czasie uniksowym (liczba całkowita w sekundach).
iat zawsze Godzina wydania tokena tożsamości. Wartość jest podawana w czasie uniksowym (liczba całkowita w sekundach).
iss zawsze Identyfikator wydawcy odpowiedzi. Zawsze https://accounts.google.com lub accounts.google.com w przypadku tokenów tożsamości Google.
sub zawsze Unikalny identyfikator użytkownika używany na wszystkich kontach Google, który nigdy nie został ponownie użyty. Konto Google może mieć wiele adresów e-mail w różnych momentach, ale wartość sub nigdy się nie zmienia. Użyj sub w aplikacji jako klucza unikalnego identyfikatora użytkownika. Maksymalna długość 255 znaków ASCII (wielkość liter ma znaczenie).
at_hash Hasz tokena dostępu. Sprawdza, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest wywoływany z wartością access_token w przepływie serwera, to twierdzenie jest zawsze uwzględniane. Tego roszczenia można użyć jako alternatywnego mechanizmu do ochrony przed atakami mających na celu fałszowanie żądań innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu.
azp client_id autoryzowanego prowadzącego. To roszczenie jest potrzebne tylko wtedy, gdy strona żądająca tokena tożsamości różni się od jego odbiorców. Możliwe, że tak samo będzie w przypadku aplikacji hybrydowych, w których aplikacja internetowa i aplikacja na Androida mają inny protokół OAuth 2.0 (client_id), ale współdzielą ten sam projekt interfejsów API Google.
email Adres e-mail użytkownika. Ta wartość może nie być unikalna dla tego użytkownika i nie może być używana jako klucz podstawowy. Podane tylko wtedy, gdy zakres zawiera wartość zakresu email.
email_verified Wartość to „prawda”, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie „fałsz”.
family_name Nazwisko użytkownika. Można je podać, jeśli istnieje roszczenie name.
given_name Imię użytkownika lub imię. Można je podać, jeśli istnieje roszczenie name.
hd Domena powiązana z organizacją użytkownika Google Cloud. Podawana tylko wtedy, gdy użytkownik należy do organizacji Google Cloud.
locale Region użytkownika, podany za pomocą tagu języka BCP 47. Wartość może być podana, jeśli istnieje roszczenie name.
name Pełne imię i nazwisko użytkownika w wyświetlanej formie. Wartość może być podana, jeśli:
  • Zakres żądania zawierał ciąg „profile”
  • Token identyfikatora jest zwracany podczas odświeżania tokena

Jeśli masz name roszczeń, możesz ich używać do aktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma gwarancji, że roszczenie się pojawi.

nonce Wartość nonce podana przez aplikację w żądaniu uwierzytelniania. Zadbaj o to, aby była wyświetlana tylko raz, co zapewni ochronę przed atakami typu replay.
picture Adres URL zdjęcia profilowego użytkownika. Wartość może być podana, jeśli:
  • Zakres żądania zawierał ciąg „profile”
  • Token identyfikatora jest zwracany podczas odświeżania tokena

Jeśli masz picture roszczeń, możesz ich używać do aktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma gwarancji, że roszczenie się pojawi.

profile Adres URL strony profilu użytkownika. Wartość może być podana, jeśli:
  • Zakres żądania zawierał ciąg „profile”
  • Token identyfikatora jest zwracany podczas odświeżania tokena

Jeśli masz profile roszczeń, możesz ich używać do aktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma gwarancji, że roszczenie się pojawi.

6. Uwierzytelnianie użytkownika

Po uzyskaniu informacji o użytkowniku z tokena identyfikatora należy wykonać zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik istnieje już w bazie danych, musisz rozpocząć sesję aplikacji dla tego użytkownika, jeśli wszystkie wymagania dotyczące logowania są spełnione przez odpowiedź interfejsu API Google.

Jeśli użytkownik nie istnieje w bazie danych użytkowników, musisz przekierować go do nowego procesu rejestracji. Możesz mieć możliwość automatycznego zarejestrowania użytkownika na podstawie informacji otrzymanych od Google, a dodatkowo możesz być w stanie wstępnie wypełnić wiele pól wymaganych w formularzu rejestracyjnym. Oprócz informacji z tokena tożsamości w naszych punktach końcowych profili użytkowników możesz znaleźć dodatkowe informacje o profilu użytkownika.

Tematy zaawansowane

Więcej informacji o interfejsie Google OAuth 2.0 API znajdziesz w poniższych sekcjach. Te informacje są przeznaczone dla deweloperów, którzy mają zaawansowane wymagania związane z uwierzytelnianiem i autoryzacją.

Dostęp do innych interfejsów API Google

Jedną z zalet uwierzytelniania OAuth 2.0 jest to, że aplikacja może uzyskiwać uprawnienia do korzystania z innych interfejsów Google API w imieniu użytkownika (np. YouTube, Dysk Google, Kalendarz lub Kontakty) w momencie uwierzytelniania użytkownika. Aby to zrobić, dołącz inne potrzebne zakresy w żądaniu uwierzytelniania wysłanym do Google. Aby na przykład dodać do żądania uwierzytelniania grupę wiekową użytkownika, przekaż parametr zakresu openid email https://www.googleapis.com/auth/profile.agerange.read. Użytkownik zobaczy odpowiedni komunikat na ekranie zgody. Token dostępu, który otrzymujesz od Google, pozwala korzystać ze wszystkich interfejsów API powiązanych z zakresami dostępu, których prośba została przyznana.

Odśwież tokeny

W swojej prośbie o dostęp do interfejsu API możesz poprosić o zwrot tokena odświeżania podczas wymiany code. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy użytkownika nie ma w aplikacji. Aby zażądać tokena odświeżania, dodaj w żądaniu uwierzytelniania parametr access_type na wartość offline.

Uwagi:

  • Token odświeżania należy przechowywać w bezpieczny i trwały sposób, ponieważ token odświeżania można uzyskać tylko po pierwszym uruchomieniu procesu wymiany kodu.
  • Obowiązuje limit liczby tokenów odświeżania: jeden limit na jedną kombinację klienta i użytkownika oraz jeden na użytkownika we wszystkich klientach. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, mogą one zostać ograniczone, co sprawi, że starsze tokeny odświeżania przestaną działać.

Więcej informacji znajdziesz w artykule Odświeżanie tokena dostępu (dostęp offline).

Możesz poprosić użytkownika o ponowne przyznanie uprawnień dostępu aplikacji, ustawiając parametr prompt na consent w żądaniu uwierzytelniania. Po uwzględnieniu obiektu prompt=consent ekran zgody wyświetla się za każdym razem, gdy aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przyznane projektowi interfejsów API Google. Z tego powodu dodaj prompt=consent tylko wtedy, gdy jest to konieczne.

Więcej informacji o parametrze prompt znajdziesz w tabeli prompt w tabeli Uwierzytelnianie identyfikatora URI.

Parametry identyfikatora uwierzytelniania

Poniższa tabela zawiera bardziej szczegółowe opisy parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0 Google.

Parametr Wymagany Opis
client_id (Wymagane) Ciąg identyfikatora klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
nonce (Wymagane) Losowa wartość wygenerowana przez aplikację, która włącza ochronę przed ponownym odtwarzaniem.
response_type (Wymagane) Jeśli wartość to code, uruchamia podstawowy przepływ kodu autoryzacji, który wymaga POST do punktu końcowego tokena, aby uzyskać tokeny. Jeśli wartość to token id_token lub id_token token, uruchamia niejawny przepływ, który wymaga użycia kodu JavaScript w identyfikatorze URI przekierowania do pobierania tokenów z identyfikatora #fragment identyfikatora.
redirect_uri (Wymagane) Określa, gdzie jest wysyłana odpowiedź. Wartość tego parametru musi dokładnie odpowiadać jednej z autoryzowanych wartości przekierowania ustawionych w polu API ConsoleCredentials page (w tym schematu HTTP lub HTTPS, wielkości liter oraz końcowego znaku „/”, jeśli taki jest).
scope (Wymagane)

Parametr zakresu musi zaczynać się od wartości openid, a następnie zawierać wartość profile, email lub obie.

Jeśli wartość zakresu profile jest obecna, token tożsamości może (ale nie jest gwarantowany) zawierać domyślne roszczenia profile użytkownika.

Jeśli wartość zakresu email jest obecna, token identyfikatora zawiera deklaracje email i email_verified.

Oprócz tych zakresów, argumentu zakres może też zawierać inne wartości zakresu. Wszystkie wartości zakresu muszą być rozdzielone spacjami. Jeśli np. chcesz mieć dostęp do pliku na Dysku Google użytkownika, parametr zakresu może wyglądać tak: openid profile email https://www.googleapis.com/auth/drive.file.

Informacje o dostępnych zakresach znajdziesz w artykule Zakresy OAuth 2.0 dla interfejsów API Google lub w dokumentacji interfejsu Google API, której chcesz użyć.

state (Opcjonalne, ale zdecydowanie zalecane)

Ciąg nieprzejrzysty, który jest przesyłane w obie strony zgodnie z protokołem, co oznacza, że jest zwracany jako parametr URI w procesie podstawowym oraz w identyfikatorze #fragment identyfikatora URI w procesie wynikowym.

Funkcja state może być przydatna do korelowania żądań i odpowiedzi. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania zainicjowanego przez aplikację. Jeśli wygenerujesz losowy ciąg lub zaszyfrujesz hasz stanu klienta (np. plik cookie), w tej zmiennej state możesz sprawdzić odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami takimi jak sfałszowanie żądań z innej witryny.

access_type (Opcjonalne) Dozwolone wartości to offline i online. Efekt jest udokumentowany w sekcji Dostęp offline. Jeśli zostanie zażądany token dostępu, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość offline.
display (Opcjonalne) Wartość ciągu znaków ASCII określająca, w jaki sposób serwer autoryzacji wyświetla strony interfejsu uwierzytelniania i uzyskiwania zgody. Serwery Google obsługują te wartości, które są akceptowane i akceptowane oraz nie mają na nie wpływu: page, popup, touch i wap.
hd (Opcjonalne)

Usprawnij proces logowania się na konta należące do organizacji Google Cloud. Dodając domenę organizacji Google Cloud (na przykład mycollege.edu), możesz wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby przeprowadzać optymalizację pod kątem kont organizacji w Google Cloud, a nie tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki (*): hd=*.

Nie polegaj na tej optymalizacji interfejsu użytkownika, aby kontrolować, kto ma dostęp do Twojej aplikacji – żądania wysyłane po stronie klienta można modyfikować. Pamiętaj, aby sprawdzić, czy zwrócony token dokumentu tożsamości ma wartość roszczenia hd zgodną z Twoimi oczekiwaniami (np. mycolledge.edu). W odróżnieniu od parametru żądania roszczenie do tokena ID znajduje się w tokenie zabezpieczeń Google, więc można mu zaufać.

include_granted_scopes (Opcjonalne) Jeśli ten parametr ma wartość true i prośba o autoryzację została przyznana, autoryzacja obejmuje wszystkie wcześniejsze autoryzacje dla tej kombinacji użytkownika i aplikacji w innych zakresach. Zobacz Autoryzacja przyrostowa.

Pamiętaj, że w procesie instalacji aplikacji nie można stopniowo zwiększać autoryzacji.

login_hint (Opcjonalne) Gdy aplikacja wie, którego użytkownika próbuje uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Pominięcie tej podpowiedzi powoduje pominięcie wyboru konta i wstępne wypełnienie pola e-maila w formularzu logowania lub wybranie odpowiedniej sesji (jeśli użytkownik korzysta z wielokrotnego logowania), co może pomóc w uniknięciu problemów, jeśli aplikacja loguje się na niewłaściwe konto użytkownika. Wartością może być adres e-mail lub ciąg sub, który jest odpowiednikiem identyfikatora Google użytkownika.
prompt (Opcjonalne) Lista rozdzielonych spacjami wartości ciągu określających, czy serwer autoryzacji prosi użytkownika o ponowne uwierzytelnienie i zgodę. Możliwe wartości:
  • none

    Serwer autoryzacji nie wyświetla żadnych ekranów uwierzytelniania ani ekranów zgody użytkownika. Jeśli użytkownik nie jest jeszcze uwierzytelniony i nie ma wstępnie skonfigurowanej zgody dla żądanych zakresów, zwróci błąd. Możesz skorzystać z none, aby sprawdzić istniejące uwierzytelnianie lub zgodę.

  • consent

    Serwer autoryzacji prosi użytkownika o zgodę przed zwróceniem informacji klientowi.

  • select_account

    Serwer autoryzacji wyświetla użytkownikowi prośbę o wybranie konta użytkownika. Dzięki temu użytkownik mający wiele kont na serwerze autoryzacji może wybrać spośród wielu kont, z których może korzystać w danej chwili.

Jeśli nie określisz żadnej wartości, a użytkownik nie wyraził wcześniej zgody na dostęp, zostanie wyświetlony ekran zgody.

Weryfikowanie tokena tożsamości

Musisz zweryfikować wszystkie tokeny na serwerze, chyba że pochodzą one bezpośrednio od Google. Na przykład serwer musi zweryfikować jako autentyczne tokeny identyfikacyjne otrzymywane z aplikacji klienckich.

Oto kilka typowych sytuacji, w których możesz wysyłać tokeny tożsamości na swój serwer:

  • Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny identyfikatorów informują o konkretnych użytkownikach wysyłających żądania i w przypadku klientów, którym przyznano tokeny.

Tokeny dokumentów tożsamości mają charakter poufny i mogą być używane w przypadku przechwycenia. Musisz się upewnić, że tokeny są obsługiwane w bezpieczny sposób, przesyłając je tylko przez HTTPS i tylko przez dane POST lub w nagłówkach żądań. Jeśli przechowujesz na serwerze tokeny tożsamości, musisz je też bezpiecznie przechowywać.

Tokeny identyfikatorów są przydatne, bo możesz je przekazywać między różnymi komponentami aplikacji. Te komponenty mogą używać tokena identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Zanim jednak użyjesz informacji w tokenie identyfikatora lub będziesz używać go jako potwierdzenia, że użytkownik się uwierzytelnił, musisz je zweryfikować.

Weryfikacja tokena tożsamości wymaga kilku kroków:

  1. Sprawdź, czy wydawca dokumentu tożsamości ma prawidłowy podpis. Tokeny wydane przez Google są podpisane jednym z certyfikatów wymienionych w identyfikatorze URI podanym w wartości metadanych jwks_uri dokumentu Discovery.
  2. Sprawdź, czy wartość roszczenia iss w tokenie identyfikatora wynosi https://accounts.google.com lub accounts.google.com.
  3. Sprawdź, czy wartość roszczenia aud w tokenie identyfikatora jest równa identyfikatorowi klienta aplikacji.
  4. Sprawdź, czy nie upłynął termin ważności (roszczenia: exp) tokena tożsamości.
  5. Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora ma deklarację hd pasującą do akceptowanej domeny powiązanej z organizacją Google Cloud.

Kroki 2–5 obejmują tylko proste porównanie ciągów znaków i dat, więc nie będziemy ich tu szczegółowo omawiać.

Pierwszy krok jest bardziej złożony i wymaga sprawdzenia podpisu kryptograficznego. Do debugowania możesz użyć punktu końcowego tokeninfo Google, aby porównać je z przetwarzaniem lokalnym wdrożonym na serwerze lub urządzeniu. Załóżmy, że wartość tokena identyfikatora to XYZ123. Następnie musisz usunąć identyfikator URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jeśli podpis tokena jest prawidłowy, odpowiedź będzie ładunkiem JWT w odkodowanym formularzu obiektu JSON.

Punkt końcowy tokeninfo przydaje się do debugowania, ale do celów produkcyjnych pobieraj klucze publiczne Google z punktu końcowego kluczy i przeprowadzaj weryfikację lokalnie. Identyfikator URI klucza powinien być pobrany z dokumentu Discovery przy użyciu wartości metadanych jwks_uri. Żądania do punktu końcowego debugowania mogą być ograniczane lub mogą występować błędy przejściowe.

Google rzadko zmienia klucze publiczne, dlatego możesz zapisywać je w pamięci podręcznej, używając dyrektyw HTTP HTTP. W większości przypadków przeprowadzasz lokalną weryfikację o wiele skuteczniej niż za pomocą punktu końcowego tokeninfo. Ta weryfikacja wymaga pobrania i analizy certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Jest to możliwe w przypadku dobrze zdefiniowanych bibliotek dostępnych w wielu różnych językach (zobacz jwt.io).

Uzyskiwanie informacji o profilu użytkownika

Aby uzyskać dodatkowe informacje o użytkowniku, możesz użyć tokena dostępu (który aplikacja otrzymuje podczas procesu uwierzytelniania) i standardu OpenID Connect:

  1. Aby zapewnić zgodność z identyfikatorem OpenID, w żądaniu uwierzytelniania musisz podać wartości zakresu openid profile.

    Jeśli chcesz uwzględnić adres e-mail użytkownika, możesz określić dodatkową wartość zakresu email. Aby określić zarówno profile, jak i email, możesz uwzględnić ten parametr w żądaniu URI uwierzytelnienia:

    scope=openid%20profile%20email
  2. Dodaj token dostępu do nagłówka autoryzacji i wyślij żądanie HTTPS GET do punktu końcowego informacji o użytkowniku, który należy pobrać z dokumentu Discovery za pomocą wartości metadanych userinfo_endpoint. Odpowiedź dotycząca informacji o użytkowniku zawiera informacje na temat użytkownika opisane w OpenID Connect Standard Claims i wartości metadanych claims_supported dokumentu Discovery. Użytkownicy lub ich organizacje mogą udostępniać lub wstrzymywać określone pola, więc niektóre pola mogą nie być widoczne w przypadku autoryzowanych zakresów dostępu.

Dokument Discovery

Protokół OpenID Connect wymaga używania wielu punktów końcowych do uwierzytelniania użytkowników oraz do wysyłania żądań zasobów, w tym tokenów, informacji o użytkownikach i kluczy publicznych.

Aby uprościć implementacje i zwiększyć elastyczność, OpenID Connect umożliwia korzystanie z „dokumentu Discovery” – dokumentu JSON znajdującego się w dobrze znanej lokalizacji. Para klucz-wartość zawiera szczegóły dotyczące konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokenów, unieważnień, informacji o użytkownikach i punktów końcowych kluczy publicznych. Dokument Discovery usługi Google OpenID Connect można pobrać z:

https://accounts.google.com/.well-known/openid-configuration

Aby korzystać z usług OpenID Connect Google, musisz zakodować na stałe identyfikator URI dokumentu Discovery (https://accounts.google.com/.well-known/openid-configuration) w aplikacji. Aplikacja pobiera dokument, stosuje reguły buforowania w odpowiedzi, a następnie w razie potrzeby pobiera z niego identyfikatory URI punktu końcowego. Aby na przykład uwierzytelnić użytkownika, kod pobierze wartość metadanych authorization_endpoint (w przykładzie poniżej: https://accounts.google.com/o/oauth2/v2/auth) jako podstawowy identyfikator URI żądań uwierzytelniania wysyłanych do Google.

Oto przykład dokumentu. Nazwy pól są podane w OpenID Connect Discovery 1.0 (opis znaczenia tych dokumentów). Wartości mają charakter poglądowy i mogą się zmienić, chociaż zostaną skopiowane z najnowszej wersji dokumentu Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Możesz uniknąć przesyłania danych w obie strony, buforując wartości w dokumencie Discovery. Używane są standardowe nagłówki buforowania HTTP i należy je przestrzegać.

Biblioteki klienta

Te biblioteki klienta ułatwiają wdrożenie OAuth 2.0, integrując je z popularnymi platformami:

Zgodność z OpenID Connect

System uwierzytelniania Google OAuth 2.0 obsługuje wymagane funkcje w specyfikacji OpenID Connect Core. Każdy klient, który został zaprojektowany do obsługi połączeń OpenID Connect, powinien współpracować z tą usługą (z wyjątkiem obiektu żądania OpenID).