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

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.

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 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.

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 .

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.

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:

Tworzenie tokena stanu antyfałszerstwa
Wyślij do Google prośbę o uwierzytelnienie
Potwierdzanie tokena stanu fałszowania
Wymień code na token dostępu i token tożsamości
Pobieranie informacji o użytkowniku z tokena identyfikatora
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:

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.
Sprawdź, czy wartość roszczenia iss w tokenie identyfikatora wynosi https://accounts.google.com lub accounts.google.com.
Sprawdź, czy wartość roszczenia aud w tokenie identyfikatora jest równa identyfikatorowi klienta aplikacji.
Sprawdź, czy nie upłynął termin ważności (roszczenia: exp) tokena tożsamości.
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:

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
```
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).

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 stanu antyfałszerstwa

PHP

Java

Python

2. Wyślij żądanie uwierzytelniania do Google

3. Potwierdź token stanu fałszowania

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

Uzyskiwanie ponownej zgody

Parametry identyfikatora uwierzytelniania

Weryfikowanie tokena tożsamości

Uzyskiwanie informacji o profilu użytkownika

Dokument Discovery

Biblioteki klienta

Zgodność z OpenID Connect

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