Ta strona została przetłumaczona przez Cloud Translation API.

OpenID Connect

Interfejsy API Google OAuth 2.0 mogą być używane zarówno do uwierzytelniania, jak i uwierzytelniania. Ten dokument opisuje implementację uwierzytelniania OAuth 2.0. Jest ona zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID. Do tej usługi ma też zastosowanie dokumentacja Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google. Jeśli chcesz interaktywnie przeglądać ten protokół, zalecamy korzystanie z Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą usługi Stack Overflow, dodaj do pytań tag „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 użytkowników, musisz skonfigurować projekt w Google API Console celu uzyskania danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje o marce widoczne 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 wykonać 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 uwierzytelniających OAuth 2.0, w tym identyfikatora klienta i tajnego klucza klienta.

Aby wyświetlić identyfikator klienta i klucz tajny klienta dla danego poświadczenia OAuth 2.0, kliknij następujący tekst: Wybierz poświadczenie . W oknie, które zostanie otwarte, wybierz projekt i żądane poświadczenia, a następnie kliknij opcję Wyświetl .

Lub wyświetl swój identyfikator klienta i API Console tajny klienta ze strony Poświadczenia w API Console :

Go to the Credentials page.
Kliknij nazwę swojego poświadczenia lub ikonę ołówka ( ). Twój identyfikator klienta i sekret znajdują się u góry strony.

Ustaw identyfikator URI przekierowania

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

Aby utworzyć, wyświetlić lub edytować identyfikatory URI przekierowania dla danego poświadczenia OAuth 2.0, wykonaj następujące czynności:

Go to the Credentials page.
W sekcji identyfikatorów klientów OAuth 2.0 na stronie kliknij poświadczenie.
Wyświetl lub edytuj identyfikatory URI przekierowania.

Jeśli na stronie Poświadczenia nie ma sekcji identyfikatorów klientów OAuth 2.0 , Twój projekt nie ma poświadczeń OAuth. Aby je utworzyć, kliknij Utwórz dane logowania .

Dostosowywanie ekranu zgody użytkownika

W przypadku użytkowników uwierzytelnianie OAuth 2.0 zawiera ekran zgody, który opisuje informacje udostępniane przez użytkownika i obowiązujące warunki. Na przykład po zalogowaniu się użytkownik może zostać poproszony 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 aplikacja uwzględnia w swoim żądaniu uwierzytelniania. Aby poprosić o dostęp do innych interfejsów API Google, możesz też użyć zakresów.

Na ekranie zgody użytkownika znajdziesz także informacje o marce, takie jak nazwa produktu, logo i adres URL strony głównej. Informacje o marce możesz kontrolować w narzędziu API Console.

Aby włączyć ekran akceptacji projektu:

Otwórz Consent Screen page w Google API Console .
If prompted, select a project, or create a new one.
Wypełnij formularz i kliknij Zapisz .

Widoczne poniżej okno z prośbą o zgodę na wykorzystanie danych pokazuje, co użytkownik może zobaczyć, gdy w żądaniu występuje kombinacja zakresów OAuth 2.0 i Dysku Google. To ogólne okno zostało wygenerowane za pomocą Google Play 2.0 Playground, więc nie zawiera informacji o marce, które byłyby ustawiane w API Console.

Uzyskiwanie dostępu do usługi

Google i inne firmy udostępniają biblioteki, za pomocą których możesz dbać o wiele szczegółów implementacji uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów API Google. Przykłady obejmują usługi tożsamości Google 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 podanymi w dalszej części tego dokumentu, które opisują przepływy żądań HTTP kryjące się pod dostępnymi bibliotekami.

Uwierzytelnianie użytkownika

Uwierzytelnianie użytkownika obejmuje uzyskanie tokena tożsamości i zweryfikowanie go. Tokeny identyfikatorów to standardowa funkcja OpenID Connect przeznaczona do udostępniania potwierdzeń tożsamości w internecie.

Powszechnie stosowane metody uwierzytelniania użytkowników i uzyskiwania tokena tożsamości to proces „serwer” i „domyślny”. Przepływ serwera umożliwia serwerowi backendu aplikacji weryfikację tożsamości osoby przy użyciu przeglądarki lub urządzenia mobilnego. Przepływ domyślny jest stosowany wtedy, gdy aplikacja po stronie klienta (zazwyczaj aplikacja JavaScript działająca w przeglądarce) musi uzyskać dostęp do interfejsów API, a nie przez swój serwer.

Ten dokument opisuje, jak przeprowadzić przepływ serwera na potrzeby uwierzytelniania użytkownika. Przepływ domyślny jest znacznie bardziej skomplikowany ze względu na zagrożenia dla bezpieczeństwa obsługi i wykorzystania tokenów po stronie klienta. Jeśli chcesz wdrożyć niejawny przepływ, zdecydowanie 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:

Tworzenie tokena antyfałszerstwa
Wyślij do Google prośbę o uwierzytelnienie
Potwierdzanie tokena przeciwdziałania fałszerstwu
Giełda code dla tokena dostępu i tokena identyfikatora
Pobieranie informacji o użytkowniku z tokena tożsamości
Uwierzytelnianie użytkownika

1. Tworzenie tokena antyfałszowania

Musisz chronić bezpieczeństwo użytkowników, zapobiegając sfałszowaniu żądań. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który utrzymuje stan między aplikacją a klientem użytkownika. Później dopasowujesz ten token sesji do odpowiedzi uwierzytelniania zwróconej przez usługę logowania Google OAuth, aby sprawdzić, czy użytkownik wysyła żądanie, a nie złośliwy atakujący. Tokeny te są często nazywane tokenami fałszowania żądań z innych witryn (CSRF).

Kolejnym dobrym rozwiązaniem dla tokena stanu jest ciąg 30 znaków skonstruowany za pomocą wysokiej jakości generatora liczb losowych. Inny jest hasz wygenerowany przez podpisanie niektórych zmiennych stanu sesji za pomocą klucza, który jest utajniony w Twoim backendzie.

Ten kod pokazuje generowanie unikalnych tokenów sesji.

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google do 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 do 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 do 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. Wysyłanie do Google żądania uwierzytelniania

Następnym krokiem jest utworzenie żądania HTTPS GET z odpowiednimi parametrami identyfikatora URI. Pamiętaj, że na wszystkich etapach tego procesu używany jest protokół HTTPS zamiast HTTP. Połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint. W tej dyskusji zakładamy, ż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 Console Credentials page.
response_type, który w podstawowym żądaniu żądania kodu autoryzacji powinien mieć postać code. (Więcej informacji znajdziesz na response_type).
scope, który w podstawowym żądaniu powinien mieć wartość openid email. (Więcej informacji znajdziesz na scope).
redirect_uri powinien być punktem końcowym HTTP na Twoim serwerze, który będzie otrzymywać odpowiedź od Google. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, żądanie zakończy się błędem redirect_uri_mismatch.
state powinien zawierać wartość tokena zapobiegającego fałszowaniu wyników sesji oraz wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wróci do Twojej 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 odtworzeniem, gdy jest używana.
login_hint może być adresem e-mail użytkownika lub ciągiem sub, który odpowiada identyfikatorowi 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 z aplikacji. (Więcej informacji: login_hint)
Użyj parametru hd, aby zoptymalizować przepływ OpenID Connect dla użytkowników z określonej domeny powiązanej z organizacją Google Cloud. (Więcej informacji znajdziesz na hd).

Oto przykład pełnego identyfikatora uwierzytelniania OpenID Connect z podziałami wierszy i spacjami pod kątem czytelności:

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 Twoja aplikacja będzie prosić o nowe informacje na jej temat lub jeśli wcześniej poprosi o dostęp do konta.

3. Potwierdź token stanu fałszowania stanu

Odpowiedź jest wysyłana do redirect_uri określonego 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 sprawdzić, czy state otrzymany od Google jest zgodny z tokenem sesji utworzonym w kroku 1. Ta weryfikacja w obie strony pozwala upewnić się, że żądanie wysyła użytkownik, a nie złośliwy skrypt.

Ten kod potwierdza token sesji utworzony w kroku 1:

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google do 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 do 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 do 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 serwer może wymienić na token dostępu i token tożsamości. Serwer wykonuje tę wymianę, wysyłając żądanie HTTPS POST. Żądanie POST jest wysyłane do punktu końcowego tokena, który należy pobrać z dokumentu Discovery za pomocą wartości metadanych token_endpoint. W tej rozmowie 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 od API Console Credentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`client_secret`	Tajny klucz klienta uzyskany z API Console Credentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`redirect_uri`	Autoryzowany identyfikator URI przekierowania dla danego atrybutu `client_id` określony w zasadzie API Console Credentials page, zgodnie z opisem w artykule 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 te pola w tablicy JSON:

Pola
`access_token`	Token, który można wysłać do interfejsu API Google.
`expires_in`	Pozostały czas działania tokena dostępu w sekundach.
`id_token`	JWT zawierający informacje o tożsamości użytkownika, który jest podpisany cyfrowo przez Google.
`scope`	Zakresy dostępu przyznane przez funkcję `access_token` wyrażone w postaci listy ciągów rozdzielanych spacjami (z uwzględnieniem wielkości liter).
`token_type`	Określa typ zwróconego tokena. Obecnie to pole ma zawsze wartość `Bearer`.
`refresh_token`	(opcjonalnie) To pole występuje tylko wtedy, gdy parametr `access_type` w żądaniu uwierzytelniania został ustawiony na `offline`. Więcej informacji 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 zakodowany kryptograficznie obiekt JSON zakodowany w standardzie Base64. Standardowo kluczowe jest weryfikacja tokena tożsamości przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google za pomocą bezserwerowego kanału HTTPS i korzystasz z tajnego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token naprawdę pochodzi od Google i jest ważny. Jeśli Twój serwer przekazuje token identyfikatora do innych komponentów aplikacji, koniecznie musisz zweryfikować token przed użyciem.

Ponieważ większość bibliotek interfejsów API łączy weryfikację z pracą dekodowania wartości zakodowanych w standardzie base64url i analizowania wewnątrz pliku JSON, prawdopodobnie zakończy się weryfikacja tokena podczas uzyskiwania dostępu do roszczeń w tokenie identyfikatora.

Ł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 tożsamości Google mogą zawierać te pola (nazywane deklaracjami):

Claim	zapisana karta	Opis
`aud`	zawsze	Dla odbiorców, do których token jest przeznaczony. Musi to być jeden z identyfikatorów klienta OAuth 2.0 Twojej aplikacji.
`exp`	zawsze	Termin ważności, po którym nie można zaakceptować tokena tożsamości. Wartość podawana w czasie uniksowym (liczba całkowita).
`iat`	zawsze	Godzina wystawienia tokena. Wartość wyrażona w czasie uniksowym (liczba całkowita).
`iss`	zawsze	Identyfikator wydawcy odpowiedzi. W przypadku tokenów tożsamości Google zawsze jest to `https://accounts.google.com` lub `accounts.google.com`.
`sub`	zawsze	Identyfikator użytkownika unikalny dla wszystkich kont Google, który nigdy nie został ponownie użyty. Konto Google może mieć w różnych miejscach wiele adresów e-mail, 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 wysyłany z wartością `access_token` w procesie serwera, to roszczenie jest zawsze uwzględniane. Twierdzenie to może być alternatywnym mechanizmem do ochrony przed atakami typu fałszerstwo polegające na żądaniach z innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu.
`azp`		`client_id` autoryzowanego przedstawiciela. Ta deklaracja jest potrzebna tylko wtedy, gdy strona żądająca tokena tożsamości różni się od jego odbiorców. Może tak być w przypadku Google w przypadku aplikacji hybrydowych, gdy aplikacja internetowa i aplikacja na Androida mają inny protokół OAuth 2.0 `client_id`, ale korzystają z tego samego projektu 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. Podany tylko wtedy, gdy zakres zawiera wartość zakresu `email`.
`email_verified`		Wartość „prawda”, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie „fałsz”.
`family_name`		Imiona lub nazwiska użytkowników. Wartość może być podana, jeśli występuje roszczenie `name`.
`given_name`		Imiona lub nazwiska użytkowników. Wartość może być podana, jeśli występuje roszczenie `name`.
`hd`		Domena powiązana z organizacją użytkownika Google Cloud. Podane tylko wtedy, gdy użytkownik należy do organizacji Google Cloud.
`locale`		Ustawienia regionalne użytkownika, oznaczone tagiem języka BCP 47. Wartość może być podana, jeśli występuje roszczenie `name`.
`name`		Pełne imię i nazwisko użytkownika w formie, którą można wyświetlić. Te informacje mogą zostać podane, jeśli: Zakres żądania zawierał ciąg „profile” Token identyfikatora jest zwracany ze odświeżenia tokena Jeśli istnieją roszczenia `name`, możesz ich używać do aktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.
`nonce`		Wartość `nonce` podana przez aplikację w żądaniu uwierzytelniania. Zadbaj o ochronę przed atakami typu replay, zapewniając, że będą one wyświetlane tylko raz.
`picture`		Adres URL zdjęcia profilowego użytkownika. Te informacje mogą zostać podane, jeśli: Zakres żądania zawierał ciąg „profile” Token identyfikatora jest zwracany ze odświeżenia tokena Jeśli zgłoszono roszczenia `picture`, możesz za ich pomocą aktualizować rekordy użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.
`profile`		Adres URL strony profilu użytkownika. Te informacje mogą zostać podane, jeśli: Zakres żądania zawierał ciąg „profile” Token identyfikatora jest zwracany ze odświeżenia tokena Jeśli zgłoszono roszczenia `profile`, możesz za ich pomocą aktualizować rekordy użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.

6. Uwierzytelnianie użytkownika

Po uzyskaniu informacji o użytkownikach z tokena identyfikatora należy przesłać zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik już istnieje w Twojej bazie danych, rozpocznij sesję aplikacji dla tego użytkownika, jeśli odpowiedź interfejsu API Google spełnia wszystkie wymagania dotyczące logowania.

Jeśli użytkownika nie ma w Twojej bazie danych, musisz przekierować go do procesu rejestracji nowego użytkownika. Możesz automatycznie zarejestrować użytkownika na podstawie informacji otrzymanych od Google, a najlepiej wypełnić wstępnie wiele pól wymaganych w formularzu rejestracyjnym. Oprócz informacji z tokena tożsamości możesz też uzyskać dodatkowe informacje o profilu użytkownika w punktach końcowych profilu użytkownika.

Tematy zaawansowane

W kolejnych sekcjach szczegółowo opisano interfejs Google OAuth 2.0 API. Te informacje są przeznaczone dla deweloperów o zaawansowanych wymaganiach dotyczących uwierzytelniania i autoryzacji.

Dostęp do innych interfejsów API Google

Jedną z zalet używania protokołu OAuth 2.0 do uwierzytelniania jest to, że aplikacja może korzystać z innych interfejsów API Google w imieniu użytkownika (np. YouTube, Dysk Google, Kalendarz czy Kontakty) podczas uwierzytelniania użytkownika. Aby to zrobić, uwzględnij inne zakresy wymagane w żądaniu uwierzytelniania, który wysyłasz 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 otrzymany od Google zapewnia dostęp do wszystkich interfejsów API powiązanych z żądanymi zakresami dostępu i został przyznany.

Odśwież tokeny

W prośbie o dostęp do interfejsu API możesz poprosić o token odświeżania, który zostanie zwrócony podczas giełdy code. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy użytkownika nie ma w aplikacji. Aby poprosić o token odświeżania, w żądaniu uwierzytelniania ustaw parametr access_type na 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 podczas pierwszego procesu wymiany kodu.
Obowiązują limity publikowania tokenów odświeżania: jeden na klienta i użytkownika na wszystkie klienty. Jeśli aplikacja żąda zbyt wielu tokenów odświeżania, mogą one osiągnąć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

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

Możesz poprosić użytkownika o ponowne przyznanie uprawnień dostępu aplikacji, ustawiając w żądaniu uwierzytelniania parametr prompt na consent. Jeśli dodasz prompt=consent, ekran zgody będzie wyświetlany za każdym razem, gdy aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli Twój projekt interfejsów API Google został wcześniej przyznany. Z tego względu uwzględniaj właściwość prompt=consent tylko wtedy, gdy jest to konieczne.

Więcej informacji o parametrze prompt znajdziesz w artykule prompt w tabeli Parametry identyfikatora URI uwierzytelniania.

Parametry identyfikatora URI uwierzytelniania

W tabeli poniżej znajdziesz bardziej szczegółowe opisy parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0.

Parametr	Wymagany	Opis
`client_id`	(Wymagane)	Ciąg identyfikatora klienta uzyskany z API Console Credentials page, jak opisano w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`nonce`	(Wymagane)	Losowa wartość wygenerowana przez aplikację, która umożliwia ochronę odtwarzania ponownego.
`response_type`	(Wymagane)	Jeśli wartość to `code`, uruchamia podstawowy przepływ kodu autoryzacji, co wymaga `POST` do punktu końcowego tokenów, aby otrzymać tokeny. Jeśli wartość to `token id_token` lub `id_token token`, uruchamia domyślny proces, który wymaga użycia JavaScriptu w identyfikatorze URI przekierowania, aby pobierać tokeny z identyfikatora `#fragment` identyfikatora URI.
`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 zasadzie API Console Credentials page (w tym schemacie HTTP lub HTTPS, na końcu i na końcu znaku „/”).
`scope`	(Wymagane)	Parametr zakresu musi zaczynać się od wartości `openid`, a następnie zawierać wartość `profile`, `email` lub obie te wartości. Jeśli wartość zakresu `profile` jest obecna, token identyfikatora 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 zakresów dotyczących identyfikatora OpenID argument zakresu może też obejmować inne wartości zakresu. Wszystkie wartości zakresu muszą być rozdzielone spacjami. Jeśli na przykład chcesz, aby użytkownik miał dostęp do Dysku Google, parametr może mieć zakres `openid profile email https://www.googleapis.com/auth/drive.file`. Informacje o dostępnych zakresach znajdziesz w artykule na temat zakresów OAuth 2.0 dla interfejsów API Google lub dokumentacji interfejsu Google API, której chcesz użyć.
`state`	(Opcjonalne, ale zdecydowanie zalecane)	Nieprzezroczysty ciąg znaków, który jest w obrębie protokołu w obie strony, tzn. jest zwracany jako parametr URI w przebiegu podstawowym oraz w identyfikatorze URI `#fragment` w procesie pośrednim. Funkcja `state` może być przydatna do korelowania żądań i odpowiedzi. Ze względu na to, że element `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 Twoją aplikację. Jeśli wygenerujesz losowy ciąg lub zaszyfrujesz hasz niektórych stanów klienta (np. plików cookie) w tej zmiennej `state`, możesz zweryfikować odpowiedź, aby zyskać pewność, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami typu „fałszywe żądania z innych witryn”.
`access_type`	(Opcjonalne)	Dozwolone wartości to `offline` i `online`. Efekt można znaleźć 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. Te wartości zostały określone i zaakceptowane przez serwery Google, ale nie mają żadnego wpływu na działanie `page`, `popup`, `touch` i `wap`.
`hd`	(Opcjonalne)	Uprość proces logowania na konta należące do organizacji Google Cloud. Dołączając domenę organizacji Google Cloud (na przykład `mycollege.edu`), możesz wskazać, że interfejs wyboru konta powinien być zoptymalizowany dla kont w tej domenie. Aby zoptymalizować konta Google Cloud organizacji zazwyczaj zamiast jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki (``): `hd=`. Nie polegaj na optymalizacji interfejsu użytkownika, aby kontrolować, kto ma dostęp do Twojej aplikacji – żądania można modyfikować po stronie klienta. Pamiętaj, aby zweryfikować, że zwrócony token tożsamości ma wartość roszczenia `hd` odpowiadającą wartości, której się spodziewasz (np. `mycolledge.edu`). W przeciwieństwie do parametru żądania żądanie identyfikatora tokena `hd` znajduje się w tokenie zabezpieczeń od Google, więc tej wartości można zaufać.
`include_granted_scopes`	(Opcjonalne)	Jeśli ten parametr ma wartość `true`, a autoryzacja jest przyznawana, autoryzacja obejmuje wszelkie wcześniejsze autoryzacje przyznane tej kombinacji użytkownika i aplikacji w innych zakresach. Zapoznaj się z autoryzacją przyrostową. Pamiętaj, że w ramach procesu Zainstalowane aplikacje nie można używać autoryzacji przyrostowej.
`login_hint`	(Opcjonalne)	Gdy aplikacja wie, którego użytkownika próbuje uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Ta wskazówka pomija wybór konta i wstępnie uzupełnia pole e-mail w formularzu logowania lub wybiera odpowiednią sesję (jeśli użytkownik korzysta z funkcji 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 znaków `sub`, który odpowiada identyfikatorowi Google użytkownika.
`prompt`	(Opcjonalne)	Lista wartości ciągu rozdzielanych spacjami, która określa, 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 zgody użytkowników. 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 użyć metody `none`, aby sprawdzić obecne uwierzytelnianie lub zgodę. `consent` Serwer autoryzacji prosi użytkownika o zgodę przed zwróceniem informacji klientowi. `select_account` Serwer autoryzacji prosi użytkownika 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, na których może obecnie prowadzić sesje. Jeśli nie określono żadnej wartości, a użytkownik nie autoryzował wcześniej dostępu, użytkownik zobaczy ekran zgody.

Weryfikuję token tożsamości

Musisz zweryfikować wszystkie tokeny identyfikatora na serwerze, chyba że wiesz, że pochodzą one bezpośrednio od Google. Serwer musi na przykład zweryfikować autentyczne tokeny tożsamości, które otrzymuje z aplikacji klienckich.

Oto kilka typowych sytuacji, w których tokeny identyfikatorów można wysyłać na serwer:

Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny tożsamości informują konkretnego użytkownika wysyłającego żądanie i dla którego klienta został on przyznany.

Tokeny tożsamości są poufne i mogą zostać przechwycone, gdy zostaną przechwycone. Musisz się upewnić, że te tokeny są obsługiwane w bezpieczny sposób, przesyłając je tylko przez HTTPS i wyłącznie przez dane POST lub nagłówki żądań. Jeśli przechowujesz tokeny identyfikatorów na serwerze, musisz je też bezpiecznie przechowywać.

Tokeny tożsamości są przydatne, ponieważ możesz je przekazywać między różnymi komponentami aplikacji. Te komponenty mogą używać tokena tożsamości jako prostego mechanizmu uwierzytelniania aplikacji i użytkownika. Jednak przed użyciem informacji w tokenie identyfikatora lub poleganie na tym, że użytkownik się uwierzytelnił, musisz je zweryfikować.

Weryfikacja tokena tożsamości wymaga wykonania kilku czynności:

Sprawdź, czy token identyfikatora jest poprawnie podpisany przez wydawcę. Tokeny wydane przez Google są podpisane przy użyciu jednego z certyfikatów wymienionych w identyfikatorze URI określonych w wartości metadanych jwks_uri dokumentu Discovery.
Sprawdź, czy wartość roszczenia iss w tokenie identyfikatora jest równa https://accounts.google.com lub accounts.google.com.
Sprawdź, czy wartość żądania aud znajdującego się w tokenie identyfikatora jest taka sama jak identyfikator klienta aplikacji.
Sprawdź, czy nie upłynął jeszcze exp okresu ważności tokena tożsamości.
Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora ma właściwość hd, która pasuje do zaakceptowanej domeny powiązanej z organizacją Google Cloud.

Kroki 2–5 obejmują tylko porównania ciągów znaków i dat, co jest dość proste, więc nie będziemy tutaj ich omawiać.

Pierwszy krok jest bardziej złożony i wymaga sprawdzenia podpisu kryptograficznego. Na potrzeby debugowania możesz użyć punktu końcowego tokeninfo Google, aby porównać przetwarzanie lokalne z Twoim serwerem lub urządzeniem. Załóżmy, że wartość tokena identyfikatora to XYZ123. Następnie należy usunąć identyfikator URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jeśli podpis tokena jest prawidłowy, odpowiedź będzie ładunkiem JWT w zdekodowanym formularzu obiektu JSON.

Punkt końcowy tokeninfo przydaje się do debugowania, ale do celów produkcyjnych pobierz klucze publiczne Google z punktu końcowego kluczy i przeprowadź weryfikację lokalnie. Identyfikator URI klucza musisz pobrać z dokumentu Discovery, korzystając z wartości metadanych jwks_uri. Żądania wysyłane do punktu końcowego debugowania mogą być ograniczone lub z powodu sporadycznych błędów.

Ponieważ Google rzadko zmienia swoje klucze publiczne, możesz je buforować, używając dyrektyw pamięci podręcznej odpowiedzi 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 przeanalizowania certyfikatów oraz przeprowadzenia odpowiednich wywołań kryptograficznych, aby sprawdzić podpis. Na szczęście można z nich korzystać w szerokich bibliotekach 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 wykorzystać token dostępu (otrzymany przez aplikację podczas procesu uwierzytelniania) oraz standard OpenID Connect:

Aby zapewnić zgodność z OpenID, w żądaniu uwierzytelniania musisz uwzględnić wartości zakresu openid profile.

Jeśli chcesz uwzględnić adres e-mail użytkownika, możesz określić dodatkową wartość email. Aby określić zarówno profile, jak i email, możesz uwzględnić ten parametr w identyfikatorze URI żądania uwierzytelniania:
```
scope=openid%20profile%20email
```
Dodaj token dostępu do nagłówka autoryzacji i prześlij żądanie HTTPS GET do punktu końcowego informacji o użytkowniku. Pobierz go z dokumentu Discovery za pomocą wartości metadanych userinfo_endpoint. Odpowiedź userinfo zawiera informacje o użytkowniku, jak opisano w OpenID Connect Standard Claims i wartości metadanych claims_supported dokumentu Discovery. Użytkownicy lub ich organizacje mogą dostarczyć lub wstrzymać określone pola, więc nie uzyskasz informacji o każdym polu w przypadku autoryzowanych zakresów dostępu.

dokument Discovery.

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

Aby uprościć wdrożenia i zwiększyć elastyczność, OpenID Connect umożliwia używanie dokumentu JSON – dobrze znanego miejsca zawierającego znane pary klucz-wartość, które zawierają szczegóły konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, unieważnienia, informacje o użytkowniku i punkty końcowe 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 wykrywania (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 punktów końcowych. Na przykład w celu uwierzytelnienia użytkownika kod pobiera wartość metadanych authorization_endpoint (w poniższym przykładzie będzie to https://accounts.google.com/o/oauth2/v2/auth) jako podstawowy identyfikator URI żądań uwierzytelniania wysyłanych do Google.

Oto przykład tego dokumentu. Nazwy pól to te określone w OpenID Connect Discovery 1.0 (ich znaczenie znajdziesz w tym dokumencie). Wartości mają charakter poglądowy i mogą się zmieniać, choć są kopiowane 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. Należy używać standardowych nagłówków buforowania HTTP i należy ich przestrzegać.

Biblioteki klienta

Poniższe biblioteki klienta ułatwiają implementację protokołu OAuth 2.0 dzięki integracji z popularnymi platformami:

Zgodność OpenID Connect

System uwierzytelniania Google OAuth 2.0 obsługuje wymagane funkcje specyfikacji OpenID Connect Core. Każdy klient zaprojektowany do współpracy z OpenID Connect powinien współpracować z tą usługą (z wyjątkiem obiektu żądania OpenID).

OpenID Connect

Konfigurowanie protokołu OAuth 2.0

Uzyskiwanie danych logowania OAuth 2.0

Ustaw identyfikator URI przekierowania

Dostosowywanie ekranu zgody użytkownika

Uzyskiwanie dostępu do usługi

Uwierzytelnianie użytkownika

Przepływ serwera

1. Tworzenie tokena antyfałszowania

PHP

Java

Python

2. Wysyłanie do Google żądania uwierzytelniania

3. Potwierdź token stanu fałszowania stanu

PHP

Java

Python

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

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

Ładunek tokena tożsamości

6. Uwierzytelnianie użytkownika

Tematy zaawansowane

Dostęp do innych interfejsów API Google

Odśwież tokeny

Wysyłanie prośby o ponowną zgodę

Parametry identyfikatora URI uwierzytelniania

Weryfikuję token tożsamości

Uzyskiwanie informacji o profilu użytkownika

dokument Discovery.

Biblioteki klienta

Zgodność OpenID Connect

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