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 autoryzacji. W tym dokumencie opisano naszą implementację protokołu OAuth 2.0 na potrzeby uwierzytelniania, która jest zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID. Do tej usługi ma też zastosowanie dokumentacja o używaniu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google. Jeśli chcesz poznać ten protokół interaktywnie, zalecamy skorzystanie z Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą Stack Overflow, oznacz swoje pytania tagiem „google-oauth”.

Konfigurowanie protokołu OAuth 2.0

Zanim aplikacja będzie mogła korzystać z systemu uwierzytelniania Google OAuth 2.0 do logowania się użytkowników, musisz skonfigurować projekt w Google API Console w celu uzyskania danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje o marce widoczne dla użytkowników na ekranie zgody użytkownika. Możesz też użyć API Console do utworzenia konta usługi, włączenia płatności, skonfigurowania filtrowania i wykonania innych zadań. 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 Twoje żądania uwierzytelniania.

要创建，查看或编辑给定OAuth 2.0凭据的重定向URI，请执行以下操作：

Go to the Credentials page.
在页面的OAuth 2.0客户端ID部分中，点击一个凭据。
查看或编辑重定向URI。

如果“凭据”页面上没有OAuth 2.0客户端ID部分，则您的项目没有OAuth凭据。要创建一个，点击创建凭证 。

Dostosowywanie ekranu zgody użytkownika

Dla użytkowników funkcja uwierzytelniania OAuth 2.0 obejmuje ekran zgody z opisem informacji udostępnianych przez użytkownika oraz obowiązujących warunków. Na przykład podczas logowania 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 znajduje się w prośbie o uwierzytelnienie aplikacji. Możesz też używać zakresów, aby prosić o dostęp do innych interfejsów API Google.

Ekran zgody użytkownika zawiera też informacje dotyczące marki, takie jak nazwa produktu, logo i adres URL strony głównej. Kontrolujesz informacje o marce w API Console.

要启用项目的同意屏幕：

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

Poniższe okno z prośbą o zgodę na przetwarzanie danych osobowych pokazuje, co zobaczy użytkownik, gdy żądanie zawiera kombinację zakresów OAuth 2.0 i Dysku Google. To ogólne okno zostało wygenerowane za pomocą narzędzia Google OAuth 2.0 Playground, więc nie zawiera informacji o marce, które można było ustawić w API Console.

Zrzut ekranu strony z prośbą o zgodę na przetwarzanie danych

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 implementacji uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów API Google. Przykłady to m.in. Google Identity Services 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 dalszej części tego dokumentu, w których opisano przepływy żądań HTTP, które są dostępne w ramach dostępnych bibliotek.

Uwierzytelnianie użytkownika

Uwierzytelnienie użytkownika obejmuje uzyskanie tokena tożsamości i jego weryfikację. Tokeny tożsamości to ustandaryzowane funkcja OpenID Connect, która służy do udostępniania potwierdzeń tożsamości w internecie.

Najczęściej stosowane metody uwierzytelniania użytkownika i uzyskiwania tokena identyfikatora nazywane są przepływem „serwera” i „przepływem niejawnym”. Przepływ po stronie serwera pozwala serwerowi backendu aplikacji zweryfikować tożsamość osób korzystających z przeglądarki lub urządzenia mobilnego. Przepływ niejawny jest używany, gdy aplikacja po stronie klienta (zwykle aplikacja JavaScript działająca w przeglądarce) musi mieć bezpośredni dostęp do interfejsów API, a nie przez serwer backendu.

W tym dokumencie opisano, jak wykonać przepływ na serwerze w celu uwierzytelnienia użytkownika. Przepływ niejawny jest znacznie bardziej skomplikowany ze względu na zagrożenia dla bezpieczeństwa związane z obsługą i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć proces niejawny, zalecamy użycie usług tożsamości Google.

Przepływ serwera

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

Utwórz token służący do zapobiegania oszustwom
Wysyłanie żądania uwierzytelniania do Google
Potwierdzanie tokena stanu zapobiegania fałszowaniu
Exchange code na potrzeby tokena dostępu i tokena tożsamości
Uzyskiwanie informacji o użytkowniku za pomocą tokena tożsamości
Uwierzytelnienie użytkownika

1. Utwórz token stanu do zapobiegania fałszowaniu

Musisz chronić bezpieczeństwo użytkowników, zapobiegając atakom polegającym na sfałszowaniu żądania. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który przechowuje stan między Twoją aplikacją a klientem użytkownika. Później dopasujesz ten unikalny token sesji do odpowiedzi uwierzytelniającej zwróconej przez usługę logowania Google OAuth, aby sprawdzić, czy użytkownik wysyła żądanie, a nie złośliwe oprogramowanie. Tokeny te są często nazywane tokenami sfałszowania żądania z innych witryn (CSRF).

Dobrym wyborem w przypadku tokena stanu jest ciąg składający się z około 30 znaków utworzony za pomocą wysokiej jakości generatora liczb losowych. Kolejny to hasz wygenerowany przez podpisanie niektórych zmiennych stanu sesji kluczem, który jest tajny w zapleczu.

Poniższy kod pokazuje generowanie unikalnych tokenów sesji.

PHP

Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka 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ć tego przykładu, 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ć tego przykładu, 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

Następnym krokiem jest utworzenie żądania HTTPS GET z odpowiednimi parametrami identyfikatora URI. Zwróć uwagę, że na wszystkich etapach tego procesu jest używany protokół HTTPS zamiast HTTP, ponieważ połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint. W dalszej części prezentacji założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth.

W przypadku żądania podstawowego podaj te parametry:

client_id, które otrzymujesz z: API Console Credentials page .
response_type, który w podstawowym żądaniu przepływu kodu autoryzacji powinien mieć wartość code. (Więcej informacji znajdziesz na response_type).
scope, którego wartość w podstawowym żądaniu powinna wynosić openid email. (Więcej informacji znajdziesz na scope).
redirect_uri powinien być punktem końcowym HTTP na serwerze, który będzie otrzymywać odpowiedź od Google. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany tutaj: API Console Credentials page. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, żądanie zakończy się niepowodzeniem i zostanie wyświetlony błąd redirect_uri_mismatch.
Pole state powinno zawierać wartość unikalnego tokena sesji, który nie służy do zapobiegania oszustwom, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wraca do aplikacji, np. początkowy adres URL. (Więcej informacji znajdziesz na state).
nonce to losowa wartość generowana przez Twoją aplikację, która włącza ochronę przed ponownym odtworzeniem, jeśli jest dostępna.
login_hint może być adresem e-mail użytkownika lub ciągiem sub, który jest odpowiednikiem identyfikatora Google użytkownika. Jeśli nie podasz adresu login_hint, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zatwierdzenie zwolnienia adresu e-mail użytkownika w Twojej aplikacji. Więcej informacji: login_hint.
Parametr hd służy do optymalizacji procesu OpenID Connect dla użytkowników określonej domeny powiązanej z organizacją Google Workspace lub Cloud (więcej informacji znajdziesz na stronie hd).

Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect ze znakami podziału wiersza i spacjami, aby zwiększyć czytelność:

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 poprosi o nowe informacje lub jeśli aplikacja prosi o dostęp do konta, którego wcześniej nie zatwierdziła.

3. Potwierdź token stanu zapobiegania fałszowaniu

Odpowiedź zostanie wysł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 potwierdzić, że state otrzymany od Google jest zgodny z tokenem sesji utworzonym w kroku 1. Weryfikacja w obie strony pomaga upewnić się, że żądania wysyła użytkownik, a nie złośliwy skrypt.

Poniższy kod pokazuje potwierdzenie tokenów sesji utworzonych w kroku 1:

PHP

Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka 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ć tego przykładu, 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ć tego przykładu, 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 identyfikatora

Odpowiedź zawiera parametr code, czyli jednorazowy kod autoryzacji, który Twój serwer może wymienić na token dostępu i token identyfikatora. Serwer realizuje 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 prezentacji założono, że punkt końcowy to https://oauth2.googleapis.com/token. Żądanie musi zawierać w treści POST te parametry:

Pola
`code`	Kod autoryzacji zwracany w wyniku wstępnego żądania.
`client_id`	Identyfikator klienta otrzymany z API Console Credentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`client_secret`	Klucz klienta uzyskany z API Console Credentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`redirect_uri`	Autoryzowany identyfikator URI przekierowania do określonego zasobu `client_id`, który jest podany w API Console Credentials pagezgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania.
`grant_type`	To pole musi zawierać wartość `authorization_code` zgodnie ze specyfikacją 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 życia 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 przyznane przez zasadę `access_token` w postaci listy ciągów znaków rozdzielonych spacjami (z uwzględnieniem wielkości liter).
`token_type`	Określa typ zwracanego tokena. Obecnie to pole zawsze ma wartość `Bearer`.
`refresh_token`	(opcjonalnie) To pole występuje tylko wtedy, gdy parametr `access_type` w żądaniu uwierzytelnienia miał wartość `offline`. Szczegółowe informacje znajdziesz w sekcji Tokeny odświeżania.

5. Uzyskiwanie informacji o użytkowniku z tokena identyfikatora

Token identyfikatora to JWT (token sieciowy JSON), czyli kryptograficznie podpisany obiekt JSON zakodowany w standardzie Base64. Zazwyczaj ważne jest, aby weryfikować token tożsamości przed jego użyciem. Ponieważ jednak komunikujesz się bezpośrednio z Google przez niezależny kanał HTTPS i używasz tajnego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token faktycznie pochodzi od Google i jest prawidłowy. Jeśli serwer przekazuje token identyfikatora do innych komponentów aplikacji, bardzo ważne jest, aby pozostałe komponenty zweryfikowały token przed jego użyciem.

Większość bibliotek interfejsów API łączy weryfikację z pracą polegającą na dekodowaniu wartości zakodowanych w base64url i analizowania wewnątrz pliku JSON, więc prawdopodobnie mimo to przejdziesz do deklaracji w tokenie identyfikatora.

Ładunek tokena identyfikatora

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ć następujące pola (nazywane deklaracjami):

Claim	zapisana karta	Opis
`aud`	zawsze	Odbiorcy, dla których jest przeznaczony 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ć akceptowany. Wartość reprezentuje czas uniksowy (całkowita liczba sekund).
`iat`	zawsze	Czas wystawienia tokena tożsamości. Wartość reprezentowana w czasie uniksowym (całkowita liczba sekund).
`iss`	zawsze	Identyfikator wystawcy 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 wśród wszystkich kont Google i nigdy nieużywany. Konto Google może mieć w różnych momentach wiele adresów e-mail, ale wartość `sub` nigdy się nie zmienia. Użyj `sub` w swojej aplikacji jako unikalnego klucza identyfikatora użytkownika. Maksymalna długość to 255 znaków ASCII z uwzględnieniem wielkości liter.
`at_hash`		Hasz tokena dostępu. Sprawdza, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest wystawiany z wartością `access_token` w przepływie serwera, ta deklaracja jest zawsze uwzględniana. To zgłoszenie może być używane jako alternatywny mechanizm ochrony przed atakami polegającymi na sfałszowaniu żądania z innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu.
`azp`		`client_id` autoryzowanego prowadzącego. Ta deklaracja jest potrzebna tylko wtedy, gdy strona żądająca tokena identyfikatora nie jest taka sama jak grupa odbiorców tokena. W Google może tak być 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. Podany tylko wtedy, gdy w żądaniu uwzględniono zakres `email`. Wartość tego roszczenia może nie być unikalna dla tego konta i z czasem może się zmieniać, dlatego nie używaj tej wartości jako podstawowego identyfikatora do powiązania z Twoim wpisem użytkownika. Nie może też polegać na domenie deklaracji `email` do identyfikowania użytkowników organizacji Google Workspace lub Cloud. Zamiast tego użyj deklaracji `hd`.
`email_verified`		Wartość „prawda”, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie „false” (fałsz).
`family_name`		Nazwisko lub nazwisko użytkownika. Może być podany, gdy istnieje roszczenie `name`.
`given_name`		Imię lub nazwisko użytkownika. Może być podany, gdy istnieje roszczenie `name`.
`hd`		Domena powiązana z organizacją Google Workspace lub Cloud użytkownika. Podaje się tylko wtedy, gdy użytkownik należy do organizacji Google Cloud. Musisz zaznaczyć to deklarację, gdy ograniczasz dostęp do zasobu tylko do użytkowników z określonych domen. Brak takiego roszczenia oznacza, że konto nie należy do domeny hostowanej przez Google.
`locale`		Język użytkownika określony za pomocą tagu języka BCP 47. Może być podany, gdy istnieje roszczenie `name`.
`name`		Imię i nazwisko użytkownika w wyświetlanej formie. Może być podany, gdy: Zakres żądania zawierał ciąg „profile” Token tożsamości jest zwracany po odświeżeniu tokena Gdy dostępne są roszczenia `name`, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nie możemy zagwarantować, że to 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. Może być podany, gdy: Zakres żądania zawierał ciąg „profile” Token tożsamości jest zwracany po odświeżeniu tokena Gdy dostępne są roszczenia `picture`, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nie możemy zagwarantować, że to roszczenie się pojawi.
`profile`		Adres URL strony profilu użytkownika. Może być podany, gdy: Zakres żądania zawierał ciąg „profile” Token tożsamości jest zwracany po odświeżeniu tokena Gdy dostępne są roszczenia `profile`, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nie możemy zagwarantować, że to roszczenie się pojawi.

6. Uwierzytelnij użytkownika

Po uzyskaniu informacji o użytkowniku z tokena identyfikatora wyślij zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik już istnieje w Twojej bazie danych, rozpocznij dla niego sesję aplikacji, o ile odpowiedź interfejsu API Google spełnia wszystkie wymagania dotyczące logowania.

Jeśli użytkownika nie ma w Twojej bazie danych, musisz go przekierować do procesu rejestracji nowych użytkowników. Możesz automatycznie zarejestrować użytkownika na podstawie informacji otrzymanych od Google lub możesz wstępnie wypełnić wiele wymaganych pól w formularzu rejestracyjnym. Oprócz informacji w tokenie identyfikatora możesz uzyskać dodatkowe informacje o profilach użytkowników w punktach końcowych profilu.

Tematy zaawansowane

W sekcjach poniżej znajdziesz bardziej szczegółowe informacje o interfejsie Google OAuth 2.0 API. Te informacje są przeznaczone dla programistów z zaawansowanymi wymaganiami dotyczącymi uwierzytelniania i autoryzacji.

Dostęp do innych interfejsów API Google

Jedną z zalet stosowania protokołu OAuth 2.0 do uwierzytelniania jest to, że aplikacja może uzyskiwać uprawnienia do korzystania z innych interfejsów API Google w imieniu użytkownika (takich jak YouTube, Dysk Google, Kalendarz czy Kontakty) podczas uwierzytelniania użytkownika. Aby to zrobić, uwzględnij inne potrzebne zakresy w prośbie o uwierzytelnienie wysyłanej do Google. Aby na przykład dodać do żądania uwierzytelnienia grupę wiekową użytkownika, przekaż parametr zakresu openid email https://www.googleapis.com/auth/profile.agerange.read. Na ekranie zgody użytkownik zobaczy odpowiednią prośbę. Token dostępu, który otrzymujesz od Google, umożliwia Ci dostęp do wszystkich interfejsów API związanych z zakresami dostępu, o które prosisz i które zostały Ci przyznane.

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 nie ma użytkownika w aplikacji. Aby poprosić o token odświeżania, dodaj parametr access_type do offline w żądaniu uwierzytelnienia.

Uwagi:

Pamiętaj, by przechowywać token odświeżania w bezpieczny i trwały, ponieważ token odświeżania możesz uzyskać tylko za pierwszym razem, gdy wykonasz proces wymiany kodu.
Obowiązują limity liczby wystawionych tokenów odświeżania: jeden limit na kombinację klienta/użytkownika i jeden na użytkownika w przypadku wszystkich klientów. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, mogą zostać osiągnięte te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

Więcej informacji znajdziesz w sekcji o odświeżaniu tokena dostępu (dostęp offline).

Możesz poprosić użytkownika o ponowną autoryzację aplikacji, ustawiając parametr prompt na consent w prośbie o uwierzytelnienie. Jeśli dołączony jest prompt=consent, ekran zgody jest wyświetlany za każdym razem, gdy Twoja aplikacja żąda autoryzacji zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przyznane projektowi interfejsów API Google. Z tego powodu uwzględniaj prompt=consent tylko wtedy, gdy jest to konieczne.

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

Parametry URI uwierzytelniania

W tabeli poniżej znajdziesz pełniejszy opis parametrów akceptowanych przez interfejs Google OAuth 2.0 API.

Parametr	Wymagane	Opis
`client_id`	(Wymagane)	Ciąg identyfikatora klienta uzyskany z Credentials page API Consolezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
`nonce`	(Wymagane)	Losowa wartość generowana przez Twoją aplikację, która włącza ochronę przed ponownym odtwarzaniem.
`response_type`	(Wymagane)	Jeśli wartość to `code`, uruchamia podstawowy przepływ kodu autoryzacji, wymagający `POST` w punkcie końcowym tokena w celu uzyskania tokenów. Jeśli wartość to `token id_token` lub `id_token token`, uruchamia proces niejawny, co wymaga użycia JavaScriptu w identyfikatorze URI przekierowania w celu pobrania tokenów z identyfikatora `#fragment` identyfikatora URI.
`redirect_uri`	(Wymagane)	Określa, dokąd jest wysyłana odpowiedź. Wartość tego parametru musi być dokładnie taka sama jak jedna z wartości autoryzowanych przekierowania ustawionych w ramach funkcji API Console Credentials page (łącznie ze schematem HTTP lub HTTPS, wielkością liter oraz końcowym znakiem „/”, jeśli występuje).
`scope`	(Wymagane)	Parametr zakresu musi zaczynać się od wartości `openid`, a następnie zawierać wartość `profile`, wartość `email` lub obie te wartości. Jeśli wartość zakresu `profile` jest podana, token identyfikatora może (ale nie jest gwarantowany) zawierać domyślne żądania `profile` użytkownika. Jeśli wartość zakresu `email` jest podana, token identyfikatora zawiera żądania `email` i `email_verified`. Oprócz tych zakresów związanych z identyfikatorem OpenID argument zakresu może też zawierać inne wartości zakresów. Wszystkie wartości zakresów muszą być rozdzielone spacjami. Jeśli na przykład chcesz uzyskać dostęp do poszczególnych plików 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 na temat zakresów protokołu OAuth 2.0 dla interfejsów API Google oraz w dokumentacji interfejsu API Google, którego chcesz używać.
`state`	(Opcjonalne, ale zdecydowanie zalecane)	Nieprzejrzysty ciąg znaków, który jest zwracany w obie strony protokołu, czyli jest zwracany jako parametr URI w przepływie podstawowym oraz w identyfikatorze URI `#fragment` w przepływie niejawnym. Interfejs `state` może być przydatny do skorelowania żądań i odpowiedzi. `redirect_uri` można odgadnąć, więc użycie wartości `state` zwiększa pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia zainicjowanego przez aplikację. Jeśli wygenerujesz losowy ciąg znaków lub zakodujesz skrót jakiegoś stanu klienta (np. pliku cookie) w tej zmiennej `state`, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami, takimi jak fałszowanie żądań z innych witryn.
`access_type`	(Opcjonalne)	Dozwolone wartości to `offline` i `online`. Efekt jest opisany w sekcji Dostęp offline. Jeśli wymagane jest żądanie tokena dostępu, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość `offline`.
`display`	(Opcjonalne)	Wartość ciągu ASCII określająca sposób wyświetlania przez serwer autoryzacji stron interfejsu uwierzytelniania i prośby o zgodę na przetwarzanie danych. Te wartości są określone i akceptowane przez serwery Google, ale nie mają żadnego wpływu na ich działanie: `page`, `popup`, `touch` i `wap`.
`hd`	(Opcjonalne)	usprawnić proces logowania się na konta należące do organizacji Google Cloud; Uwzględnij domenę organizacji Google Cloud (na przykład `mycollege.edu`), aby wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby przeprowadzić optymalizację pod kątem kont organizacji w Google Cloud, a nie tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki (``): `hd=`. Nie korzystaj z tej optymalizacji UI do kontrolowania, kto może korzystać z Twojej aplikacji, ponieważ żądania po stronie klienta można modyfikować. Pamiętaj, aby validate, czy zwrócony token identyfikatora zawiera wartość żądania `hd` odpowiadającą oczekiwanej wartości (np. `mycolledge.edu`). W przeciwieństwie do parametru żądania żądanie `hd` tokena tożsamości jest zawarte w tokenie zabezpieczeń od Google, więc wartość może być godna zaufania.
`include_granted_scopes`	(Opcjonalne)	Jeśli ten parametr jest podany o wartości `true`, a żądanie autoryzacji zostanie przyznane, autoryzacja będzie obejmować wszystkie wcześniejsze autoryzacje przyznane tej kombinacji użytkownika i aplikacji na potrzeby innych zakresów. Więcej informacji znajdziesz w sekcji Autoryzacja przyrostowa. Pamiętaj, że w ramach procesu Zainstalowana aplikacja nie można przeprowadzić autoryzacji przyrostowej.
`login_hint`	(Opcjonalne)	Gdy aplikacja będzie wiedzieć, który użytkownik próbuje się uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Przekazanie tej podpowiedzi powoduje wyłączenie funkcji wyboru konta i powoduje wstępne wypełnienie pola e-mail w formularzu logowania lub wybranie odpowiedniej sesji (jeśli użytkownik korzysta z wielokrotnego logowania), co pomaga uniknąć problemów, gdy 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ągów określających, czy serwer autoryzacji prosi użytkownika o ponowne uwierzytelnienie i zgodę na przetwarzanie danych. Możliwe wartości: `none` Serwer autoryzacji nie wyświetla żadnych ekranów uwierzytelniania ani zgody użytkownika. Jeśli użytkownik nie jest jeszcze uwierzytelniony i nie ma wstępnie skonfigurowanej zgody dla żądanych zakresów, zwraca błąd. Aby sprawdzić istniejące uwierzytelnianie i uzyskiwanie zgody, możesz użyć narzędzia `none`. `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, który ma na serwerze autoryzacji wiele kont, może wybrać jedno z tych kont, dla których może mieć bieżące sesje. Jeśli nie podasz żadnej wartości, a użytkownik nie autoryzował wcześniej dostępu, wyświetli się ekran zgody.

Weryfikowanie tokena tożsamości

Musisz zweryfikować wszystkie tokeny tożsamości na swoim serwerze, chyba że wiesz, że pochodzą bezpośrednio od Google. Na przykład Twój serwer musi weryfikować jako autentyczne tokeny tożsamości, które otrzymuje z aplikacji klienckich.

Oto typowe sytuacje, w których możesz wysyłać tokeny identyfikacyjne na swój serwer:

Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny tożsamości informują o konkretnym użytkowniku wysyłającym żądanie i kliencie, któremu przyznano ten token.

Tokeny tożsamości są poufne i w przypadku ich przechwycenia mogą zostać niewłaściwie użyte. Musisz upewnić się, że te tokeny są obsługiwane w bezpieczny sposób, przesyłając je tylko przez HTTPS i tylko za pomocą danych POST lub w nagłówkach żądań. Jeśli na swoim serwerze przechowujesz tokeny tożsamości, musisz też je bezpiecznie przechowywać.

Jedną z zalet tokenów tożsamości jest możliwość przekazywania ich do różnych komponentów aplikacji. Komponenty te mogą wykorzystać token identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Zanim jednak będzie można używać informacji z tokena identyfikatora lub polegać na nich jako o uwierzytelnieniach uwierzytelnionych przez użytkownika, musisz je zweryfikować.

Weryfikacja tokena tożsamości składa się z kilku etapów:

Sprawdź, czy wydawca prawidłowo podpisał token tożsamości. Tokeny wydane przez Google są podpisane jednym z certyfikatów znalezionych w identyfikatorze URI określonym w wartości metadanych jwks_uri w dokumencie Discovery.
Sprawdź, czy wartość żądania iss w tokenie identyfikatora jest równa https://accounts.google.com lub accounts.google.com.
Sprawdź, czy wartość deklaracji aud w tokenie identyfikatora jest równa identyfikatorowi klienta Twojej aplikacji.
Sprawdź, czy termin ważności (roszczenie exp) tokena tożsamości nie minął.
Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora zawiera deklarację hd odpowiadającą akceptowanej domenie powiązanej z organizacją w Google Cloud.

Kroki 2–5 obejmują tylko porównania ciągów znaków i dat, które są dość proste, więc nie będziemy ich szczegółowo omawiać.

Pierwszy etap jest bardziej skomplikowany i obejmuje sprawdzanie podpisu kryptograficznego. Na potrzeby debugowania możesz użyć punktu końcowego tokeninfo Google, aby porównać dane z przetwarzaniem lokalnym zaimplementowanym na serwerze lub urządzeniu. Załóżmy, że wartość tokena tożsamości wynosi XYZ123. W takim przypadku należy usunąć odniesienie do identyfikatora URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jeśli podpis tokena jest prawidłowy, odpowiedzią jest ładunek JWT w formularzu zdekodowanego obiektu JSON.

Punkt końcowy tokeninfo jest przydatny do debugowania, ale w środowisku produkcyjnym pobiera klucze publiczne Google z punktu końcowego kluczy i przeprowadź weryfikację lokalnie. Identyfikator URI kluczy należy pobrać z dokumentu Discovery za pomocą wartości metadanych jwks_uri. Żądania wysyłane do punktu końcowego debugowania mogą być ograniczane lub w inny sposób mogą powodować przejściowe błędy.

Google rzadko zmienia swoje klucze publiczne, dlatego możesz je buforować, korzystając z instrukcji buforowania odpowiedzi HTTP. W większości przypadków lokalna weryfikacja przeprowadzana jest o wiele wydajniej niż przy użyciu punktu końcowego tokeninfo. Ta weryfikacja wymaga pobrania i analizy certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Aby było to możliwe, istnieją dobrze zdebugowane biblioteki w wielu różnych językach (patrz jwt.io).

Uzyskiwanie informacji o profilu użytkownika

Aby uzyskać dodatkowe informacje o profilu użytkownika, możesz użyć tokena dostępu (otrzymywanego przez aplikację podczas procesu uwierzytelniania) i standardu OpenID Connect:

Aby zapewnić zgodność z OpenID, w prośbie o uwierzytelnienie musisz uwzględnić wartości zakresu openid profile.

Jeśli chcesz, aby był uwzględniony 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 identyfikatorze URI żądania uwierzytelniania:
```
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óre musisz pobrać z dokumentu Discovery za pomocą wartości metadanych userinfo_endpoint. Odpowiedź dotycząca informacji o użytkowniku zawiera informacje o użytkowniku (zgodnie z opisem w sekcji OpenID Connect Standard Claims) i wartość metadanych claims_supported dokumentu Discovery. Użytkownicy lub ich organizacje mogą podać lub wstrzymać określone pola, więc możesz nie uzyskać informacji o niektórych polach dla autoryzowanych zakresów dostępu.

Dokument Discovery

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

W celu uproszczenia implementacji i zwiększenia elastyczności OpenID Connect pozwala na korzystanie z dokumentu Discovery – dokumentu JSON znajdującego się w dobrze znanej lokalizacji, zawierającego pary klucz-wartość zawierające szczegółowe informacje o konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokena, unieważnienia, informacje o użytkowniku i punktów końcowych kluczy publicznych. Dokument Discovery dla usługi Google OpenID Connect można pobrać z:

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

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

Oto przykład takiego dokumentu; nazwy pól są określone w OpenID Connect Discovery 1.0 (ich znaczenie znajdziesz w tym dokumencie). Wartości mają charakter czysto poglądowy i mogą się zmieniać, chociaż są kopiowane z najnowszej wersji rzeczywistego 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ąć obiegu protokołu HTTP, buforując wartości z dokumentu wykrywania. Używane są standardowe nagłówki buforowania HTTP i należy je respektować.

Biblioteki klienta

Te biblioteki klienta upraszczają implementację protokołu OAuth 2.0 dzięki integracji z popularnymi platformami:

Zgodność z OpenID Connect

System uwierzytelniania Google OAuth 2.0 obsługuje wymagane funkcje ze specyfikacji OpenID Connect Core. Każdy klient, który został zaprojektowany do działania z OpenID Connect, powinien z nią współpracować (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. Utwórz token stanu do zapobiegania fałszowaniu

PHP

Java

Python

2. Wyślij żądanie uwierzytelniania do Google

3. Potwierdź token stanu zapobiegania fałszowaniu

PHP

Java

Python

4. Wymień code na token dostępu i token identyfikatora

5. Uzyskiwanie informacji o użytkowniku z tokena identyfikatora

Ładunek tokena identyfikatora

6. Uwierzytelnij użytkownika

Tematy zaawansowane

Dostęp do innych interfejsów API Google

Odśwież tokeny

Proszenie o ponowne wyrażenie zgody

Parametry URI 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 identyfikatora