OpenID Connect

Interfejsy API Google OAuth 2.0 mogą służyć do uwierzytelniania i autoryzacji. Ten dokument opisuje implementację protokołu OAuth 2.0 na potrzeby uwierzytelniania, która jest zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID Certified. Dokumentacja dostępna w artykule Używanie protokołu OAuth 2.0 do korzystania z interfejsów API Google również ma zastosowanie do tej usługi. Jeśli chcesz interaktywnie korzystać z tego protokołu, zalecamy użycie Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą usługi Stack Overflow, oznacz swoje pytania tagiem 'google-oauth'.

Uwaga: jeśli chcesz udostępnić przycisk „Zaloguj się przez Google” dla swojej witryny lub aplikacji, zalecamy użycie Logowania przez Google, czyli biblioteki klienta do logowania opartej na protokole OpenID Connect, która udostępnia tokeny identyfikatorów w formacie OpenID Connect.

Konfigurowanie protokołu OAuth 2.0

Zanim 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 celu uzyskania danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje dotyczące marki, które użytkownicy widzą 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 uwierzytelniających OAuth 2.0, w tym identyfikatora klienta i tajnego klucza klienta.

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

1. Go to the Credentials page.
2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

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:

1. Go to the Credentials page.
2. W sekcji identyfikatorów klientów OAuth 2.0 na stronie kliknij poświadczenie.
3. 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 i obowiązujące warunki. Na przykład, gdy użytkownik się zaloguje, może zostać poproszony o przyznanie aplikacji dostępu do jej adresu e-mail oraz podstawowych informacji o koncie. Aby poprosić o dostęp do tych informacji, użyj parametru scope, który aplikacja uwzględnia w żądaniu uwierzytelnienia. Zakresy możesz też wykorzystać, by zażądać dostępu do innych interfejsów API Google.

Ekran zgody użytkownika wyświetla też informacje o marce, takie jak nazwa produktu, logo i adres URL strony głównej. Informacje o budowaniu marki możesz kontrolować w API Console.

Aby włączyć ekran akceptacji projektu:

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

Poniższe okno z prośbą o zgodę pokazuje, co użytkownik zobaczy, gdy w żądaniu występuje kombinacja zakresów OAuth 2.0 i Dysku Google. To ogólne okno zostało utworzone na podstawie aplikacji Google OAuth 2.0 Playground, więc nie zawiera informacji o marce, które można by ustawić tutaj: API Console.

Uzyskiwanie dostępu do usługi

Google i firmy zewnętrzne oferują 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 obejmują Logowanie przez Google i biblioteki klienta Google, które są dostępne na wielu platformach.

Uwaga: ze względu na bezpieczeństwo związane z prawidłowym wdrożeniem zdecydowanie zalecamy korzystanie ze gotowej biblioteki lub usługi. Poprawne uwierzytelnianie użytkowników jest ważne dla ich własnego bezpieczeństwa i bezpieczeństwa. Zazwyczaj dobrym sposobem jest użycie dobrze zdebugowanego kodu napisanego przez innych. Więcej informacji znajdziesz w artykule o bibliotekach klienta.

Jeśli nie chcesz korzystać z biblioteki, postępuj zgodnie z instrukcjami podanymi w dalszej części tego dokumentu opisującej przepływy żądań HTTP, które mieszczą się w pozostałych dostępnych bibliotekach.

Uwierzytelnianie użytkownika

Uwierzytelnianie użytkownika obejmuje uzyskanie tokena i jego weryfikację. Tokeny identyfikatora to standardowa funkcja OpenID Connect przeznaczona do udostępniania potwierdzeń tożsamości w internecie.

Najczęstsze metody uwierzytelniania użytkowników i uzyskiwania tokenów tożsamości to tzw. przepływ „serwera” i „przepływ&" niejawny”. Przepływ serwera pozwala serwerowi backendu aplikacji sprawdzać tożsamość osoby przy użyciu przeglądarki lub urządzenia mobilnego. Domniemany przepływ jest używany, gdy aplikacja po stronie klienta (zazwyczaj aplikacja JavaScript działająca w przeglądarce) musi uzyskać dostęp bezpośrednio do interfejsów API, a nie przez serwer backendu.

Ten dokument zawiera opis sposobu przeprowadzania serwera na potrzeby uwierzytelniania użytkownika. Proces niejawny jest znacznie bardziej skomplikowany ze względu na zagrożenie związane z obsługą i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć schemat bezpośredni, zalecamy użycie Logowania przez Google.

Przepływ serwera

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

1. Tworzenie tokena zapobiegającego fałszerstwu
2. Wysyłanie do Google żądania uwierzytelnienia
3. Potwierdzanie tokena stanu fałszowania
4. Wymiana tokena code na token dostępu i identyfikator
5. Uzyskiwanie informacji o użytkowniku z tokena identyfikatora
6. Uwierzytelnianie użytkownika

1. Tworzenie tokena zapobiegającego fałszerstwu

Zadbaj o bezpieczeństwo użytkowników, zapobiegając atakom polegającym na fałszowaniu żądań. 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 zweryfikować, że użytkownik wysyła żądanie, a nie złośliwy intruz. Tokeny te są często określane jako fałszowanie żądań w różnych witrynach (CSRF).

Dobrym rozwiązaniem dla tokena stanu jest ciąg składający się z co najmniej 30 znaków skonstruowanych z użyciem wysokiej jakości generatora liczb losowych. Drugim jest skrót wygenerowany przez podpisanie niektórych zmiennych stanu sesji za pomocą klucza, który jest przechowywany w tajemnicy w backendzie.

Poniższy kod ilustruje sposób generowania 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ć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla Pythona.

# 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 URI. Zwróć uwagę, że podczas wszystkich etapów tego procesu używany jest protokół HTTPS zamiast HTTP, dlatego połączenia HTTP są odrzucane. Podstawowy identyfikator URI powinien być pobrany z dokumentu opisującego za pomocą wartości metadanych authorization_endpoint. W tej dyskusji założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth.

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

• client_id uzyskany z: API ConsoleCredentials page
• response_type. W podstawowym żądaniu autoryzacji powinien znajdować się kod code. (Więcej informacji: response_type).
• scope, który w podstawowym żądaniu powinien mieć wartość openid email. (Więcej informacji znajdziesz na scope).
• redirect_uri to punkt końcowy HTTP na Twoim serwerze, który będzie otrzymywać odpowiedzi od Google. Wartość musi być zgodna z jednym z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, żądanie zakończy się niepowodzeniem i wyświetli się błąd redirect_uri_mismatch.
• state powinna zawierać wartość unikalnego tokena sesji zapobiegającego fałszerstwu, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik powraca 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 odtwarzaniem, jeśli jest dostępna.
• 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 identyfikatora login_hint, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zatwierdzenie zwolnienia adresu e-mail użytkownika z aplikacji. Więcej informacji znajdziesz na stronie login_hint.
• Parametr hd pozwala zoptymalizować przepływ OpenID OpenID dla użytkowników w określonej domenie powiązanej z organizacją Google Cloud. (Więcej informacji: hd).

Uwaga: wymienione są tylko najczęściej używane parametry. Pełną listę parametrów oraz więcej informacji o wszystkich parametrach znajdziesz w artykule Parametry identyfikatora URI uwierzytelniania.

Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect z znakami podziału wiersza i spacjami, które mają być czytelne:

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=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Użytkownicy muszą wyrazić zgodę, jeśli aplikacja prosi o nowe informacje o nich lub gdy aplikacja wymaga dostępu do konta, które nie zostało wcześniej zatwierdzone.

3. Potwierdź token stanu fałszowania

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. Taka weryfikacja w obie strony pozwala potwierdzić, że żądanie wysyła użytkownik, a nie złośliwy skrypt.

Ten kod zawiera potwierdzenie tokenów sesji utworzonych 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ć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla Pythona.

# 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 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 opisującego za pomocą wartości metadanych token_endpoint. W tej dyskusji założono, ż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 początkowego żądania.
client_id	Identyfikator klienta uzyskany z API ConsoleCredentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
client_secret	Klucz klienta uzyskany z API Console Credentials page, jak opisano w sekcji Uzyskiwanie danych logowania OAuth 2.0.
redirect_uri	Autoryzowany identyfikator przekierowania dla danego client_id określonego w API ConsoleCredentials page, jak opisano 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 Google API.
expires_in	Pozostały czas życia tokena dostępu (w sekundach).
id_token	JWT zawierający informacje o tożsamości użytkownika podpisane przez Google cyfrowo.
scope	Zakresy dostępu przyznane przez zasadę access_token wyrażoną jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter.
token_type	Określa typ zwracanego tokena. Obecnie to pole ma zawsze wartość Bearer.
refresh_token	(opcjonalnie) To pole jest obecne tylko wtedy, gdy w żądaniu uwierzytelniania parametr access_type został ustawiony na offline. Więcej informacji znajdziesz w temacie Tokeny odświeżania.

Uwaga: liczba tokenów na konto użytkownika Google jest ograniczona, a każde żądanie uwierzytelniania powyżej tego limitu może unieważnić token oczekującego odświeżenia. Szczegółowe informacje znajdziesz w sekcji Wygaśnięcie tokena.

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

Token identyfikatora jest JWT (tożsamość sieciowym JSON), czyli kryptograficznie podpisany obiekt JSON zakodowany w Base64. Zwykle konieczne jest zweryfikowanie tokena tożsamości przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google przez bezpośredni pośredni kanał HTTPS i używasz swojego tajnego 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, ważne jest, by te komponenty sprawdziły token przed jego użyciem.

Ponieważ większość bibliotek API łączy weryfikację z pracą dekodowania wartości zakodowanych w standardzie base64url i analizowania kodu JSON w końcu, prawdopodobnie i tak zakończysz weryfikację tokena, gdy uzyskasz dostęp 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 zgodnie z 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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Tokeny identyfikatora Google mogą zawierać następujące pola (nazywane roszczeniami):

Odbierz	zapisana karta	Opis
aud	zawsze	Odbiorcy, dla których przeznaczony jest 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 nie można zaakceptować tokena tożsamości. Wartość w czasie uniksowym (łączna liczba sekund).
iat	zawsze	Godzina wydania tokena tożsamości. Wartość w czasie uniksowym (łączna liczba sekund).
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 momentach wiele adresów e-mail, ale wartość sub nigdy się nie zmienia. Użyj klucza sub w swojej aplikacji jako klucza unikalnego identyfikatora użytkownika. Maksymalna długość: 255 znaków ASCII (wielkość liter ma znaczenie).
at_hash		Hasz tokena dostępu. Zapewnia weryfikację, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest wydawany z wartością access_token w przepływie serwera, to roszczenie zawsze jest dołączane. Twierdzenia można używać jako alternatywnego mechanizmu do ochrony przed atakami fałszerskimi pochodzącymi z różnych 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. Tak może być w 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. Podawana tylko wtedy, gdy zakres zawiera wartość zakresu email.
email_verified		TRUE, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie ma wartość Fałsz.
family_name		Nazwisko lub nazwisko użytkownika. Ten atrybut można podać, jeśli istnieje roszczenie name.
given_name		Imię i nazwisko użytkownika. Ten atrybut można podać, jeśli istnieje roszczenie name.
hd		Domena powiązana z organizacją Google Cloud użytkownika. Podawane tylko wtedy, gdy użytkownik należy do organizacji Google Cloud.
locale		Region użytkownika reprezentowany przez tag języka BCP 47. Ten atrybut można podać, jeśli istnieje roszczenie name.
name		Pełne imię i nazwisko użytkownika w wyświetlanej formie. Może być podawana, gdy: Zakres żądania zawierał ciąg "profile" Token identyfikatora jest zwracany z odświeżenia tokena Jeśli masz name roszczeń, możesz użyć ich do zaktualizowania rekordów użytkownika aplikacji. Uwaga: nigdy nie gwarantujemy, że roszczenie zostanie zgłoszone.
nonce		Wartość obiektu 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ć podawana, gdy: Zakres żądania zawierał ciąg "profile" Token identyfikatora jest zwracany z odświeżenia tokena Jeśli dostępne są roszczenia picture, możesz ich użyć do zaktualizowania rekordów użytkownika aplikacji. Uwaga: nigdy nie gwarantujemy, że roszczenie zostanie zgłoszone.
profile		Adres URL strony profilu użytkownika. Może być podawana, gdy: Zakres żądania zawierał ciąg "profile" Token identyfikatora jest zwracany z odświeżenia tokena Jeśli dostępne są roszczenia profile, możesz ich użyć do zaktualizowania rekordów użytkownika aplikacji. Uwaga: nigdy nie gwarantujemy, że roszczenie zostanie zgłoszone.

6. Uwierzytelnianie użytkownika

Po uzyskaniu od użytkownika identyfikatora użytkownika prześlij zapytanie do bazy danych aplikacji. Jeśli użytkownik już istnieje w Twojej bazie danych, rozpocznij sesję aplikacji dla tego użytkownika, jeśli wszystkie odpowiedzi na wymagania logowania są spełnione przez interfejs API Google.

Jeśli użytkownika nie ma w bazie danych, musisz przekierować go do nowego procesu rejestracji. Możesz mieć możliwość automatycznego zarejestrowania użytkownika na podstawie informacji otrzymanych od Google, ale możesz też mieć możliwość wypełnienia wstępnie kilku pól wymaganych w formularzu rejestracyjnym. Oprócz informacji z tokenu identyfikatora możesz uzyskać dodatkowe informacje z profilu użytkownika w naszych punktach końcowych profilu użytkownika.

Tematy zaawansowane

W poniższych sekcjach znajdziesz szczegółowy opis interfejsu Google OAuth 2.0 API. Te informacje są przeznaczone dla programistów o zaawansowanych wymaganiach dotyczących uwierzytelniania i autoryzacji.

Dostęp do innych interfejsów API Google

Jedną z zalet OAuth 2.0 jest to, że aplikacja może korzystać z uprawnień do korzystania z innych interfejsów Google API w imieniu użytkownika (np. YouTube, Dysku Google, Kalendarza lub Kontaktów) podczas uwierzytelniania użytkownika. Aby to zrobić, dołącz inne zakresy, których potrzebujesz, w żądaniu uwierzytelniania wysyłanym do Google. Aby na przykład dodać grupę wiekową użytkowników do żądania uwierzytelniania, 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, umożliwia dostęp do wszystkich interfejsów API powiązanych z zakresami dostępu, o które prosisz i których przyznano.

Uwaga: jeśli aplikacja prosi o wiele zakresów, ekran zgody zawiera wiele wierszy tekstu. Im więcej zakresów prosi Twoja aplikacja, tym mniejsze jest prawdopodobieństwo, że użytkownik ją zaakceptuje – aplikacja powinna prosić tylko o zakresy, których potrzebuje.

Odśwież tokeny

W swojej prośbie o dostęp do interfejsu API możesz poprosić o token odświeżania zwracany podczas giełdy code. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy użytkownik nie jest obecny w aplikacji. Aby poprosić o token odświeżania, dodaj parametr access_type do offline w żądaniu uwierzytelniania.

Uwagi:

• Pamiętaj, że token odświeżania musi być bezpiecznie i na stałe przechowywany, ponieważ token odświeżania można uzyskać tylko po pierwszym uruchomieniu wymiany kodu.
• Obowiązują limity liczby tokenów odświeżania: jeden dla danej kombinacji klienta i użytkownika oraz jeden dla każdego użytkownika. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, może to spowodować przekroczenie tych limitów. W takim przypadku starsze tokeny odświeżania przestaną działać.

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

Ponowna prośba o zgodę

Możesz poprosić użytkownika o ponowne uwierzytelnienie aplikacji, ustawiając parametr prompt na consent w żądaniu uwierzytelniania. Po uwzględnieniu właściwości prompt=consent ekran zgody będzie wyświetlany za każdym razem, gdy aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przydzielone do projektu interfejsów API Google. Z tego względu właściwość prompt=consent powinna być stosowana tylko wtedy, gdy jest to konieczne.

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

Parametry URI uwierzytelniania

Tabela poniżej zawiera bardziej szczegółowy opis parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0.

Parametr	Wymagane	Opis
client_id	(wymagane)	Ciąg identyfikatora klienta uzyskany z API Console Credentials 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 odtworzeniem.
response_type	(wymagane)	Jeśli wartość to code, uruchamia się proces podstawowego 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, uruchamiany jest przepływ domyślny, który wymaga użycia JavaScriptu 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 API ConsoleCredentials page (w tym schemacie HTTP lub HTTPS, na końcu oraz '/&#39, jeśli występują).
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 występuje wartość zakresu profile, token identyfikatora może (ale nie musi) uwzględniać domyślnych roszczeń profile użytkownika. Jeśli występuje wartość zakresu email, token identyfikatora zawiera roszczenia email i email_verified. Oprócz zakresów typowych dla identyfikatora OpenID Twój argument zakresu może też zawierać inne wartości zakresu. Wszystkie wartości zakresu muszą być rozdzielone spacjami. Jeśli na przykład chcesz uzyskać 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 zakresach OAuth 2.0 dla interfejsów API Google oraz dokumentacji interfejsu Google API, której chcesz używać.
state	(Opcjonalne, ale zdecydowanie zalecane)	Nieprzezroczysty ciąg znaków w protokole, czyli zwracany jako parametr URI w przepływie podstawowym i identyfikatorze URI #fragment w przepływie podstawowym. Wartość state może być przydatna do korelowania żądań i odpowiedzi. Odgadnięcie wartości właściwości redirect_uri pozwala zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania zainicjowanego przez Twoją aplikację. Jeśli wygenerujesz losowy ciąg znaków lub zakodujesz hasz niektórych stanów klienta (np. pliku cookie) w tej zmiennej state, możesz sprawdzić odpowiedź, aby upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami takimi jak fałszowanie żądań pochodzących z innych stron.
access_type	(Opcjonalnie)	Dozwolone wartości to offline i online. Efektem jest dostęp offline. Jeśli żądany jest token dostępu, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość offline.
display	(Opcjonalnie)	Wartość ciągu znaków ASCII określająca sposób wyświetlania stron uwierzytelniania i uzyskiwania zgody przez serwer autoryzacji. Te wartości są określone i akceptowane przez serwery Google, ale nie mają żadnego wpływu na działanie tych usług: page, popup, touch i wap.
hd	(Opcjonalnie)	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 pod kątem kont w tej domenie. Aby przeprowadzić optymalizację pod kątem kont organizacji w Google Cloud, zamiast tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki (*): hd=*. Nie polegaj na optymalizacji interfejsu, aby mieć kontrolę nad tym, kto może korzystać z Twojej aplikacji – w przeciwnym razie żądania po stronie klienta mogą być modyfikowane. Pamiętaj, aby sprawdzić, czy zwrócony token tożsamości ma wartość roszczenia hd zgodną z oczekiwaniami (np. mycolledge.edu). W przeciwieństwie do parametru żądania żądanie identyfikatora tokena hd znajduje się w tokenie zabezpieczeń Google, więc wartość może być zaufana.
include_granted_scopes	(Opcjonalnie)	Jeśli ten parametr ma wartość true i prośba o autoryzację zostanie przyjęta, autoryzacja obejmuje wszystkie wcześniejsze autoryzacje przyznane tej kombinacji użytkownika i aplikacji w innych zakresach. Zobacz Dodatkowa autoryzacja. Pamiętaj, że w procesie instalacji aplikacji nie można przeprowadzić przyrostowej autoryzacji.
login_hint	(Opcjonalnie)	Jeśli aplikacja wie, jakiego użytkownika próbuje uwierzytelnić, może dostarczyć ten parametr jako wskazówkę dla serwera uwierzytelniania. Zapisanie tej wskazówki powoduje wyłączenie selektora kont i wstępne wypełnienie pola e-maila w formularzu logowania lub wybranie właściwej sesji (jeśli użytkownik korzysta z wielokrotnego logowania). Pozwala to uniknąć problemów, które występują, 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 odpowiada identyfikatorowi Google użytkownika.
prompt	(Opcjonalnie)	Lista rozdzielonych spacjami wartości ciągów, która określa, czy serwer autoryzacji prosi użytkownika o ponowne uwierzytelnienie i wyrażenie zgody. Możliwe wartości: none Serwer autoryzacji nie wyświetla żadnych ekranów uwierzytelniania ani zgód użytkowników. Jeśli użytkownik nie jest jeszcze uwierzytelniony i nie ma wstępnie skonfigurowanej zgody dla żądanych zakresów, zostanie zwrócony błąd. Aby sprawdzić istniejące uwierzytelnianie lub zgodę, możesz użyć none. consent Serwer autoryzacyjny prosi użytkownika o zgodę przed zwróceniem informacji do klienta. select_account Serwer autoryzacji wyświetla użytkownikowi prośbę o wybranie konta użytkownika. Dzięki temu użytkownik, który ma wiele kont na serwerze autoryzacji, może wybierać spośród wielu kont, z których mogą korzystać bieżące sesje. Jeśli nie określono żadnej wartości, a użytkownik nie autoryzował wcześniej dostępu, użytkownik zobaczy ekran zgody.

Weryfikowanie tokena tożsamości

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

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

• Wysyłam tokeny tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny identyfikatora informują o konkretnym użytkowniku wysyłającym żądanie i o tym kliencie, któremu został on przyznany.

Tokeny tożsamości są poufne i mogą zostać wykorzystane w razie ich przechwycenia. Musisz się upewnić, że te tokeny są obsługiwane bezpiecznie, przesyłając je tylko przez HTTPS i tylko przez dane POST lub w nagłówkach żądań. Jeśli przechowujesz tokeny identyfikatorów na serwerze, musisz je bezpiecznie przechowywać.

Jedną z przydatności tokenów tożsamości jest to, że możesz je przekazywać między różnymi komponentami aplikacji. Te komponenty mogą używać tokena tożsamości jako lekkiego mechanizmu uwierzytelniania, który uwierzytelnia aplikację i użytkownika. Zanim jednak użyjesz informacji w tokenie identyfikatora lub użyjesz go jako potwierdzenia, że użytkownik uwierzytelnił się, musisz je zweryfikować.

Weryfikacja tokena tożsamości obejmuje kilka etapów:

1. Sprawdź, czy wydawca dokumentu tożsamości został prawidłowo podpisany. Tokeny wydane przez Google są podpisane jednym z certyfikatów wymienionych w identyfikatorze URI podanym w wartości metadanych jwks_uri dokumentu opisującego.
2. Sprawdź, czy wartość roszczenia iss w tokenie identyfikatora jest równa https://accounts.google.com lub accounts.google.com.
3. Sprawdź, czy wartość żądania aud w tokenie identyfikatora jest równa identyfikatorowi klienta aplikacji.
4. Sprawdź, czy czas wygaśnięcia tokena tożsamości (exp) nie minął.
5. Jeśli w żądaniu określono wartość parametr hd, sprawdź, czy token identyfikatora ma deklarację hd odpowiadającą akceptowanej domenie powiązanej z organizacją Google Cloud.

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

Pierwszy krok jest bardziej złożony i wymaga weryfikacji podpisu kryptograficznego. Na potrzeby debugowania możesz użyć punktu końcowego tokeninfo Google+ do porównania z przetwarzaniem lokalnym wdrożonym na serwerze lub urządzeniu. Załóżmy, że token 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 ładunek JWT w jego zdekodowanej postaci 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 opisującego, korzystając z wartości metadanych jwks_uri. Żądania do punktu końcowego debugowania mogą być ograniczane lub mogą w niektórych przypadkach występować sporadyczne błędy.

Google rzadko aktualizuje swoje klucze publiczne, dlatego możesz je zapisywać w pamięci podręcznej, używając instrukcji HTTP dotyczących pamięci podręcznej. W większości przypadków przeprowadzasz lokalną weryfikację znacznie skuteczniej niż za pomocą punktu końcowego tokeninfo. Ta weryfikacja wymaga pobrania i przeanalizowania certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Na szczęście dostępne są dobrze wyedytowane biblioteki w wielu różnych językach (zobacz jwt.io).

Uzyskiwanie informacji z profilu użytkownika

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

1. Aby zachować zgodność z identyfikatorem 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ść zakresu email. Aby określić zarówno profile, jak i email, możesz uwzględnić ten parametr w żądaniu URI uwierzytelniania:

   scope=openid%20profile%20email

2. Dodaj token dostępu do nagłówka autoryzacji i wyślij żądanie HTTPS GET do punktu końcowego informacji użytkownika. Informacje te należy pobrać z dokumentu opisującego za pomocą wartości metadanych userinfo_endpoint. Odpowiedź z informacjami o użytkowniku zawiera informacje o użytkowniku zgodnie z opisem w OpenID Connect Standard Claims i wartości metadanych claims_supported dokumentu Discovery. Użytkownicy i ich organizacje mogą udostępniać lub blokować określone pola, więc możesz nie zobaczyć informacji o poszczególnych polach dotyczących autoryzowanych zakresów dostępu.

dokument Discovery.

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

Aby uprościć implementację i zwiększyć elastyczność, OpenID Connect umożliwia korzystanie z dokumentu „Discovery” w dobrze znanej lokalizacji z parami klucz-wartość, które zawierają szczegóły konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokena, unieważnienia, informacji o użytkowniku i punktów końcowych kluczy. 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 OpenID Connect Google, musisz zakodować na stałe identyfikator URI dokumentu wykrywania (https://accounts.google.com/.well-known/openid-configuration) w swojej aplikacji. Aplikacja pobiera dokument, stosuje reguły przechowywania 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 (https://accounts.google.com/o/oauth2/v2/auth w przykładzie poniżej) jako podstawowy identyfikator URI wysyłanego do Google żądania uwierzytelniania.

Oto przykład tego dokumentu. Nazwy pól są zgodne z nazwami podanymi w artykule OpenID Connect Discovery 1.0 (odnieś się do ich znaczenia). Wartości są tylko przykładami i mogą się zmienić, chociaż są skopiowane 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 zapobiec przepływowi danych w obie strony, buforując wartości z dokumentu Discovery. Standardowe nagłówki HTTP z pamięci podręcznej są używane i należy ich przestrzegać.

Biblioteki klienta

Te biblioteki klienta ułatwiają wdrażanie protokołu OAuth 2.0 dzięki integracji z popularnymi platformami:

• Biblioteka klienta interfejsów API Google dla języka Java
• Biblioteka klienta interfejsów API Google dla Pythona
• Biblioteka klienta interfejsów API Google dla domeny .NET
• Biblioteka klienta interfejsów API Google dla języka Ruby
• Biblioteka klienta interfejsów API Google dla PHP
• Biblioteka OAuth 2.0 na potrzeby Narzędzi internetowych Google
• Kontrolery Zestawu narzędzi Google OAuth 2.0 dla Zestawu narzędzi Google

Zgodność z OpenID Connect

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