OpenID Connect

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

Interfejsów API Google OAuth 2.0 można używać zarówno do uwierzytelniania, jak i do autoryzacji. Ten dokument opisuje naszą implementację OAuth 2.0 do uwierzytelniania, która jest zgodna ze specyfikacją OpenID Connect i posiada certyfikat OpenID . Dokumentacja znajdująca się w artykule Używanie OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google dotyczy również tej usługi. Jeśli chcesz interaktywnie poznać ten protokół, zalecamy Google OAuth 2.0 Playground . Aby uzyskać pomoc dotyczącą przepełnienia stosu , oznacz swoje pytania tagiem „google-oauth”.

Konfigurowanie OAuth 2.0

Zanim Twoja aplikacja będzie mogła używać systemu uwierzytelniania Google OAuth 2.0 do logowania użytkowników, musisz skonfigurować projekt w Google API Console, aby uzyskać poświadczenia OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje o marce, które Twoi użytkownicy widzą na koncie użytkownika. ekran akceptacji. Możesz również 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 poświadczenia OAuth 2.0

Potrzebujesz danych logowania OAuth 2.0, w tym identyfikatora klienta i klucza tajnego, aby uwierzytelniać użytkowników i uzyskiwać dostęp do interfejsów API Google.

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 identyfikator URI przekierowania

Identyfikator URI przekierowania ustawiony w API Console określa, gdzie 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, które użytkownik udostępnia, oraz obowiązujące warunki. Na przykład, gdy użytkownik się loguje, może zostać poproszony o udzielenie aplikacji dostępu do jego adresu e-mail i podstawowych informacji o koncie. Żądasz dostępu do tych informacji przy użyciu parametru scope , który aplikacja zawiera w żądaniu uwierzytelnienia . Możesz także użyć zakresów, aby zażądać dostępu do innych interfejsów API Google.

Ekran zgody użytkownika zawiera również informacje dotyczące marki, takie jak nazwa produktu, logo i adres URL strony głównej. Masz kontrolę nad informacjami dotyczącymi marki w pliku 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 pokazuje, co zobaczy użytkownik, gdy w żądaniu znajduje się 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 o marce, które byłyby ustawione w API Console.)

Zrzut ekranu strony zgody

Dostęp do usługi

Google i firmy zewnętrzne udostępniają biblioteki, których można użyć do zadbania o wiele szczegółów implementacyjnych związanych z uwierzytelnianiem użytkowników i uzyskiwaniem dostępu do interfejsów API Google. Przykłady obejmują logowanie przez Google i biblioteki klienckie 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, w których opisano przepływy żądań HTTP, które dotyczą dostępnych bibliotek.

Uwierzytelnianie użytkownika

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

Najpowszechniej stosowane podejścia do uwierzytelniania użytkownika i uzyskiwania tokena identyfikatora są nazywane przepływem „serwera” 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. Niejawny przepływ jest używany, gdy aplikacja po stronie klienta (zwykle aplikacja JavaScript działająca w przeglądarce) musi uzyskać dostęp do interfejsów API bezpośrednio, a nie 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 uwierzytelniania użytkowników. Gdy użytkownik próbuje zalogować się w 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. Wymień code na token dostępu i token identyfikacyjny
  5. Uzyskaj informacje o użytkowniku z tokenu 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 aplikacją a klientem użytkownika. Później dopasowujesz ten unikalny token sesji do odpowiedzi uwierzytelniającej zwróconej przez usługę Google OAuth Login, aby sprawdzić, czy to użytkownik wysyła żądanie, a nie złośliwy atakujący. Te tokeny są często nazywane tokenami fałszowania żądań między lokacjami ( CSRF ).

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

Poniższy kod ilustruje generowanie unikatowych tokenów sesji.

PHP

Aby skorzystać z 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
));

Jawa

Aby skorzystać z 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

Następnym 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 wykrywania przy użyciu wartości metadanych authorization_endpoint końcowego. Poniższa dyskusja zakłada, że ​​podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth .

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

  • client_id , który można uzyskać z pliku API Console Credentials page.
  • response_type , który w żądaniu przepływu kodu autoryzacji podstawowej powinien być code . (Przeczytaj więcej na response_type .)
  • scope , którym w podstawowym żądaniu powinien być openid email . (Przeczytaj więcej w scope .)
  • redirect_uri powinno 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, który został skonfigurowany w API Console Credentials 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 chroniącego przed fałszerstwem, a także wszelkie inne informacje potrzebne do odtworzenia kontekstu, gdy użytkownik powraca do aplikacji, np. początkowy adres URL. (Czytaj więcej w state .)
  • nonce to losowa wartość generowana przez Twoją aplikację, która umożliwia ochronę powtórek, jeśli jest obecna.
  • 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 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. (Przeczytaj więcej w 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 jakichkolwiek nowych informacji na ich temat lub 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 demonstruje potwierdzenie tokenów sesji utworzonych w kroku 1:

PHP

Aby skorzystać z 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);
}

Jawa

Aby skorzystać z 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. Wymień code na token dostępu i token identyfikacyjny

Odpowiedź zawiera parametr code , jednorazowy kod autoryzacji, który serwer może wymienić na token dostępu i token identyfikatora. 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 wykrywania przy użyciu wartości metadanych token_endpoint . Poniższa dyskusja zakłada, ż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, który jest zwracany z pierwotnego żądania .
client_id Identyfikator klienta uzyskany z API Console Credentials page, zgodnie z opisem w sekcji Uzyskiwanie poświadczeń OAuth 2.0 .
client_secret Klucz tajny klienta uzyskany z API Console Credentials page, zgodnie z opisem w sekcji Uzyskiwanie poświadczeń OAuth 2.0 .
redirect_uri Autoryzowany identyfikator URI przekierowania dla danego client_id określony w API Console Credentials page, zgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania .
grant_type To pole musi zawierać wartość authorization_code zdefiniowaną w specyfikacji OAuth 2.0 .

Rzeczywiste żądanie może wyglądać następująco:

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 Token JWT zawierający informacje o tożsamości użytkownika, który jest podpisany cyfrowo przez Google.
scope Zakresy dostępu przyznane przez access_token wyrażone jako lista ciągów rozdzielanych spacjami z rozróżnianiem wielkości liter.
token_type Identyfikuje typ zwróconego tokenu. W tej chwili to pole ma zawsze wartość Bearer .
refresh_token (opcjonalny)

To pole jest obecne tylko wtedy, gdy parametr access_type został ustawiony na offline w żądaniu uwierzytelnienia . Aby uzyskać szczegółowe informacje, zobacz Odświeżanie tokenów .

5. Uzyskaj informacje o użytkowniku z tokenu ID

Identyfikator token to JWT (JSON Web Token), czyli podpisany kryptograficznie obiekt JSON zakodowany w standardzie Base64. Zwykle ważne jest, aby zweryfikować token identyfikatora przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google przez kanał HTTPS wolny od pośredników i używasz tajnego klucza klienta do uwierzytelnienia się w Google, możesz być pewien Otrzymać naprawdę pochodzi od Google i jest ważny. Jeśli serwer przekazuje token identyfikatora do innych składników aplikacji, niezwykle ważne jest, aby inne składniki zweryfikowały token przed jego użyciem.

Ponieważ większość bibliotek API łączy walidację z pracą polegającą na dekodowaniu wartości zakodowanych w base64url i analizowaniu kodu JSON, prawdopodobnie i tak zakończysz walidację tokenu, gdy uzyskasz dostęp do oświadczeń w tokenie identyfikatora.

Ładunek tokena identyfikatora

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 identyfikacyjne Google mogą zawierać następujące pola (zwane oświadczeniami ):

Roszczenie Opatrzony 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 Czas wygaśnięcia w dniu lub po którym token ID nie może zostać zaakceptowany. Przedstawione w czasie uniksowym (sekundy całkowite).
iat zawsze Czas wystawienia tokena identyfikatora. Przedstawione w czasie uniksowym (sekundy całkowite).
iss zawsze Identyfikator emitenta dla emitenta odpowiedzi. Zawsze https://accounts.google.com lub accounts.google.com przypadku tokenów Google ID.
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 użytkownika. Maksymalna długość 255 znaków ASCII z uwzględnieniem wielkości liter.
at_hash Skrót tokenu dostępu. Zapewnia weryfikację, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest wystawiony z wartością access_token w przepływie serwera, to żądanie jest zawsze uwzględniane. To oświadczenie może służyć jako alternatywny mechanizm do ochrony przed atakami polegającymi na fałszowaniu żądań między lokacjami, ale jeśli wykonasz kroki 1 i 3 , weryfikacja tokenu dostępu nie jest konieczna.
azp client_id autoryzowanego prezentera. To żądanie jest potrzebne tylko wtedy, gdy strona żądająca tokenu identyfikatora nie jest tym samym, co odbiorca 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 protokołu OAuth 2.0, ale mają ten sam projekt interfejsów API Google.
email Adres e-mail użytkownika. Ta wartość może nie być unikatowa dla tego użytkownika i nie nadaje się do użytku jako klucz podstawowy. Podawany tylko wtedy, gdy zakres obejmuje wartość zakresu email .
email_verified Prawda, jeśli adres e-mail użytkownika został zweryfikowany; w przeciwnym razie fałszywe.
family_name Nazwisko (a) lub nazwisko (a) użytkownika. Można podać, gdy występuje roszczenie dotyczące name .
given_name Imię (imiona) lub imię (imiona) użytkownika. Można podać, gdy występuje roszczenie dotyczące name .
hd Hostowana domena G Suite użytkownika. Podawany tylko wtedy, gdy użytkownik należy do domeny hostowanej.
locale Ustawienia regionalne użytkownika reprezentowane przez znacznik języka BCP 47 . Można podać, gdy występuje roszczenie dotyczące name .
name Imię i nazwisko użytkownika w wyświetlanej formie. Może być dostarczony, gdy:
  • Zakres żądania obejmował ciąg „profil”
  • Token ID jest zwracany po odświeżeniu tokenu

W przypadku stwierdzenia name można ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że to roszczenie nigdy nie jest gwarantowane.

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

W przypadku roszczeń do picture można ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że to roszczenie nigdy nie jest gwarantowane.

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

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

6. Uwierzytelnij użytkownika

Po uzyskaniu informacji o użytkowniku z tokenu identyfikatora należy wysłać zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik już istnieje w bazie danych, należy rozpocząć sesję aplikacji dla tego użytkownika, jeśli wszystkie wymagania dotyczące logowania są spełnione przez odpowiedź interfejsu API Google.

Jeśli użytkownika nie ma w bazie danych użytkowników, należy przekierować go do przepływu rejestracji nowego użytkownika. Możesz mieć możliwość automatycznej rejestracji użytkownika na podstawie informacji otrzymanych od Google, a 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 punktach końcowych naszego profilu użytkownika.

Zaawansowane tematy

W poniższych sekcjach szczegółowo opisano 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 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 Ty 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 zakresu openid email https://www.googleapis.com/auth/profile.agerange.read . Użytkownik jest odpowiednio monitowany na ekranie akceptacji . Token dostępu, który otrzymasz z powrotem od Google, umożliwia dostęp do wszystkich interfejsów API związanych z zakresami dostępu, o które prosiłeś i które zostały przyznane.

Odśwież tokeny

W swoim wniosku o dostęp do API możesz zażądać zwrotu 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 ustawienie parametru access_type na offline w żądaniu uwierzytelnienia .

Rozważania:

  • Pamiętaj, aby przechowywać token odświeżania bezpiecznie i na stałe, ponieważ token odświeżania można uzyskać tylko podczas pierwszego wykonywania przepływu wymiany kodu.
  • Istnieją ograniczenia dotyczące liczby wystawianych tokenów odświeżania: jeden limit na kombinację klienta / użytkownika 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ę aplikacji, ustawiając parametr prompt celu consent w żądaniu uwierzytelnienia . Gdy prompt=consent jest uwzględniona, ekran zgody jest wyświetlany za każdym razem, gdy Twoja aplikacja zażą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.

Aby uzyskać więcej informacji na temat parametru prompt , zobacz prompt w tabeli parametrów identyfikatora URI uwierzytelniania .

Parametry identyfikatora 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 Console Credentials page, zgodnie z opisem w sekcji Uzyskiwanie poświadczeń OAuth 2.0 .
nonce (Wymagany) Losowa wartość wygenerowana przez Twoją aplikację, która umożliwia ochronę przed powtórkami.
response_type (Wymagany) Jeśli wartość to code , uruchamia przepływ kodu autoryzacji podstawowej , wymagając POST do punktu końcowego tokenu w celu uzyskania tokenów. Jeśli wartość to token id_token lub id_token token , uruchamia niejawny przepływ , wymagając użycia JavaScript w przekierowaniu URI w celu pobrania tokenów z identyfikatora URI #fragment .
redirect_uri (Wymagany) Określa, gdzie wysyłana jest odpowiedź. Wartość tego parametru musi dokładnie odpowiadać jednej z autoryzowanych wartości przekierowania ustawionych w API Console Credentials page (łącznie ze schematem HTTP lub HTTPS, wielkością liter i końcowym „/”, jeśli istnieje).
scope (Wymagany)

Parametr scope 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 obecna, token identyfikatora może (ale nie gwarantuje) zawierać domyślne oświadczenia profile .

Jeśli wartość zakresu email jest obecna, token identyfikatora obejmuje oświadczenia email - 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 Dysku Google użytkownika dla poszczególnych plików, parametrem zakresu może być openid profile email https://www.googleapis.com/auth/drive.file .

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

state (Opcjonalnie, ale zdecydowanie zalecane)

Nieprzezroczysty ciąg, który jest przesyłany w obie strony w protokole; to znaczy, 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ż można odgadnąć redirect_uri , użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia zainicjowanego przez aplikację. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót jakiegoś stanu klienta (np. Plik 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 lokacjami.

access_type (Opcjonalny) Dozwolone wartości to offline i online . Efekt jest udokumentowany w Dostęp w trybie 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 służąca do określania sposobu wyświetlania przez serwer autoryzacji stron interfejsu użytkownika uwierzytelniania i wyrażania 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 kontach hostowanych 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 ogólnie, 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ć. Koniecznie validate że wrócił ID żeton ma hd wartości roszczenia, które mecze czego oczekujesz (np mycolledge.edu ). W przeciwieństwie do parametru żądania, roszczenie hd tokenu identyfikatora jest zawarte w tokenie bezpieczeństwa od Google, więc wartości można ufać.

include_granted_scopes (Opcjonalny) Jeśli dla tego parametru zostanie podana wartość true , a żądanie autoryzacji zostanie udzielone, autoryzacja obejmie wszelkie poprzednie uprawnienia przyznane tej kombinacji użytkownik / aplikacja dla innych zakresów; zobacz Autoryzacja przyrostowa .

Należy pamiętać, że nie można dokonać przyrostowej autoryzacji za pomocą przepływu 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 występujących w przypadku aplikacji 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 (Opcjonalny) Rozdzielana spacjami lista wartości łańcuchowych, która określa, czy serwer autoryzacji monituje użytkownika o ponowne uwierzytelnienie i zgodę. Możliwe wartości to:
  • none

    Serwer autoryzacyjny 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. Możesz użyć none aby sprawdzić istniejące uwierzytelnienie i / lub zgodę.

  • consent

    Serwer autoryzacyjny pyta 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 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 akceptacji.

Weryfikacja tokena identyfikatora

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

Poniżej przedstawiono typowe sytuacje, w których możesz wysłać tokeny identyfikatora na swój serwer:

  • Wysyłanie tokenów ID z żądaniami, które wymagają uwierzytelnienia. Tokeny identyfikacyjne informują o konkretnym użytkowniku wysyłającym żądanie oraz o tym, któremu klientowi przyznano ten token identyfikatora.

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

Jedną z rzeczy, które sprawiają, że tokeny identyfikacyjne są przydatne, jest fakt, że można je przekazywać między różnymi komponentami aplikacji. Te składniki mogą używać tokenu identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Ale zanim będzie można korzystać z informacji w ID tokena lub polegać na nim jako twierdzenie, że użytkownik został uwierzytelniony, należy je zweryfikować.

Weryfikacja tokena identyfikatora wymaga kilku kroków:

  1. Sprawdź, czy token identyfikatora jest poprawnie podpisany przez wystawcę. Tokeny wydane przez Google są podpisywane przy użyciu jednego z certyfikatów znajdujących się w identyfikatorze URI określonym w wartości metadanych jwks_uri dokumentu Discovery .
  2. Sprawdź, czy wartość żądania 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 nie upłynął czas wygaśnięcia (roszczenie exp ) tokenu identyfikatora.
  5. Jeśli w żądaniu określono wartość parametru hd , sprawdź, czy token identyfikatora zawiera żądanie hd pasujące do akceptowanej domeny hostowanej 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 opisywać.

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

tokeninfo 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ć walidację lokalnie. Należy pobrać identyfikator URI kluczy z dokumentu wykrywania przy użyciu wartości metadanych jwks_uri . Żądania do punktu końcowego debugowania mogą być ograniczane lub w inny sposób podlegać sporadycznym błędom.

Ponieważ Google rzadko zmienia swoje klucze publiczne, można je buforować przy użyciu dyrektyw pamięci podręcznej odpowiedzi HTTP iw większości przypadków przeprowadzać walidację lokalną znacznie wydajniej niż przy użyciu 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 istnieją dobrze zdebugowane biblioteki dostępne w wielu różnych językach, które to umożliwiają (patrz jwt.io ).

Uzyskiwanie informacji o profilu użytkownika

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

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

    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 email - email , możesz uwzględnić następujący parametr w identyfikatorze URI żądania uwierzytelnienia:

    scope=openid%20profile%20email
  2. Dodaj 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 wykrywania przy użyciu wartości metadanych userinfo_endpoint . Odpowiedź w informacjach o użytkowniku zawiera informacje o użytkowniku, zgodnie z opisem w OpenID Connect Standard Claims i wartości metadanych claims_supported w dokumencie 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 swoich autoryzowanych zakresów dostępu.

Dokument Discovery

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 użycie „dokumentu wykrywania”, dokumentu JSON znajdującego się w dobrze znanej lokalizacji, zawierającego pary klucz-wartość, które zawierają szczegółowe informacje o konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji , token, odwołanie, informacje o użytkowniku i punkty końcowe kluczy publicznych. Dokument Discovery dotyczący 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, należy na stałe zakodować identyfikator URI dokumentu Discovery ( https://accounts.google.com/.well-known/openid-configuration ) w swojej aplikacji. Twoja aplikacja pobiera dokument, stosuje w odpowiedzi reguły buforowania, a następnie w razie potrzeby pobiera z niej identyfikatory URI punktów końcowych. Na przykład, aby uwierzytelnić użytkownika, Twój kod będzie pobierać authorization_endpoint wartości metadanych ( https://accounts.google.com/o/oauth2/v2/auth w poniższym przykładzie) jako podstawy do URI żądania uwierzytelnienia, które są wysyłane do Google.

Oto przykład takiego dokumentu; nazwy pól są określone w OpenID Connect Discovery 1.0 (ich znaczenie można znaleźć w tym dokumencie). Wartości mają charakter wyłącznie ilustracyjny i mogą ulec zmianie, chociaż zostały skopiowane z najnowszej wersji faktycznego 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ąć przesyłania w obie strony HTTP, buforując wartości z dokumentu odnajdywania. Używane są standardowe nagłówki pamięci podręcznej HTTP i należy ich przestrzegać.

Biblioteki klienckie

Poniższe biblioteki klienckie ułatwiają wdrażanie protokołu OAuth 2.0 dzięki integracji z popularnymi platformami:

Zgodność z OpenID Connect

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