Interfejsy API Google OAuth 2.0 mogą być używane zarówno do uwierzytelniania, jak i autoryzacji. Ten dokument opisuje naszą implementację protokołu OAuth 2.0 do uwierzytelniania. Jest ona zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID. Dotyczy to również dokumentacji dotyczącej używania OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google. Jeśli chcesz poznać ten protokół w interaktywny sposób, zalecamy skorzystanie z narzędzia Google OAuth 2.0 Playground. Aby uzyskać pomoc na Stack Overflow, oznacz swoje pytania tagiem „google-oauth”.
Konfigurowanie protokołu OAuth 2.0
Zanim aplikacja będzie mogła korzystać z systemu uwierzytelniania Google OAuth 2.0 do logowania się użytkowników, musisz skonfigurować projekt w Google API Console , aby uzyskać dane uwierzytelniające protokołu OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje marki widoczne dla użytkowników 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.
Uzyskiwanie danych logowania OAuth 2.0
Aby uwierzytelnić użytkowników i uzyskać dostęp do interfejsów API Google, potrzebujesz danych logowania OAuth 2.0, w tym identyfikatora klienta i tajnego klucza klienta.
Aby wyświetlić identyfikator klienta i klucz tajny klienta dla danego poświadczenia OAuth 2.0, kliknij następujący tekst: Wybierz poświadczenie . W oknie, które zostanie otwarte, wybierz projekt i żądane poświadczenia, a następnie kliknij opcję Wyświetl .
Lub wyświetl swój identyfikator klienta i API Console tajny klienta ze strony Poświadczenia w API Console :
- Go to the Credentials page.
- Kliknij nazwę swojego poświadczenia lub ikonę ołówka ( create ). 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, dokąd Google będzie wysyłać odpowiedzi na Twoje żądania uwierzytelniania.
Aby utworzyć, wyświetlić lub edytować identyfikatory URI przekierowania dla danego poświadczenia OAuth 2.0, wykonaj następujące czynności:
- Go to the Credentials page.
- W sekcji identyfikatorów klientów OAuth 2.0 na stronie kliknij poświadczenie.
- 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
Dla użytkowników uwierzytelnianie OAuth 2.0 obejmuje ekran akceptacji, który zawiera informacje udostępniane przez użytkownika i obowiązujące warunki. Na przykład podczas logowania użytkownik może zostać poproszony o przyznanie aplikacji dostępu do jego adresu e-mail i podstawowych informacji o koncie. Prosisz o dostęp do tych informacji za pomocą parametru scope
, który jest uwzględniany w żądaniu uwierzytelnienia przez aplikację. 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 dotyczące marki, takie jak nazwa usługi, logo i adres URL strony głównej. Informacje o marce kontrolujesz w API Console.
Aby włączyć ekran akceptacji projektu:
- Otwórz Consent Screen page w Google API Console .
- If prompted, select a project, or create a new one.
- Wypełnij formularz i kliknij Zapisz .
Poniższe okno z prośbą o zgodę na przetwarzanie danych osobowych pokazuje, co zobaczy użytkownik, gdy żądanie zawiera kombinację zakresów OAuth 2.0 i Dysku Google. To ogólne okno zostało wygenerowane za pomocą narzędzia Google OAuth 2.0 Playground, więc nie zawiera informacji o marce, które można było ustawić w API Console.

Uzyskiwanie dostępu do usługi
Google i inne firmy udostępniają biblioteki, których możesz używać do obsługi wielu szczegółów implementacji uwierzytelniania użytkowników i uzyskiwania dostępu do interfejsów API Google. Przykłady obejmują usługi tożsamości Google 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 podanymi w pozostałej części tego dokumentu, w których opisano przepływy żądań HTTP, które są podstawą dostępnych bibliotek.
Uwierzytelnianie użytkownika
Uwierzytelnienie użytkownika obejmuje uzyskanie tokena identyfikatora i jego weryfikację. Tokeny tożsamości to ustandaryzowana funkcja OpenID Connect zaprojektowana do użytku do udostępniania potwierdzeń tożsamości w internecie.
Najczęściej stosowane metody uwierzytelniania użytkownika i uzyskiwania tokena identyfikatora nazywane są przepływami „serwera” i „implicit” (przepływem niejawnym). Przepływ po stronie serwera pozwala serwerowi backendu aplikacji zweryfikować tożsamość osoby korzystającej z przeglądarki lub urządzenia mobilnego. Przepływ niejawny jest używany, gdy aplikacja po stronie klienta (zwykle aplikacja JavaScript działająca w przeglądarce) musi uzyskać bezpośredni dostęp do interfejsów API, a nie przez swój serwer backendu.
W tym dokumencie opisano, jak wykonać przepływ na serwerze w celu uwierzytelnienia użytkownika. Przepływ niejawny jest znacznie bardziej skomplikowany ze względu na zagrożenia dla bezpieczeństwa podczas obsługi i używania tokenów po stronie klienta. Jeśli chcesz wdrożyć przepływ niejawny, zdecydowanie zalecamy korzystanie z usług tożsamości Google.
Przepływ na serwerze
Skonfiguruj aplikację API Console, aby umożliwić jej korzystanie z tych protokołów i uwierzytelnianie użytkowników. Gdy użytkownik próbuje zalogować się przez Google, musisz:
- Tworzenie tokena stanu zapobiegającego fałszowaniu
- Wysyłanie żądania uwierzytelnienia do Google
- Potwierdzanie tokena stanu ochrony przed fałszowaniem
- Exchange
code
na potrzeby tokena dostępu i identyfikatora - Uzyskiwanie informacji o użytkowniku przy użyciu tokena identyfikatora
- Uwierzytelnij użytkownika
1. Utwórz token stanu zapobiegający fałszowaniu
Musisz chronić bezpieczeństwo użytkowników, zapobiegając atakom polegającym na sfałszowaniu żądania. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który przechowuje stan między Twoją aplikacją a klientem użytkownika. Później dopasowujesz ten unikalny token sesji do odpowiedzi uwierzytelniającej zwróconej przez usługę Google OAuth Login, aby potwierdzić, że żądanie pochodzi od użytkownika, a nie złośliwego atakującego. Tokeny te są często nazywane tokenami fałszowania żądań między witrynami (CSRF).
Token stanu może być na przykład ciągiem 30 znaków utworzonym z wykorzystaniem wysokiej jakości generatora liczb losowych. Inny hasz jest generowany przez podpisywanie niektórych zmiennych stanu sesji kluczem, który jest tajny w Twoim backendzie.
Poniższy kod pokazuje generowanie unikalnych tokenów sesji.
PHP
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka PHP.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Python.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Wyślij żądanie uwierzytelnienia do Google
Następnym krokiem jest utworzenie żądania HTTPS GET
z odpowiednimi parametrami URI.
Zwróć uwagę, że na wszystkich etapach tego procesu używany jest protokół HTTPS zamiast HTTP. Połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery przy użyciu wartości metadanych authorization_endpoint
. W dalszej analizie założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth
.
W przypadku podstawowego żądania podaj te parametry:
client_id
otrzymanych z API Console Credentials pageresponse_type
, który w żądaniu przepływu podstawowego kodu autoryzacji powinien mieć wartośćcode
. (Więcej informacji znajdziesz naresponse_type
).scope
, który w podstawowym żądaniu powinien mieć wartośćopenid email
. (Więcej informacji znajdziesz nascope
).redirect_uri
powinien być punktem końcowym HTTP Twojego serwera, który będzie otrzymywać odpowiedź od Google. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanych w API Console Credentials page. Jeśli ta wartość nie jest zgodna z autoryzowanym identyfikatorem URI, żądanie zakończy się niepowodzeniem i zostanie wyświetlony błądredirect_uri_mismatch
.- Pole
state
powinno zawierać wartość unikalnego tokena sesji zapobiegającego fałszowaniu, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wraca do Twojej aplikacji, np. początkowy adres URL. (Więcej informacji znajdziesz nastate
). nonce
to losowa wartość generowana przez Twoją aplikację, która włącza ochronę przed ponownym odtworzeniem, jeśli jest dostępna.login_hint
może być adresem e-mail użytkownika lub ciągiemsub
, który jest odpowiednikiem identyfikatora Google użytkownika. Jeśli nie podasz właściwościlogin_hint
, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zatwierdzenie zgody na zwolnienie adresu e-mail użytkownika w aplikacji. Więcej informacji znajdziesz nalogin_hint
.- Użyj parametru
hd
, aby zoptymalizować proces OpenID Connect pod kątem użytkowników w określonej domenie powiązanej z organizacją Google Cloud. (Więcej informacji znajdziesz nahd
).
Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect ze znakami podziału wiersza i spacjami, aby zwiększyć czytelność:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Użytkownicy muszą wyrazić zgodę, jeśli Twoja aplikacja poprosi o nowe informacje lub jeśli aplikacja prosi o dostęp do konta, która nie została wcześniej przez nich zatwierdzona.
3. Potwierdź token stanu zapobiegania fałszowaniu
Odpowiedź jest wysyłana do redirect_uri
podanego w żądaniu. Wszystkie odpowiedzi są zwracane w ciągu zapytania, jak pokazano poniżej:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
Na serwerze musisz potwierdzić, że state
otrzymany od Google jest zgodny z tokenem sesji utworzonym w kroku 1. Weryfikacja w obie strony pomaga upewnić się, że żądania wysyła użytkownik, a nie złośliwy skrypt.
Poniższy kod pokazuje potwierdzenie tokenów sesji utworzonych w kroku 1:
PHP
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka PHP.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Java.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Aby użyć tego przykładu, musisz pobrać bibliotekę klienta interfejsów API Google dla języka Python.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. Wymiana code
na token dostępu i token tożsamości
Odpowiedź zawiera parametr code
– jednorazowy kod autoryzacji, który Twój serwer może wymienić na token dostępu i token identyfikatora. Serwer realizuje tę wymianę, wysyłając żądanie HTTPS POST
. Żądanie POST
jest wysyłane do punktu końcowego tokena, który należy pobrać z dokumentu Discovery za pomocą wartości metadanych token_endpoint
. W poniższej dyskusji założono, że punkt końcowy to https://oauth2.googleapis.com/token
. W treści POST
żądanie musi zawierać te parametry:
Pola | |
---|---|
code |
Kod autoryzacji zwracany z początkowego żądania. |
client_id |
Identyfikator klienta otrzymany z Credentials page API Console, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
client_secret |
Klucz klienta uzyskany z API Console Credentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
redirect_uri |
Autoryzowany identyfikator URI przekierowania dla określonego elementu client_id , który jest podany w API Console
Credentials page, zgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania. |
grant_type |
To pole musi zawierać wartość authorization_code
zgodnie ze specyfikacją OAuth 2.0. |
Faktyczne żą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 te pola w tablicy JSON:
Pola | |
---|---|
access_token |
Token, który można wysłać do interfejsu API Google. |
expires_in |
Pozostały czas ważności tokena dostępu w sekundach. |
id_token |
Token JWT zawierający informacje o tożsamości użytkownika podpisane cyfrowo przez Google. |
scope |
Zakresy dostępu przyznane przez usługę access_token wyrażone w postaci listy ciągów rozdzielanych spacjami (z uwzględnieniem wielkości liter). |
token_type |
Identyfikuje typ zwróconego tokena. Obecnie to pole zawsze ma wartość Bearer .
|
refresh_token |
(odpowiedź nie jest wymagana)
To pole jest obecne tylko wtedy, gdy parametr |
5. Uzyskiwanie informacji o użytkowniku z tokena tożsamości
Token identyfikatora to JWT (token sieciowy JSON), czyli podpisany kryptograficznie obiekt JSON zakodowany w standardzie Base64. Zwykle ważne jest weryfikacja tokena identyfikatora przed jego użyciem, ale ponieważ komunikujesz się bezpośrednio z Google przez niepośredni kanał HTTPS i używasz 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, bardzo ważne jest, aby te komponenty zweryfikowały token przed jego użyciem.
Większość bibliotek interfejsów API łączy weryfikację z pracą polegającą na dekodowaniu wartości zakodowanych w base64url i analizie wewnątrz obiektu JSON, więc prawdopodobnie mimo to otrzymasz dostęp do deklaracji w tokenie identyfikatora.
Ładunek tokena identyfikatora
Token identyfikatora to obiekt JSON zawierający zbiór par nazwa/wartość. Oto przykład sformatowany pod kątem czytelności:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Tokeny tożsamości Google mogą zawierać następujące pola (nazywane deklaracjami):
Claim | zapisana karta | Opis |
---|---|---|
aud |
zawsze | Odbiorcy, dla której przeznaczony jest ten token tożsamości. Musi to być jeden z identyfikatorów klienta OAuth 2.0 Twojej aplikacji. |
exp |
zawsze | Termin ważności, po którym token tożsamości nie będzie już akceptowany. Wartość podawana w czasie uniksowym (całkowita liczba sekund). |
iat |
zawsze | Godzina wystawienia tokena tożsamości. Wartość podawana w czasie uniksowym (całkowita liczba sekund). |
iss |
zawsze | Identyfikator wystawcy odpowiedzi. W przypadku tokenów identyfikatorów Google zawsze https://accounts.google.com lub accounts.google.com . |
sub |
zawsze | Identyfikator użytkownika, unikalny wśród wszystkich kont Google i nigdy nieużywany. Konto Google może mieć w różnych momentach wiele adresów e-mail, ale wartość sub nigdy się nie zmienia. Użyj sub w swojej aplikacji jako unikalnego klucza identyfikującego użytkownika. Maksymalna długość to 255 znaków ASCII (wielkość liter ma znaczenie). |
at_hash |
Hasz tokena dostępu. Sprawdza, czy token dostępu jest powiązany z tokenem tożsamości. Jeśli token identyfikatora jest wystawiany z wartością access_token w przepływie serwera, ta deklaracja jest zawsze uwzględniana. To zgłoszenie może być używane jako alternatywny mechanizm ochrony przed atakami polegającymi na sfałszowaniu żądania z innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu. |
|
azp |
client_id autoryzowanego prezentera. Ta deklaracja jest potrzebna tylko wtedy, gdy strona żądająca tokena tożsamości różni się od jego odbiorcy. W Google może tak być w przypadku aplikacji hybrydowych, gdy aplikacja internetowa i aplikacja na Androida mają różne ustawienia client_id OAuth 2.0, ale korzystają z tego samego projektu interfejsów API Google. |
|
email |
Adres e-mail użytkownika. Ta wartość może nie być unikalna dla tego użytkownika i nie może być użyta jako klucz podstawowy. Podany tylko wtedy, gdy Twój zakres zawiera wartość zakresu email . |
|
email_verified |
Wartość „prawda”, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie „false” (fałsz). | |
family_name |
Nazwisko lub nazwisko użytkownika. Może być podany, gdy występuje roszczenie name . |
|
given_name |
Imiona lub imiona użytkownika. Może być podany, gdy występuje roszczenie name . |
|
hd |
Domena powiązana z organizacją użytkownika w Google Cloud. Podawana tylko wtedy, gdy użytkownik należy do organizacji Google Cloud. | |
locale |
Język użytkownika określony przez tag języka BCP 47.
Może być podany, gdy występuje roszczenie name . |
|
name |
Imię i nazwisko użytkownika w możliwej do wyświetlenia formie. Ta wartość może być podana, gdy:
Gdy istnieją roszczenia |
|
nonce |
Wartość parametru nonce dostarczonego przez Twoją 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. Ta wartość może być podana, gdy:
Gdy istnieją roszczenia |
|
profile |
Adres URL strony profilu użytkownika. Ta wartość może być podana, gdy:
Gdy istnieją roszczenia |
6. Uwierzytelnienie 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, rozpocznij dla niego sesję aplikacji, o ile odpowiedź interfejsu API Google spełnia wszystkie wymagania dotyczące logowania.
Jeśli użytkownika nie ma w Twojej bazie danych, musisz przekierować go do procesu rejestracji nowego użytkownika. Możesz automatycznie zarejestrować użytkownika na podstawie informacji otrzymanych od Google lub przynajmniej wstępnie wypełnić wiele pól wymaganych w formularzu rejestracyjnym. Oprócz informacji w tokenie identyfikatora możesz uzyskać dodatkowe informacje o profilu użytkownika w punktach końcowych profilu użytkownika.
Tematy zaawansowane
W poniższych sekcjach szczegółowo opisano interfejs Google OAuth 2.0 API. Te informacje są przeznaczone dla programistów z zaawansowanymi wymaganiami dotyczącymi uwierzytelniania i autoryzacji.
Dostęp do innych interfejsów API Google
Jedną z zalet stosowania protokołu OAuth 2.0 do uwierzytelniania jest to, że aplikacja może uzyskiwać uprawnienia do korzystania z innych interfejsów API Google w imieniu użytkownika (takich jak YouTube, Dysk Google, Kalendarz czy Kontakty) podczas uwierzytelniania użytkownika. Aby to zrobić, uwzględnij inne zakresy, które są potrzebne w prośbę o uwierzytelnienie wysyłanej do Google. Aby na przykład dodać do żądania uwierzytelnienia grupę wiekową użytkownika, przekaż parametr zakresu openid email https://www.googleapis.com/auth/profile.agerange.read
. Na ekranie zgody użytkownik zobaczy odpowiednie pytanie. Token dostępu, który otrzymujesz od Google, umożliwia dostęp do wszystkich interfejsów API związanych z zakresami dostępu, o który prosisz i które zostały Ci przyznane.
Odśwież tokeny
W prośbie o dostęp do interfejsu API możesz poprosić o zwrócenie tokena odświeżania podczas giełdy code
. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy nie ma w niej użytkownika. Aby zażądać tokena odświeżania, dodaj ustaw parametr access_type
na offline
w żądaniu uwierzytelniania.
Uwagi:
- Token odświeżania możesz przechowywać w bezpieczny i trwały sposób, bo token odświeżania możesz uzyskać tylko za pierwszym razem, gdy wykonasz przepływ wymiany kodu.
- Obowiązują pewne limity liczby wystawionych tokenów odświeżania: jeden limit na kombinację klienta i użytkownika i jeden na użytkownika w przypadku wszystkich klientów. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, limity te mogą zostać osiągnięte i starsze tokeny odświeżania przestaną działać.
Więcej informacji znajdziesz w sekcji Odświeżanie tokena dostępu (dostęp offline).
Prośba o ponowną zgodę
Możesz poprosić użytkownika o ponowną autoryzację aplikacji, ustawiając parametr prompt
na consent
w żądaniu uwierzytelniania. Jeśli dodasz prompt=consent
, ekran zgody będzie wyświetlany za każdym razem, gdy Twoja aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przyznane projektowi z użyciem interfejsów API Google. Z tego względu uwzględniaj prompt=consent
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
W tabeli poniżej znajdziesz pełniejszy opis parametrów akceptowanych przez interfejs Google OAuth 2.0 API.
Parametr | Wymagany | Opis |
---|---|---|
client_id |
(Wymagane) | Ciąg identyfikatora klienta uzyskany z Credentials page API Consolezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
nonce |
(Wymagane) | Losowa wartość generowana przez Twoją aplikację, która włącza ochronę przed ponownym odtworzeniem. |
response_type |
(Wymagane) | Jeśli wartość to code , uruchamia podstawowy przepływ kodu autoryzacji, wymagając dostępu do punktu końcowego tokena POST w celu uzyskania tokenów. Jeśli wartość to token id_token lub id_token token , uruchamia przepływ niejawny, co wymaga użycia JavaScriptu w identyfikatorze URI przekierowania w celu pobrania tokenów z identyfikatora #fragment identyfikatora #fragment . |
redirect_uri |
(Wymagane) | Określa, dokąd jest wysyłana odpowiedź. Wartość tego parametru musi być dokładnie taka sama jak jedna z wartości autoryzowanego przekierowania ustawionych w interfejsie API Console Credentials page (łącznie ze schematem HTTP lub HTTPS, wielkością liter i na końcu „/”, jeśli występuje). |
scope |
(Wymagane) | Parametr zakresu musi zaczynać się od wartości Jeśli wartość zakresu Jeśli wartość zakresu Oprócz zakresów specyficznych dla OpenID argument zakresu może też zawierać inne wartości zakresów. Wszystkie wartości zakresów muszą być rozdzielone spacjami. Jeśli na przykład chcesz uzyskać dostęp do poszczególnych plików na Dysku Google użytkownika, parametr zakresu może wyglądać tak: Więcej informacji o dostępnych zakresach znajdziesz w artykule na temat zakresów OAuth 2.0 dla interfejsów API Google i w dokumentacji interfejsu API Google, którego chcesz używać. |
state |
(Opcjonalne, ale zdecydowanie zalecane) | Nieprzejrzysty ciąg znaków przesyłany w obrębie protokołu, tzn. jest zwracany jako parametr URI w przepływie podstawowym oraz w identyfikatorze URI Funkcja |
access_type |
(Opcjonalne) | Dozwolone wartości to offline i online . Efekt jest udokumentowany w sekcji Dostęp offline. Jeśli żądanie tokena dostępu jest wysyłane, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość offline . |
display |
(Opcjonalne) | Wartość ASCII określająca sposób, w jaki serwer autoryzacji wyświetla strony interfejsu uwierzytelniania i uzyskiwania zgody użytkownika. Te wartości są określone i akceptowane przez serwery Google, ale nie mają żadnego wpływu na ich działanie: page , popup , touch i wap . |
hd |
(Opcjonalne) | Usprawnij proces logowania się na kontach należących do organizacji Google Cloud. Podając domenę organizacji Google Cloud (na przykład mycollege.edu), możesz wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby przeprowadzić optymalizację pod kątem kont organizacji Google Cloud, a nie tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki ( Nie korzystaj z tej optymalizacji UI, aby kontrolować, kto ma dostęp do Twojej aplikacji, ponieważ żądania po stronie klienta można modyfikować. Pamiętaj, aby validate, czy zwrócony token identyfikatora zawiera wartość żądania |
include_granted_scopes |
(Opcjonalne) | Jeśli podasz wartość true , a żądanie autoryzacji zostanie udzielone, autoryzacja będzie obejmować wszystkie wcześniejsze autoryzacje przyznane tej kombinacji użytkownika i aplikacji dla innych zakresów. Patrz sekcja Autoryzacja przyrostowa.
Pamiętaj, że w procesie Zainstalowana aplikacja nie można przeprowadzić autoryzacji przyrostowej. |
login_hint |
(Opcjonalne) | Gdy aplikacja będzie wiedzieć, którego użytkownika próbuje uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Przekazanie tej podpowiedzi powoduje wyłączenie funkcji wyboru kont i powoduje wstępne wypełnienie pola adresu e-mail w formularzu logowania lub wybranie odpowiedniej sesji (jeśli użytkownik korzysta z wielokrotnego logowania), co pozwala uniknąć problemów, gdy aplikacja loguje się na niewłaściwym koncie użytkownika.
Wartością może być adres e-mail lub ciąg sub , który jest odpowiednikiem identyfikatora Google użytkownika. |
prompt |
(Opcjonalne) | Lista rozdzielonych spacjami wartości ciągów określających, czy serwer autoryzacji prosi użytkownika o ponowne uwierzytelnienie i uzyskanie zgody użytkownika. Możliwe wartości:
Jeśli nie podasz żadnej wartości, a użytkownik nie autoryzował wcześniej dostępu, wyświetli się ekran zgody. |
Weryfikowanie tokena tożsamości
Musisz zweryfikować wszystkie tokeny identyfikacyjne na swoim serwerze, chyba że wiesz, że pochodzą bezpośrednio od Google. Na przykład serwer musi weryfikować wszystkie tokeny identyfikacyjne, które otrzymuje od aplikacji klienckich.
Oto typowe sytuacje, w których możesz wysłać tokeny identyfikacyjne na swój serwer:
- Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny tożsamości wskazują konkretnego użytkownika wysyłającego żądanie i klienta, któremu przyznano token tożsamości.
Tokeny tożsamości są poufne i w przypadku ich przechwycenia mogą zostać niewłaściwie użyte. Musisz się upewnić, że te tokeny są obsługiwane w bezpieczny sposób, przesyłając je tylko przez HTTPS i tylko za pomocą danych POST lub w nagłówkach żądań. Jeśli przechowujesz na serwerze tokeny tożsamości, musisz też bezpiecznie je przechowywać.
Jedną z zalet tokenów tożsamości jest możliwość przekazywania ich między różnymi komponentami aplikacji. Tokeny te mogą używać tokena identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Zanim jednak użyjesz informacji z tokena identyfikatora lub polegaj na nich jako twierdzenie o uwierzytelnieniu użytkownika, musisz je zweryfikować.
Weryfikacja tokena tożsamości składa się z kilku etapów:
- Sprawdź, czy token tożsamości został poprawnie podpisany przez wydawcę. Tokeny wydane przez Google są podpisane jednym z certyfikatów znalezionych w identyfikatorze URI określonym w wartości metadanych
jwks_uri
w dokumencie Discovery. - Sprawdź, czy wartość żądania
iss
w tokenie identyfikatora jest równahttps://accounts.google.com
lubaccounts.google.com
. - Sprawdź, czy wartość żądania
aud
w tokenie identyfikatora jest równa identyfikatorowi klienta Twojej aplikacji. - Sprawdź, czy czas wygaśnięcia (roszczenie
exp
) tokena identyfikatora nie minął. - Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora zawiera deklarację
hd
odpowiadającą akceptowanej domenie powiązanej z organizacją Google Cloud.
Kroki 2–5 obejmują tylko porównania ciągów znaków i dat, które są dość proste, więc nie będziemy ich szczegółowo omawiać.
Pierwszy etap jest bardziej złożony i obejmuje sprawdzanie podpisu kryptograficznego. Do debugowania możesz użyć punktu końcowego tokeninfo
Google, aby porównać wyniki z przetwarzaniem lokalnym zaimplementowanym na Twoim serwerze lub urządzeniu. Załóżmy, że wartość tokena tożsamości to XYZ123
. W takim przypadku należy wykluczyć identyfikator URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Jeśli podpis tokena jest prawidłowy, odpowiedzią jest ładunek JWT w formie zdekodowanego obiektu JSON.
Punkt końcowy tokeninfo
jest przydatny do debugowania, ale w środowisku produkcyjnym pobiera klucze publiczne Google z punktu końcowego kluczy i przeprowadź weryfikację lokalnie. Identyfikator URI kluczy należy pobrać z dokumentu Discovery przy użyciu wartości metadanych jwks_uri
. Żądania wysyłane do punktu końcowego debugowania mogą być ograniczone lub w inny sposób powodować przejściowe błędy.
Google zmienia swoje klucze publiczne rzadko, więc możesz je buforować za pomocą dyrektyw dotyczących pamięci podręcznej w odpowiedzi HTTP. W większości przypadków możesz przeprowadzić lokalną weryfikację znacznie wydajniej niż przy użyciu punktu końcowego tokeninfo
. Ta weryfikacja wymaga pobrania i analizowania certyfikatów oraz wykonywania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Aby to zrobić, dostępne są sprawdzone biblioteki w wielu różnych językach (zobacz jwt.io).
Uzyskiwanie informacji o profilu użytkownika
Aby uzyskać dodatkowe informacje o profilu użytkownika, możesz użyć tokena dostępu (otrzymywanego przez aplikację podczas procesu uwierzytelniania) i standardu OpenID Connect:
Aby zapewnić zgodność z OpenID, w prośbie o uwierzytelnienie musisz uwzględnić wartości zakresu
openid profile
.Jeśli chcesz uwzględniać adres e-mail użytkownika, możesz określić dodatkową wartość zakresu
email
. Aby określić zarównoprofile
, jak iemail
, możesz umieścić ten parametr w identyfikatorze URI żądania uwierzytelniania:scope=openid%20profile%20email
- Dodaj token dostępu do nagłówka autoryzacji i wyślij do punktu końcowego informacji o użytkowniku żądanie HTTPS
GET
, które trzeba pobrać z dokumentu Discovery za pomocą wartości metadanychuserinfo_endpoint
. Odpowiedź z informacjami o użytkowniku zawiera informacje o użytkowniku (zgodnie z opisem wOpenID Connect Standard Claims
) oraz wartość metadanychclaims_supported
dokumentu Discovery. Użytkownicy lub ich organizacje mogą podać lub zablokować określone pola, więc możesz nie uzyskać informacji o niektórych polach z autoryzowanych zakresów dostępu.
Dokument Odkrywanie
Protokół OpenID Connect wymaga używania wielu punktów końcowych do uwierzytelniania użytkowników oraz do wysyłania żądań zasobów, w tym tokenów, informacji o użytkowniku i kluczy publicznych.
W celu uproszczenia implementacji i zwiększenia elastyczności OpenID Connect pozwala na użycie „dokumentu Discovery” – dokumentu JSON znalezionego w dobrze znanej lokalizacji zawierającej pary klucz-wartość zawierające szczegóły konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokena, unieważnienia, informacje o użytkowniku i punkty końcowe kluczy publicznych. Dokument Discovery dla usługi Google OpenID Connect można pobrać z:
https://accounts.google.com/.well-known/openid-configuration
Aby korzystać z usług Google OpenID Connect, musisz na stałe umieścić w aplikacji identyfikator URI dokumentu Discovery (https://accounts.google.com/.well-known/openid-configuration
).
Aplikacja pobiera dokument, stosuje w odpowiedzi reguły buforowania, a potem w razie potrzeby pobiera z niego identyfikatory URI punktów końcowych. Na przykład, aby uwierzytelnić użytkownika, kod pobierze wartość metadanych authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
w przykładzie poniżej) jako podstawowy identyfikator URI żądań uwierzytelniania wysyłanych do Google.
Oto przykład takiego dokumentu; nazwy pól są określone w OpenID Connect Discovery 1.0 (ich znaczenie można znaleźć w tym dokumencie). Wartości mają charakter czysto poglądowy i mogą się zmienić, chociaż są kopiowane z najnowszej wersji dokumentu Google Discovery:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
Możesz uniknąć przesyłania ruchu w obie strony HTTP, umieszczając w pamięci podręcznej wartości z dokumentu Discovery. Używane są standardowe nagłówki buforowania HTTP i należy je respektować.
Biblioteki klienta
Te biblioteki klienta ułatwiają wdrażanie OAuth 2.0 dzięki integracji z popularnymi platformami:
- Biblioteka klienta interfejsów API Google do języka Java
- Biblioteka klienta interfejsów API Google do języka Python
- Biblioteka klienta interfejsów API Google dla języka .NET
- Biblioteka klienta interfejsów API Google dla języka Ruby
- Biblioteka klienta interfejsów API Google do języka PHP
- Biblioteka OAuth 2.0 dla narzędzi internetowych Google
- Zestaw narzędzi Google dla kontrolerów OAuth 2.0 dla komputerów Mac
Zgodność z OpenID Connect
System uwierzytelniania Google OAuth 2.0 obsługuje wymagane funkcje ze specyfikacji OpenID Connect Core. Każdy klient, który został zaprojektowany do pracy z OpenID Connect, powinien z nią współpracować (z wyjątkiem obiektu żądania OpenID).