OpenID Connect

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Interfejsy API Google OAuth 2.0 mogą służyć zarówno do uwierzytelniania, jak i uwierzytelniania. Ten dokument opisuje naszą implementację uwierzytelniania OAuth 2.0, która jest zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID Certified. Zapoznaj się też z dokumentacją dostępu do interfejsów API Google przy użyciu protokołu OAuth 2.0. Jeśli chcesz korzystać z tego protokołu interaktywnie, zalecamy skorzystanie z Google OAuth 2.0 Playground. Jeśli potrzebujesz pomocy w związku z usługą Stack Overflow, dodaj do swoich pytań tag „##99;google-oauth'”.

Konfigurowanie protokołu OAuth 2.0

Zanim Twoja aplikacja będzie mogła używać systemu uwierzytelniania OAuth 2.0 do logowania użytkowników, musisz skonfigurować projekt w Google API Console , aby uzyskać dane logowania OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje o marce, 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 wykonać inne zadania. Więcej informacji znajdziesz w Centrum pomocyGoogle API Console.

Uzyskanie danych logowania OAuth 2.0

Do uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów API Google potrzebne są dane logowania OAuth 2.0, w tym identyfikator klienta i tajny klucz 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.

Ustawianie identyfikatora 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 uwierzytelniania OAuth 2.0 użytkownikom wyświetla się 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 adresu e-mail i podstawowych informacji o koncie. Prosisz o dostęp do tych informacji za pomocą parametru scope, który aplikacja uwzględnia w żądaniu uwierzytelniania. Możesz też użyć zakresów, aby poprosić o dostęp do innych interfejsów API Google.

Ekran zgody użytkownika zawiera też informacje o marce, takie jak nazwa produktu, logo i adres URL strony głównej. Informacje o budowaniu marki możesz kontrolować w narzędziu 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 .

Następne okno z prośbą o zgodę na wykorzystanie danych pokazuje, co użytkownik zobaczy w żądaniu, które zawiera kombinację zakresów OAuth 2.0 i Dysku Google. (To ogólne okno zostało wygenerowane za pomocą Google Play 2.0 Playground, więc nie zawiera informacji o budowaniu marki skonfigurowanych w API Console).

Zrzut ekranu strony z prośbą o zgodę

Uzyskiwanie dostępu do usługi

Google i inne firmy oferują biblioteki, w których można zarządzać wieloma szczegółami implementacji uwierzytelniania użytkowników i uzyskiwaniem dostępu do interfejsów API Google. Przykłady obejmują usługi Google Identity i biblioteki klienta Google, które są dostępne na różnych platformach.

Jeśli nie chcesz korzystać z biblioteki, postępuj zgodnie z instrukcjami znajdującymi się w pozostałej części tego dokumentu. Opisuje przepływy żądań HTTP, które są domyślnie dostępne.

Uwierzytelnianie użytkownika

Uwierzytelnianie użytkownika wymaga uzyskania tokena identyfikatora i zweryfikowania go. Tokeny identyfikatorów to standardowa funkcja OpenID Connect, która służy do udostępniania potwierdzenia tożsamości w internecie.

Najczęściej używanym sposobem uwierzytelniania użytkownika i uzyskiwania tokena identyfikatora jest proces &serwer – wzorzec &"implicit" Flow. Proces serwera pozwala serwerowi backendu aplikacji sprawdzać tożsamość użytkownika przy użyciu przeglądarki lub urządzenia mobilnego. Ten proces jest używany, gdy aplikacja po stronie klienta (zwykle 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 opisuje, jak wykonać procedurę serwera w celu uwierzytelnienia użytkownika. Jest to znacznie bardziej skomplikowane z powodu zagrożeń związanych z bezpieczeństwem obsługi i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć proces pośredni, zalecamy użycie usług tożsamości Google.

Przepływ serwera

Pamiętaj, aby skonfigurować aplikację w: API Console, tak aby mogła korzystać z tych protokołów i uwierzytelniać użytkowników. Gdy użytkownik spróbuje zalogować się przez Google:

  1. Tworzenie tokena stanu zapobiegającego fałszowaniu
  2. Wysyłanie do Google prośby o uwierzytelnienie
  3. Potwierdzanie tokena stanu fałszowania
  4. Wymiana code na token dostępu i token tożsamości
  5. Pobieranie informacji o użytkowniku z tokena identyfikatora
  6. Uwierzytelnianie użytkownika

1. Tworzenie tokena stanu zapobiegającego fałszowaniu

Musisz chronić bezpieczeństwo użytkowników, zapobiegając atakom fałszywym. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który utrzymuje stan między aplikacją a klientem klienta. Później dopasowujesz ten unikalny token sesji do odpowiedzi uwierzytelniania zwróconej przez usługę logowania Google OAuth, aby zweryfikować, czy użytkownik wykonuje żądanie i nie jest złośliwym atakującym. Czasami są one nazywane „fałszywymi żądaniami w różnych witrynach” (CSRF).

Tokenem stanu może być co najmniej 30 znaków stworzonych za pomocą wysokiej jakości generatora liczb losowych. Kolejnym skrótem jest wygenerowany przez podpisanie niektórych zmiennych stanu sesji za pomocą klucza ukrytego w backendzie.

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

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla PHP.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla 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. Podczas wykonywania tego procesu używaj protokołu HTTPS zamiast HTTP. Połączenia HTTP są odrzucane. Pobierz podstawowy identyfikator URI z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint. W tej rozmowie założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth.

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

  • client_id, którą uzyskujesz z API ConsoleCredentials page.
  • response_type. W podstawowym żądaniu przepływu autoryzacji powinien wyświetlić się code. (Więcej informacji znajdziesz na stronie response_type).
  • scope, który w podstawowym żądaniu powinien mieć wartość openid email. (Więcej informacji znajdziesz na stronie scope).
  • redirect_uri powinien być punktem końcowym HTTP na serwerze, który otrzymuje odpowiedź od Google. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API Console Credentials page. Jeśli ta wartość nie będzie zgodna z autoryzowanym identyfikatorem URI, żądanie zakończy się niepowodzeniem i błędem redirect_uri_mismatch.
  • Wartość state powinna zawierać wartość unikalnego tokena zapobiegającego fałszowaniu, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wróci do Twojej aplikacji, np. początkowy adres URL. (Więcej informacji znajdziesz na stronie state).
  • nonce to losowa wartość wygenerowana przez Twoją aplikację, która umożliwia ochronę odtwarzania, jeśli występuje.
  • login_hint może być adresem e-mail użytkownika lub ciągiem sub odpowiadającym identyfikatorowi Google użytkownika. Jeśli nie podasz identyfikatora login_hint, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zgodę na zwolnienie adresu e-mail użytkownika z aplikacji. Więcej informacji znajdziesz na login_hint.
  • Parametr hd pozwala zoptymalizować przepływ OpenID Connect dla użytkowników w określonej domenie powiązanej z organizacją Google Cloud. (Więcej informacji znajdziesz na stronie hd).

Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect z podziałem na wiersze i spacjami:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

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

Ten kod potwierdza, że tokeny sesji utworzone w kroku 1:

PHP

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla PHP.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Aby użyć tej próbki, musisz pobrać bibliotekę klienta interfejsów API Google dla 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 wykonuje tę wymianę przez wysłanie żądania HTTPS POST. Żądanie POST jest wysyłane do punktu końcowego tokena, który należy pobrać z dokumentu Discovery za pomocą wartości metadanych token_endpoint. W tej rozmowie 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, który jest 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 od Credentials page API Consolezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0.
redirect_uri Autoryzowany identyfikator URI przekierowania dla podanego client_id podany 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.

Żądanie może wyglądać np. tak:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Pomyślna odpowiedź na to żądanie zawiera te pola w tablicy JSON:

Pola
access_token Token, który można wysłać do interfejsu API Google.
expires_in Pozostały okres 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 przydzielone przez access_token jako listę ciągów rozdzielanych spacjami (wielkość liter ma znaczenie).
token_type Określa typ zwróconego tokena. Obecnie to pole ma zawsze wartość Bearer.
refresh_token (opcjonalnie)

To pole jest widoczne tylko wtedy, gdy parametr access_type w żądaniu uwierzytelniania ma wartość offline. Więcej informacji znajdziesz w temacie Tokeny odświeżania.

5. Uzyskiwanie informacji o użytkowniku z tokena identyfikatora

Token identyfikatora to JWT (token tokena JSON), który jest szyfrowanym kryptograficznie obiektem JSON. Ważne jest, aby używać tokena identyfikatora przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google bez pośredniego kanału HTTPS i używasz swojego tajnego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token pochodzi od Google i jest prawidłowy. Jeśli serwer przekazuje token identyfikatora do innych komponentów aplikacji, pamiętaj, by przed jego użyciem sprawdzić token.

Większość bibliotek API łączy weryfikację z pracą dekodowania wartości zakodowanej w standardzie base64url i analizowania wewnątrz pliku JSON, więc i tak powinno dojść do weryfikacji tokena podczas uzyskiwania dostępu do deklaracji w tokenie identyfikatora.

Ładunek identyfikatora

Token identyfikatora to obiekt JSON zawierający zbiór par nazwa/wartość. Oto przykład w formacie czytelnym:

{
  "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 identyfikatora Google mogą zawierać te pola (nazywane roszczeniami):

Odbierz zapisana karta Opis
aud zawsze Lista odbiorców, dla której jest przeznaczony ten identyfikator. 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 identyfikatora. Wartość jest podawana w czasie uniksowym (liczba całkowita w sekundach).
iat zawsze Data wydania tokena identyfikatora. Wartość będzie podawana w czasie uniksowym (liczba całkowita w sekundach).
iss zawsze Identyfikator wystawcy odpowiedzi. Zawsze https://accounts.google.com lub accounts.google.com w przypadku tokenów tożsamości Google.
sub zawsze Unikalny identyfikator użytkownika dla wszystkich kont Google, który nigdy nie został ponownie użyty. Konto Google może mieć wiele adresów e-mail w różnych momentach, ale wartość sub nigdy się nie zmienia. Użyj sub w aplikacji jako klucza unikalnego identyfikatora użytkownika. Maksymalna długość 255 znaków ASCII (z uwzględnieniem wielkości liter).
at_hash Hasz tokena dostępu. Zapewnia weryfikację, że token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest generowany z wartością access_token w przepływie serwera, to roszczenie jest zawsze uwzględniane. To roszczenie może być alternatywnym mechanizmem służącym do ochrony przed atakami typu fałszowanie żądań z innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu.
azp client_id autoryzowanego prowadzącego. Ta deklaracja jest potrzebna tylko wtedy, gdy strona żądająca tokena tożsamości nie jest taka sama jak lista odbiorców tokena identyfikatora. Może się tak zdarzyć w Google w przypadku aplikacji hybrydowych, które mają inną aplikację OAuth 2.0 client_id niż aplikację internetową, ale mają ten sam projekt Google API.
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. Wartość dostarczana tylko wtedy, gdy zakres zawiera wartość zakresu email.
email_verified Prawda, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie ma wartość Fałsz.
family_name imiona i nazwiska użytkowników; Ten atrybut można podać, jeśli istnieje roszczenie name.
given_name Imię lub nazwisko użytkownika. Ten atrybut można podać, jeśli istnieje roszczenie name.
hd Domena powiązana z organizacją użytkownika Google Cloud. Podany 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 formie, która może zostać wyświetlona. Może zostać podana, gdy:
  • Zakres żądania zawierał ciąg "profile"
  • Token identyfikatora jest zwracany po odświeżeniu tokena

Jeśli istnieją roszczenia name, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.

nonce Wartość nonce podana przez aplikację w żądaniu uwierzytelniania. Zadbaj o to, aby była wyświetlana tylko raz, co zapewni ochronę przed atakami typu replay.
picture Adres URL zdjęcia profilowego użytkownika. Może zostać podana, gdy:
  • Zakres żądania zawierał ciąg "profile"
  • Token identyfikatora jest zwracany po odświeżeniu tokena

Jeśli istnieją roszczenia picture, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.

profile Adres URL strony profilu użytkownika. Może zostać podana, gdy:
  • Zakres żądania zawierał ciąg "profile"
  • Token identyfikatora jest zwracany po odświeżeniu tokena

Jeśli istnieją roszczenia profile, możesz ich użyć do zaktualizowania rekordów użytkowników aplikacji. Pamiętaj, że nigdy nie ma takiej gwarancji.

6. Uwierzytelnianie użytkownika

Po otrzymaniu informacji o użytkowniku od tokena identyfikatora wyślij 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 logowania są spełnione przez interfejs API Google.

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

Tematy zaawansowane

Poniżej znajdziesz więcej informacji o interfejsie Google OAuth 2.0 API. Ta informacja jest przeznaczona dla programistów z zaawansowanymi wymaganiami dotyczącymi uwierzytelniania i autoryzacji.

Dostęp do innych interfejsów API Google

Jedną z zalet uwierzytelniania OAuth 2.0 jest to, że aplikacja może uzyskać uprawnienia do używania innych interfejsów API Google w imieniu użytkownika (np. YouTube, Dysku Google, Kalendarza lub Kontaktów) podczas uwierzytelniania użytkownika. Aby to zrobić, uwzględnij inne zakresy, których potrzebujesz, w żądaniu uwierzytelniania wysłanym do Google. Aby na przykład dodać do grupy uwierzytelniania grupę wiekową użytkownika, przekaż parametr zakresu openid email https://www.googleapis.com/auth/profile.agerange.read. użytkownik zobaczy odpowiedni komunikat na ekranie zgody. Token dostępu, który otrzymujesz od Google, pozwala uzyskać dostęp do wszystkich interfejsów API powiązanych z żądanymi zakresami dostępu i przyznanymi.

Odśwież tokeny

W swojej prośbie o dostęp do interfejsu API możesz poprosić o zwrot tokena odświeżania podczas giełdy code. Token odświeżania zapewnia stały dostęp aplikacji 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:

  • Token odświeżania musi być zabezpieczony na stałe i na stałe, ponieważ token odświeżania można pobrać tylko po pierwszym uruchomieniu procesu wymiany kodu.
  • Istnieją limity liczby tokenów odświeżania – po jednym limicie kombinacji na klienta i użytkownika na wszystkich klientów. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, mogą one przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

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

Możesz poprosić użytkownika o ponowne uwierzytelnienie aplikacji, ustawiając parametr prompt na consent w żądaniu uwierzytelniania. Jeśli uwzględnisz właściwość 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 przyznane Twojemu projektowi interfejsów API Google. Z tego powodu właściwość prompt=consent powinna być uwzględniana 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

Poniższa tabela zawiera pełniejszy opis parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0.

Parametr Wymagane Opis
client_id (wymagane) Ciąg identyfikatora klienta uzyskany od API ConsoleCredentials page, jak opisano w sekcji Uzyskiwanie danych logowania OAuth 2.0.
nonce (wymagane) Losowa wartość wygenerowana przez aplikację, która umożliwia ochronę odtwarzania.
response_type (wymagane) Jeśli wartość to code, uruchamia podstawowy przepływ autoryzacji, gdzie do punktu końcowego tokena wymagana jest właściwość POST. Jeśli wartość to token id_token lub id_token token, uruchamia domyślny proces, który wymaga użycia JavaScriptu w identyfikatorze URI przekierowania do pobrania tokenów z identyfikatora #fragment identyfikatora URI.
redirect_uri (wymagane) Określa, gdzie jest wysyłana odpowiedź. Wartość tego parametru musi dokładnie odpowiadać jednej z autoryzowanych wartości przekierowań ustawionych w polu API ConsoleCredentials page (w tym schematu HTTP lub HTTPS, kropki i końca ' 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 wartość zakresu profile jest obecna, token identyfikatora może (ale nie musi) zawierać domyślne roszczenia profile użytkownika.

Jeśli wartość zakresu email jest obecna, token identyfikatora zawiera roszczenia email i email_verified.

Oprócz zakresów określonych przez OpenID Twój zakres może też zawierać inne wartości zakresu. Wszystkie wartości zakresu muszą być rozdzielone spacjami. Jeśli na przykład chcesz mieć dostęp do pliku na Dysku Google użytkownika, parametr zakresu może wyglądać tak: openid profile email https://www.googleapis.com/auth/drive.file.

Informacje o dostępnych zakresach znajdziesz w artykule Zakresy OAuth 2.0 na potrzeby interfejsów API Google lub w dokumentacji interfejsu Google API, której chcesz używać.

state (Opcjonalne, ale zdecydowanie zalecane)

Nieprzezroczysty ciąg znaków, który jest w obu kierunkach, określony jako protokół URI, to znaczy, że jest zwracany jako parametr URI w przepływie podstawowym, a w identyfikatorze URI #fragment w przepływie wynikowym.

state może być przydatny do korelowania żądań i odpowiedzi. Odgadnięcie wartości redirect_uri sprawia, że użycie wartości state zwiększa pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania zainicjowanego przez Twoją aplikację. Jeśli w zmiennej state wygenerujesz losowy ciąg znaków lub zaszyfrujesz hasz niektórych stanów klienta, możesz zweryfikować odpowiedź, aby się upewnić, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Takie rozwiązanie chroni przed atakami typu sfałszowanie żądania z innej witryny.

access_type (Opcjonalnie) Dozwolone wartości to offline i online. Efekt jest udokumentowany w sekcji Dostęp offline. Jeśli zażądano tokena dostępu, klient nie otrzyma tokena odświeżania, chyba że określono wartość offline.
display (Opcjonalnie) Wartość ciągu ASCII określająca, w jaki sposób serwer autoryzacji ma wyświetlać strony interfejsu uwierzytelniania i zgody. Te wartości zostały określone i zaakceptowane przez serwery Google, ale nie mają żadnego wpływu na działanie usługi: page, popup, touch i wap.
hd (Opcjonalnie)

Uprość proces logowania na konta należące do organizacji Google Cloud. Dodając domenę organizacji Google Cloud (np. mycollege.edu), możesz wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby przeprowadzać optymalizację pod kątem kont organizacji w Google Cloud, zamiast tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki (*): hd=*.

Nie polegaj na tej optymalizacji interfejsu, aby kontrolować, kto ma dostęp do Twojej aplikacji – żądania można modyfikować po stronie klienta. Pamiętaj, aby sprawdzić, czy zwrócony token identyfikatora ma wartość roszczenia hd zgodną z Twoimi oczekiwaniami (np. mycolledge.edu). W odróżnieniu od parametru żądania żądanie identyfikatora tokena hd jest zawarte w tokenie zabezpieczeń od Google, więc można ufać tej wartości.

include_granted_scopes (Opcjonalnie) Jeśli ten parametr zostanie podany z wartością true, a prośba o autoryzację zostanie przyznana, autoryzacja będzie obejmować wszystkie poprzednie autoryzacje, które zostały przypisane do tej kombinacji użytkownika i aplikacji w innych zakresach; patrz sekcja Autoryzacja przyrostowa.

Pamiętaj, że w ramach procesu instalowania aplikacji nie możesz zwiększać autoryzacji.

login_hint (Opcjonalnie) Gdy aplikacja wie, którego użytkownika próbuje uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Pominięcie tej podpowiedzi powoduje pominięcie wyboru konta i wstępne wypełnianie pola e-maila w formularzu logowania lub wybranie właściwej sesji (jeśli użytkownik korzysta z wielokrotnego logowania), co pomaga uniknąć problemów, gdy aplikacja loguje się na niewłaściwe konto użytkownika. Wartością może być adres e-mail lub ciąg sub, który odpowiada identyfikatorowi Google użytkownika.
prompt (Opcjonalnie) Lista rozdzielonych spacjami wartości ciągu, które określają, czy serwer autoryzacji poprosi użytkownika o ponowne uwierzytelnienie i zgodę. Możliwe wartości:
  • none

    Serwer autoryzacji nie wyświetla żadnych uwierzytelniania ani ekranów zgody użytkownika. Jeśli użytkownik nie jest jeszcze uwierzytelniony i nie ma wstępnie skonfigurowanej zgody na wymienione zakresy, zwróci komunikat o błędzie. Możesz użyć none, aby sprawdzić istniejące uwierzytelnianie lub zgodę.

  • consent

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

  • select_account

    Serwer autoryzacji wyświetli 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, do których może prowadzić sesje.

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

Weryfikowanie tokena identyfikatora

Musisz zweryfikować wszystkie tokeny identyfikatora na swoim serwerze, chyba że pochodzą bezpośrednio od Google. Serwer musi na przykład zweryfikować autentyczność tokenów tożsamości otrzymanych z aplikacji klienckich.

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

  • Wysyłam tokeny identyfikatora z żądaniami, które wymagają uwierzytelnienia. Tokeny z identyfikatorem informują o tym, który użytkownik przesłał żądanie i w przypadku którego klienta został on przyznany.

Tokeny identyfikatora są poufne i mogą być używane nieprawidłowo, jeśli zostaną przechwycone. Musisz upewnić się, że te tokeny są obsługiwane w bezpieczny sposób, wysyłając je tylko przez protokół HTTPS i tylko przez dane POST lub nagłówki żądań. Jeśli przechowujesz tokeny identyfikatorów na serwerze, musisz je też bezpiecznie przechowywać.

Jedną z przydatnych tokenów tożsamości jest fakt, że możesz je przekazywać w różnych komponentach aplikacji. Te komponenty mogą używać tokena identyfikatora jako prostego mechanizmu uwierzytelniania uwierzytelniającego 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 wymaga kilku kroków:

  1. Sprawdź, czy token identyfikatora jest prawidłowo podpisany przez wydawcę. Tokeny wydane przez Google są podpisane jednym z certyfikatów wymienionych w identyfikatorze URI podanym 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 okres ważności tokena (exp) nie upłynął.
  5. Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora zawiera deklarację hd pasującą do akceptowanej domeny powiązanej z organizacją Google Cloud.

Kroki 2–5 obejmują tylko proste porównania ciągów znaków i daty, dlatego omówimy je tutaj.

Pierwszy krok jest bardziej skomplikowany i wymaga weryfikacji podpisu kryptograficznego. Do debugowania możesz użyć punktu końcowego tokeninfo w Google, aby porównać go z przetwarzaniem lokalnym wdrożonym na serwerze lub urządzeniu. Załóżmy, że wartość tokena identyfikatora to XYZ123. Następnie określ identyfikator URI: https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jeśli podpis tokena jest prawidłowy, odpowiedzią będzie ładunek JWT w zdekodowanym formacie obiektu JSON.

Punkt końcowy tokeninfo jest przydatny podczas debugowania, ale do celów produkcyjnych pobierz klucze publiczne Google z punktu końcowego kluczy i przeprowadź weryfikację lokalnie. Identyfikator URI klucza powinien być pobrany z dokumentu Discovery przy użyciu wartości metadanych jwks_uri. Żądania do punktu końcowego debugowania mogą być ograniczone lub w przeciwnym razie mogą występować przejściowe błędy.

Google rzadko zmienia klucze publiczne, dlatego możesz buforować je przy użyciu dyrektyw pamięci podręcznej odpowiedzi HTTP i w większości przypadków wykonujesz 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. Aby to osiągnąć, można korzystać z dobrze debugowanych bibliotek w wielu różnych językach (zobacz jwt.io).

Uzyskiwanie informacji z profilu użytkownika

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

  1. Aby zapewnić zgodność z OpenID, w żądaniu uwierzytelniania musisz umieścić 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, który możesz pobrać z dokumentu Discovery za pomocą wartości metadanych userinfo_endpoint. Odpowiedź dotycząca informacji o użytkowniku zawiera informacje o użytkowniku, tak jak to opisano w OpenID Connect Standard Claims oraz wartości metadanych claims_supported w dokumencie Discovery. Użytkownicy lub ich organizacje mogą udostępniać lub wstrzymywać określone pola, dlatego niektóre dane w autoryzowanych zakresach dostępu mogą nie być dostępne.

dokument Discovery,

Protokół OpenID Connect wymaga użycia wielu punktów końcowych do uwierzytelniania użytkowników oraz wysyłania żądań dotyczących 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 zawierającej pary klucz-wartość, które zawierają szczegółowe informacje o konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, unieważniania, informacji o użytkowniku i punktów końcowych kluczy. Dokument Discovery dla usługi OpenID Connect można pobrać z:

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

Aby korzystać z usług OpenID Connect, musisz zakodować na stałe identyfikator URI dokumentu wykrywania (https://accounts.google.com/.well-known/openid-configuration) w aplikacji. Aplikacja pobiera dokument, stosuje reguły pamięci podręcznej w odpowiedzi, a następnie w razie potrzeby pobiera z niej identyfikatory URI punktów końcowych. Aby na przykład uwierzytelnić użytkownika, Twój kod pobiera wartość metadanych authorization_endpoint (w poniższym przykładzie https://accounts.google.com/o/oauth2/v2/auth) jako podstawowy identyfikator URI żądań uwierzytelniania wysyłanych do Google.

Oto przykład takiego dokumentu. Nazwy pól są podane w formacie OpenID Connect Discovery 1.0 (ich znaczenie znajdziesz w tym dokumencie). Wartości stanowią tylko ilustrację i mogą się zmieniać, ale są kopiowane z najnowszej wersji rzeczywistego dokumentu Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Być może uda Ci się uniknąć przekierowania w obie strony, buforując wartości z dokumentu Discovery. Używane są standardowe nagłówki pamięci podręcznej HTTP, które należy uwzględnić.

Biblioteki klienta

Poniższe biblioteki klienta ułatwiają implementację protokołu OAuth 2.0 dzięki integracji z popularnymi platformami:

Zgodność z OpenID Connect

System uwierzytelniania OAuth 2.0 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).