Połącz OpenID

Punkt końcowy OpenID Connect firmy Google ma certyfikat OpenID.

Interfejsy API OAuth 2.0 firmy Google mogą być używane zarówno do uwierzytelniania, jak i autoryzacji. Ten dokument opisuje naszą implementację OAuth 2.0 do uwierzytelniania, która jest zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID Certified . Dokumentacja znajdująca się w artykule Korzystanie z OAuth 2.0 w celu uzyskania dostępu do interfejsów Google API również dotyczy tej usługi. Jeśli chcesz interaktywnie zapoznać się z tym protokołem, zalecamy 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 Twoja aplikacja będzie mogła używać systemu uwierzytelniania OAuth 2.0 firmy Google do logowania użytkowników, musisz skonfigurować projekt w polu Google API Console , aby uzyskać poświadczenia OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje dotyczące marki, które użytkownicy widzą w ekran zgody użytkownika. Możesz także użyć API Console , aby utworzyć konto usługi, włączyć rozliczenia, skonfigurować filtrowanie i wykonywać inne zadania. Więcej informacji można znaleźć w pomocy Google API Console .

Uzyskaj dane uwierzytelniające 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 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 :

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

Ustaw przekierowanie URI

Identyfikator URI przekierowania ustawiony w API Console określa, dokąd Google wysyła odpowiedzi na Twoje żądania uwierzytelnienia .

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 .

Dostosuj ekran zgody użytkownika

W przypadku użytkowników środowisko uwierzytelniania OAuth 2.0 obejmuje ekran akceptacji, który opisuje informacje udostępniane przez użytkownika oraz obowiązujące warunki. Na przykład, gdy użytkownik się loguje, może zostać poproszony o przyznanie aplikacji dostępu do swojego adresu e-mail i podstawowych informacji o koncie. Żądasz dostępu do tych informacji za pomocą parametru scope , który Twoja aplikacja zawiera w żądaniu uwierzytelnienia . Możesz także użyć zakresów, aby poprosić o dostęp do innych interfejsów API Google.

Ekran zgody użytkownika przedstawia również informacje dotyczące marki, takie jak nazwa produktu, logo i adres URL strony głównej. Kontrolujesz informacje dotyczące marki 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 dialogowe wyrażania zgody pokazuje, co zobaczyłby użytkownik, gdy w żądaniu występuje kombinacja zakresów OAuth 2.0 i Dysku Google. (To ogólne okno dialogowe zostało wygenerowane przy użyciu Google OAuth 2.0 Playground , więc nie zawiera informacji dotyczących marki, które zostałyby ustawione w polu API Console.)

Zrzut ekranu strony zgody

Dostęp do usługi

Google i inne firmy udostępniają biblioteki, których możesz użyć, aby zadbać o wiele szczegółów implementacji uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów Google API. Przykłady obejmują Logowanie przez Google i biblioteki klienta Google , które są dostępne dla różnych platform.

Jeśli zdecydujesz się nie używać biblioteki, postępuj zgodnie z instrukcjami w pozostałej części tego dokumentu, która opisuje przepływy żądań HTTP, które są podstawą dostępnych bibliotek.

Uwierzytelnianie użytkownika

Uwierzytelnianie użytkownika polega na uzyskaniu tokena ID i jego walidacji. Tokeny ID to ustandaryzowana funkcja OpenID Connect przeznaczona do użytku podczas udostępniania potwierdzeń tożsamości w Internecie.

Najczęściej używane podejścia do uwierzytelniania użytkownika i uzyskiwania tokenu identyfikatora są nazywane przepływem „serwer” i przepływem „niejawnym”. Przepływ serwera umożliwia serwerowi zaplecza aplikacji weryfikację tożsamości osoby za pomocą 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) musi uzyskać dostęp do interfejsów API bezpośrednio zamiast za pośrednictwem serwera zaplecza.

W tym dokumencie opisano, jak wykonać przepływ serwera w celu uwierzytelnienia użytkownika. Niejawny przepływ jest znacznie bardziej skomplikowany ze względu na zagrożenia bezpieczeństwa związane z obsługą i używaniem tokenów po stronie klienta. Jeśli musisz zaimplementować niejawny przepływ, zdecydowanie zalecamy korzystanie z logowania przez Google .

Przepływ serwera

Upewnij się, że skonfigurowałeś swoją 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ę za pomocą Google, musisz:

  1. Utwórz token stanu zapobiegający fałszowaniu
  2. Wyślij żądanie uwierzytelnienia do Google
  3. Potwierdź token stanu zapobiegający fałszowaniu
  4. code wymiany na token dostępu i token ID
  5. Uzyskaj informacje o użytkowniku z tokena ID
  6. Uwierzytelnij użytkownika

1. Utwórz token stanu zapobiegający fałszowaniu

Musisz chronić bezpieczeństwo swoich użytkowników, zapobiegając atakom polegającym na fałszowaniu żądań. Pierwszym krokiem jest utworzenie unikalnego tokenu sesji, który przechowuje stan między Twoją aplikacją a klientem użytkownika. Później dopasowujesz ten unikalny token sesji z odpowiedzią uwierzytelnienia zwróconą przez usługę logowania Google OAuth, aby sprawdzić, czy użytkownik wysyła żądanie, a nie złośliwy atakujący. Te tokeny są często nazywane tokenami CSRF (cross-site request forgery).

Dobrym wyborem dla tokena stanu jest ciąg około 30 znaków skonstruowany przy użyciu wysokiej jakości generatora liczb losowych. Innym jest hash generowany przez podpisanie niektórych zmiennych stanu sesji kluczem, który jest utrzymywany w tajemnicy na twoim zapleczu.

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

PHP

Aby użyć tego przykładu, 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
));

Jawa

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);

Pyton

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 uwierzytelnienia do Google

Kolejnym krokiem jest utworzenie żądania HTTPS GET z odpowiednimi parametrami URI. Zwróć uwagę na użycie protokołu HTTPS zamiast HTTP na wszystkich etapach tego procesu; Połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery przy użyciu 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 .

Dla podstawowego żądania określ następujące parametry:

  • client_id , który można uzyskać z API ConsoleCredentials page.
  • response_type , który w podstawowym żądaniu przepływu kodu autoryzacyjnego powinien być code . (Przeczytaj więcej w response_type .)
  • scope , który w podstawowym żądaniu powinien być openid email . (Czytaj więcej w scope .)
  • redirect_uri powinien być punktem końcowym HTTP na Twoim serwerze, który otrzyma odpowiedź od Google. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2,0 skonfigurowanego w API ConsoleCredentials page. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, żądanie zakończy się niepowodzeniem z błędem redirect_uri_mismatch .
  • state powinien zawierać wartość unikalnego tokena sesji zapobiegającej fałszerstwu, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wróci do Twojej aplikacji, np. początkowy adres URL. (Czytaj więcej w state .)
  • nonce to losowa wartość generowana przez Twoją aplikację, która włącza ochronę przed powtarzaniem, gdy jest obecna.
  • login_hint może być adresem e-mail użytkownika lub sub , który jest odpowiednikiem identyfikatora Google użytkownika. Jeśli nie podasz login_hint , a użytkownik jest aktualnie zalogowany, ekran akceptacji zawiera prośbę o zgodę na udostępnienie adresu e-mail użytkownika w Twojej aplikacji. (Przeczytaj więcej na login_hint .)
  • Użyj parametru hd , aby zoptymalizować przepływ OpenID Connect dla użytkowników określonej domeny G Suite. (Czytaj więcej na hd .)

Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect, z podziałami wierszy i spacjami zapewniającymi 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 są zobowiązani do wyrażenia zgody, jeśli aplikacja zażąda nowych informacji na ich temat lub jeśli aplikacja zażąda dostępu do konta, którego wcześniej nie zatwierdzili.

3. Potwierdź token stanu zapobiegający fałszowaniu

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

Poniższy kod ilustruje potwierdzanie tokenów sesji, które zostały utworzone w kroku 1:

PHP

Aby użyć tego przykładu, 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);
}

Jawa

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.");
}

Pyton

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. code wymiany na token dostępu i token ID

Odpowiedź zawiera parametr code , jednorazowy kod autoryzacyjny, który Twój serwer może wymienić na token dostępu i token identyfikacyjny. Twój serwer dokonuje tej wymiany, wysyłając żądanie HTTPS POST . Żądanie POST jest wysyłane do punktu końcowego tokenu, który należy pobrać z dokumentu Discovery przy użyciu wartości metadanych token_endpoint . W poniższej dyskusji przyjęto założenie, że punkt końcowy to https://oauth2.googleapis.com/token . Żądanie musi zawierać następujące parametry w treści POST :

Pola
code Kod autoryzacji zwracany z początkowego żądania .
client_id Identyfikator klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w Uzyskaj poświadczenia OAuth 2.0 .
client_secret Klucz tajny klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w sekcji Uzyskaj poświadczenia OAuth 2.0 .
redirect_uri Autoryzowany identyfikator URI przekierowania dla danego identyfikatora client_id określonego w API ConsoleCredentials page, zgodnie z opisem w Set a przekierowania URI .
grant_type To pole musi zawierać wartość authorization_code zgodnie z definicją w specyfikacji OAuth 2.0 .

Rzeczywiste żądanie może wyglądać jak w następującym przykładzie:

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 Google API.
expires_in Pozostały okres istnienia tokenu dostępu w sekundach.
id_token JWT , który zawiera informacje o tożsamości użytkownika, podpisane cyfrowo przez Google.
scope Zakresy dostępu przyznanego przez access_token wyrażone jako lista rozdzielonych spacjami ciągów z rozróżnianiem wielkości liter.
token_type Identyfikuje typ zwracanego tokena. W tej chwili to pole zawsze ma wartość Bearer .
refresh_token (opcjonalny)

To pole występuje tylko wtedy, gdy parametr access_type został ustawiony na offline w żądaniu uwierzytelnienia . Aby uzyskać szczegółowe informacje, zobacz Odśwież tokeny .

5. Uzyskaj informacje o użytkowniku z tokena ID

Identyfikator Token to JWT (JSON Web Token), czyli kryptograficznie podpisany obiekt JSON zakodowany w Base64. Zwykle bardzo ważne jest, aby zweryfikować token identyfikacyjny przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google za pośrednictwem kanału HTTPS bez pośredników i używasz tajnego klucza klienta do uwierzytelnienia się w Google, możesz mieć pewność, że token Otrzymaj naprawdę pochodzi od Google i jest ważny. Jeśli Twój serwer przekazuje token ID do innych składników Twojej aplikacji, niezwykle ważne jest, aby inne składniki weryfikowały token przed jego użyciem.

Ponieważ większość bibliotek interfejsu API łączy weryfikację z pracą polegającą na dekodowaniu wartości zakodowanych w formacie base64url i analizowaniu zawartego w nim JSON, prawdopodobnie i tak zakończysz walidację tokenu podczas uzyskiwania dostępu do oświadczeń w tokenie identyfikatora.

Ładunek tokena ID

Token ID to obiekt JSON zawierający zestaw 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 Google ID mogą zawierać następujące pola (tzw. oświadczenia ):

Prawo Pod warunkiem, że Opis
aud zawsze Odbiorcy, dla których jest przeznaczony ten token identyfikatora. Musi to być jeden z identyfikatorów klienta OAuth 2.0 Twojej aplikacji.
exp zawsze Termin ważności w dniu lub po którym token ID nie może zostać zaakceptowany. Reprezentowane w czasie uniksowym (sekundy całkowite).
iat zawsze Czas wystawienia tokena ID. Reprezentowane w czasie uniksowym (sekundy całkowite).
iss zawsze Identyfikator Emitenta dla Emitenta odpowiedzi. W przypadku tokenów identyfikatora Google zawsze https://accounts.google.com lub accounts.google.com .
sub zawsze Identyfikator użytkownika, unikalny wśród wszystkich kont Google i nigdy nie używany ponownie. 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 swojej aplikacji jako klucza unikatowego identyfikatora dla użytkownika. Maksymalna długość 255 znaków ASCII z rozróżnianiem wielkości liter.
at_hash Skrót tokena dostępu. Zapewnia weryfikację, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora zostanie wystawiony z wartością access_token w przepływie serwera, to oświadczenie jest zawsze uwzględniane. To oświadczenie może służyć jako alternatywny mechanizm ochrony przed atakami fałszowania żądań między lokacjami, ale jeśli wykonasz krok 1 i krok 3 , nie jest konieczne weryfikacja tokenu dostępu.
azp client_id autoryzowanego prezentera. To żądanie jest potrzebne tylko wtedy, gdy strona żądająca tokenu identyfikatora nie jest taka sama jak odbiorcy tokenu identyfikatora. Może tak być w przypadku Google w przypadku aplikacji hybrydowych, w których aplikacja internetowa i aplikacja na Androida mają inny identyfikator client_id OAuth 2.0, 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 Twój zakres zawiera wartość zakresu email .
email_verified Prawda, jeśli adres e-mail użytkownika został zweryfikowany; inaczej fałszywe.
family_name Nazwisko (nazwiska) lub nazwisko (nazwiska) użytkownika. Może być podany, gdy występuje żądanie name .
given_name Imię (imiona) lub imię (imiona) użytkownika. Może być podany, gdy występuje żądanie name .
hd Hostowana domena G Suite użytkownika. Dostarczane tylko wtedy, gdy użytkownik należy do domeny hostowanej.
locale Ustawienia regionalne użytkownika, reprezentowane przez znacznik języka BCP 47 . Może być podany, gdy występuje żądanie name .
name Imię i nazwisko użytkownika w formie możliwej do wyświetlenia. Może być dostarczony, gdy:
  • Zakres żądania zawierał ciąg „profil”
  • Token ID zwracany jest po odświeżeniu tokena

Jeśli są obecne oświadczenia name , możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że to twierdzenie nigdy nie jest gwarantowane.

nonce Wartość nonce przez aplikację w żądaniu uwierzytelnienia. Powinieneś wymusić ochronę przed atakami typu powtórka, zapewniając, że jest prezentowana tylko raz.
picture Adres URL zdjęcia profilowego użytkownika. Może być dostarczony, gdy:
  • Zakres żądania zawierał ciąg „profil”
  • Token ID zwracany jest po odświeżeniu tokena

Gdy istnieją oświadczenia dotyczące picture , możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że to twierdzenie nigdy nie jest gwarantowane.

profile Adres URL strony profilu użytkownika. Może być dostarczony, gdy:
  • Zakres żądania zawierał ciąg „profil”
  • Token ID zwracany jest po odświeżeniu tokena

Jeśli są obecne oświadczenia profile , możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że to twierdzenie nigdy nie jest gwarantowane.

6. Uwierzytelnij użytkownika

Po uzyskaniu informacji o użytkowniku z tokena ID należy wykonać zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik już istnieje w Twojej bazie danych, należy uruchomić 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 Twojej bazie danych użytkowników, przekieruj go do procesu rejestracji nowego użytkownika. Możesz mieć możliwość automatycznej rejestracji użytkownika na podstawie informacji otrzymanych od Google lub przynajmniej możesz być w stanie wstępnie wypełnić wiele pól wymaganych w formularzu rejestracyjnym. Oprócz informacji zawartych w tokenie ID, możesz uzyskać dodatkowe informacje o profilu użytkownika w naszych punktach końcowych profilu użytkownika.

Zaawansowane tematy

Poniższe sekcje opisują bardziej szczegółowo interfejs API Google OAuth 2.0. 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 używania protokołu OAuth 2.0 do uwierzytelniania jest to, że Twoja aplikacja może uzyskać uprawnienia do korzystania z innych interfejsów API Google w imieniu użytkownika (takich jak YouTube, Dysk Google, Kalendarz lub Kontakty) w tym samym czasie, gdy uwierzytelniasz użytkownika. Aby to zrobić, uwzględnij inne potrzebne zakresy w żądaniu uwierzytelnienia wysyłanym do Google. Na przykład, aby dodać grupę wiekową użytkownika do żądania uwierzytelnienia, przekaż parametr scope openid email https://www.googleapis.com/auth/profile.agerange.read . Użytkownik jest odpowiednio monitowany na ekranie akceptacji . Token dostępu, który otrzymujesz z powrotem od Google, umożliwia dostęp do wszystkich interfejsów API związanych z zakresami dostępu, o który prosiłeś i które zostały Ci przyznane.

Odśwież tokeny

W swoim żądaniu dostępu do interfejsu API możesz poprosić o zwrot tokena odświeżania podczas wymiany code . Token odświeżania zapewnia Twojej aplikacji ciągły dostęp do interfejsów API Google, gdy użytkownik nie jest obecny w Twojej aplikacji. Aby zażądać tokenu odświeżania, dodaj w żądaniu uwierzytelnienia parametr access_type na offline .

Rozważania:

  • Pamiętaj, aby bezpiecznie i trwale przechowywać token odświeżania, ponieważ token odświeżania można uzyskać tylko przy pierwszym wykonaniu przepływu wymiany kodu.
  • Istnieją ograniczenia liczby wydawanych tokenów odświeżania: jeden limit na kombinację klient/użytkownik i inny na użytkownika na wszystkich klientach. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, może napotkać te limity, w którym to przypadku starsze tokeny odświeżania przestaną działać.

Aby uzyskać więcej informacji, zobacz Odświeżanie tokenu dostępu (dostęp w trybie offline) .

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

Aby uzyskać więcej informacji o parametrze prompt , zobacz prompt w tabeli parametrów identyfikatora URI uwierzytelniania .

Parametry URI uwierzytelniania

Poniższa tabela zawiera pełniejsze opisy parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0 firmy Google.

Parametr Wymagany Opis
client_id (Wymagany) Ciąg identyfikatora klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w Uzyskaj poświadczenia OAuth 2.0 .
nonce (Wymagany) Losowa wartość generowana przez Twoją aplikację, która umożliwia ochronę przed powtórkami.
response_type (Wymagany) Jeśli wartością jest code , uruchamia przepływ kodu autoryzacji Basic , wymagając POST do punktu końcowego tokenu w celu uzyskania tokenów. Jeśli wartością jest token id_token lub id_token token , uruchamia przepływ niejawny , wymagający użycia JavaScript w przekierowaniu URI w celu pobrania tokenów z identyfikatora URI #fragment .
redirect_uri (Wymagany) Określa, gdzie zostanie wysłana odpowiedź. Wartość tego parametru musi dokładnie odpowiadać jednej z autoryzowanych wartości przekierowania ustawionych w API ConsoleCredentials page (w tym schematu HTTP lub HTTPS, wielkości liter i końcowego znaku „/”, jeśli istnieje).
scope (Wymagany)

Parametr scope musi zaczynać się od wartości openid , a następnie zawierać wartość profile , wartość email lub oba te elementy.

Jeśli wartość zakresu profile jest obecna, token identyfikatora może (ale nie jest gwarantowany) zawierać oświadczenia profile domyślnego użytkownika.

Jeśli wartość zakresu email jest obecna, token identyfikatora zawiera oświadczenia e- email i email_verified .

Oprócz tych zakresów specyficznych dla OpenID argument zakresu może również zawierać inne wartości zakresu. Wszystkie wartości zakresu muszą być oddzielone spacjami. Na przykład, jeśli chcesz uzyskać dostęp do poszczególnych plików na Dysku Google użytkownika, parametrem zakresu może być openid profile email https://www.googleapis.com/auth/drive.file .

Aby uzyskać informacje o dostępnych zakresach, zobacz Zakresy protokołu OAuth 2.0 dla interfejsów API Google lub dokumentację interfejsu API Google, którego chcesz użyć.

state (Opcjonalne, ale zdecydowanie zalecane)

Nieprzezroczysty ciąg, który w protokole jest przerzucany w obie strony; oznacza to, że jest zwracany jako parametr URI w przepływie podstawowym oraz w identyfikatorze URI #fragment w przepływie niejawnym.

state może być przydatny do korelowania żądań i odpowiedzi. Ponieważ Twoje redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia zainicjowanego przez Twoją aplikację. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót jakiegoś stanu klienta (np. 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ń między witrynami.

access_type (Opcjonalny) Dozwolone wartości to offline i online . Efekt jest udokumentowany w Dostępie offline ; jeśli zażądano tokenu dostępu, klient nie otrzyma tokenu odświeżania, chyba że określono wartość offline .
display (Opcjonalny) Wartość ciągu ASCII określająca sposób wyświetlania przez serwer autoryzacji stron interfejsu użytkownika uwierzytelniania i zgody. Następujące wartości są określone i akceptowane przez serwery Google, ale nie mają żadnego wpływu na jego zachowanie: page , popup , touch i wap .
hd (Opcjonalny)

Parametr hd (domena hostowana) usprawnia proces logowania na konta hostowane w G Suite. Uwzględniając domenę użytkownika G Suite (na przykład mycollege.edu ), możesz wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby zoptymalizować pod kątem kont G Suite, a nie tylko jednej domeny, ustaw wartość gwiazdki ( * ): hd=* .

Nie polegaj na tej optymalizacji interfejsu użytkownika, aby kontrolować, kto może uzyskać dostęp do Twojej aplikacji, ponieważ żądania po stronie klienta można modyfikować. Upewnij się, że zwrócony token ID ma wartość roszczenia hd , która jest zgodna z oczekiwanymi (np mycolledge.edu ) . W przeciwieństwie do parametru request, roszczenie hd token ID jest zawarte w tokenie zabezpieczającym od Google, więc można zaufać wartości.

include_granted_scopes (Opcjonalny) Jeśli w tym parametrze podano wartość true , a żądanie autoryzacji zostanie udzielone, autoryzacja będzie obejmować wszelkie wcześniejsze autoryzacje udzielone tej kombinacji użytkownika/aplikacji dla innych zakresów; zobacz Przyrostowa autoryzacja .

Pamiętaj, że nie możesz wykonać przyrostowej autoryzacji w przepływie Zainstalowana aplikacja.

login_hint (Opcjonalny) Gdy aplikacja wie, którego użytkownika próbuje uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Przekazanie tej wskazówki blokuje wybór konta i albo wstępnie wypełnia pole e-mail w formularzu logowania, albo wybiera odpowiednią sesję (jeśli użytkownik korzysta z wielokrotnego logowania ), co może pomóc w uniknięciu problemów, które mogą wystąpić, jeśli Twoja aplikacja loguje się na niewłaściwe konto użytkownika. Wartością może być adres e-mail lub sub , który jest odpowiednikiem identyfikatora Google użytkownika.
prompt (Opcjonalny) Rozdzielana spacjami lista wartości ciągu, która określa, czy serwer autoryzacji monituje użytkownika o ponowne uwierzytelnienie i zgodę. Możliwe wartości to:
  • none

    Serwer autoryzacji nie wyświetla żadnych ekranów uwierzytelniania ani zgody użytkownika; zwróci błąd, jeśli użytkownik nie jest jeszcze uwierzytelniony i nie ma wstępnie skonfigurowanej zgody dla żądanych zakresów. Nie możesz użyć none , aby sprawdzić istniejące uwierzytelnienie i/lub zgodę.

  • consent

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

  • select_account

    Serwer autoryzacji prosi użytkownika o wybranie konta użytkownika. Dzięki temu użytkownik, który ma wiele kont na serwerze autoryzacji, może wybrać spośród wielu kont, dla których może mieć bieżące sesje.

Jeśli nie określono żadnej wartości, a użytkownik nie autoryzował wcześniej dostępu, zostanie wyświetlony ekran zgody.

Walidacja tokena ID

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

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

  • Wysyłanie tokenów ID z żądaniami, które wymagają uwierzytelnienia. Tokeny ID informują o konkretnym użytkowniku składającym żądanie i dla którego klienta przyznano ten token ID.

Tokeny ID są wrażliwe i mogą być niewłaściwie użyte, jeśli zostaną przechwycone. Musisz upewnić się, że te tokeny są bezpiecznie obsługiwane, przesyłając je tylko przez HTTPS i tylko za pośrednictwem danych POST lub w nagłówkach żądań. Jeśli przechowujesz tokeny ID na swoim serwerze, musisz je również bezpiecznie przechowywać.

Jedną z rzeczy, która sprawia, że ​​tokeny ID są przydatne, jest fakt, że możesz je przekazywać między różnymi komponentami swojej aplikacji. Te składniki mogą używać tokenu identyfikatora jako lekkiego mechanizmu uwierzytelniania, który uwierzytelnia aplikację i użytkownika. Ale zanim będziesz mógł użyć informacji w tokenie ID lub polegać na nich jako asercji, że użytkownik został uwierzytelniony, musisz je zweryfikować.

Walidacja tokena ID wymaga kilku kroków:

  1. Sprawdź, czy token ID jest prawidłowo podpisany przez wystawcę. Tokeny wydane przez Google są podpisywane przy użyciu jednego z certyfikatów znalezionych w identyfikatorze URI określonym w wartości metadanych jwks_uri w dokumencie Discovery .
  2. Sprawdź, czy wartość roszczenia iss w tokenie identyfikatora jest równa https://accounts.google.com lub accounts.google.com .
  3. Sprawdź, czy wartość roszczenia aud w tokenie ID jest równa identyfikatorowi klienta Twojej aplikacji.
  4. Sprawdź, czy nie minął czas wygaśnięcia (roszczenie exp ) tokena ID.
  5. Jeśli w żądaniu określisz wartość parametru hd , sprawdź, czy token identyfikatora zawiera roszczenie hd zgodne z zaakceptowaną domeną hostowaną przez G Suite.

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

Pierwszy krok jest bardziej złożony i obejmuje sprawdzanie podpisów kryptograficznych. Do celów debugowania możesz użyć punktu końcowego tokeninfo Google, aby porównać z przetwarzaniem lokalnym zaimplementowanym na Twoim serwerze lub urządzeniu. Załóżmy, że wartość Twojego tokena ID to XYZ123 . Następnie wyłuskaj identyfikator URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Jeśli podpis tokenu jest prawidłowy, odpowiedzią będzie ładunek JWT w postaci zdekodowanego obiektu JSON.

Punkt końcowy tokeninfo jest przydatny do debugowania, ale do celów produkcyjnych należy pobrać klucze publiczne Google z punktu końcowego kluczy i przeprowadzić weryfikację lokalnie. Klucze URI należy pobrać z dokumentu Discovery, używając wartości metadanych jwks_uri . Żądania do punktu końcowego debugowania mogą być ograniczane lub w inny sposób mogą powodować sporadyczne błędy.

Ponieważ Google zmienia swoje klucze publiczne rzadko, możesz je buforować za pomocą dyrektyw pamięci podręcznej odpowiedzi HTTP i w zdecydowanej większości przypadków przeprowadzać lokalną walidację znacznie wydajniej niż przy użyciu punktu końcowego tokeninfo . Ta walidacja wymaga pobrania i przeanalizowania certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Na szczęście istnieją dobrze zdebugowane biblioteki dostępne w wielu różnych językach (zobacz jwt.io ).

Uzyskiwanie informacji o profilu użytkownika

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

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

    Jeśli chcesz, aby adres e-mail użytkownika został uwzględniony, możesz określić dodatkową wartość zakresu email . Aby określić zarówno profile , jak i adres e- email , możesz dołączyć następujący parametr do identyfikatora URI żądania uwierzytelnienia:

    scope=openid%20profile%20email
  2. Dodaj swój token dostępu do nagłówka autoryzacji i wykonaj żądanie HTTPS GET do punktu końcowego informacji o użytkowniku, które należy pobrać z dokumentu Discovery przy użyciu wartości metadanych userinfo_endpoint . Odpowiedź userinfo zawiera informacje o użytkowniku, zgodnie z opisem w OpenID Connect Standard Claims i wartość metadanych claims_supported dokumentu Discovery. Użytkownicy lub ich organizacje mogą zdecydować się na dostarczenie lub wstrzymanie niektórych pól, więc możesz nie uzyskać informacji dla każdego pola dla autoryzowanych zakresów dostępu.

Dokument odkrycia

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

Aby uprościć implementacje i zwiększyć elastyczność, OpenID Connect umożliwia korzystanie z „Discovery document”, dokumentu JSON znajdującego się w dobrze znanej lokalizacji, zawierającego pary klucz-wartość, które dostarczają szczegółowych informacji na temat konfiguracji dostawcy OpenID Connect, w tym identyfikatorów URI autoryzacji , token, odwołania, informacje o użytkowniku i punkty końcowe kluczy publicznych. Dokument Discovery dotyczący usługi OpenID Connect firmy Google można pobrać z:

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

Aby korzystać z usług OpenID Connect firmy Google, należy na stałe zakodować w aplikacji identyfikator URI dokumentu Discovery ( https://accounts.google.com/.well-known/openid-configuration ). Twoja aplikacja pobiera dokument, stosuje w odpowiedzi reguły buforowania, a następnie w razie potrzeby pobiera z niego identyfikatory URI punktów końcowych. Na przykład, aby uwierzytelnić użytkownika, Twój kod powinien pobrać wartość metadanych authorization_endpoint ( https://accounts.google.com/o/oauth2/v2/auth w poniższym przykładzie) jako podstawowy identyfikator URI dla żądań uwierzytelnienia, które są wysyłane do Google.

Oto przykład takiego dokumentu; nazwy pól są takie same, jak określone w OpenID Connect Discovery 1.0 (zapoznaj się z tym dokumentem, aby poznać ich znaczenie). Wartości mają charakter czysto ilustracyjny i mogą ulec zmianie, chociaż zostały skopiowane z najnowszej wersji aktualnego 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 być w stanie uniknąć w obie strony HTTP, buforując wartości z dokumentu Discovery. Używane są standardowe nagłówki pamięci podręcznej HTTP i należy ich przestrzegać.

Biblioteki klienta

Następujące biblioteki klienckie ułatwiają implementację OAuth 2.0 poprzez integrację z popularnymi frameworkami:

Zgodność z OpenID Connect

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