Interfejsy API Google OAuth 2.0 mogą być używane zarówno do uwierzytelniania, jak i autoryzacji. W tym dokumencie opisano naszą implementację protokołu OAuth 2.0 na potrzeby uwierzytelniania, która jest zgodna ze specyfikacją OpenID Connect i ma certyfikat OpenID. Do tej usługi ma też zastosowanie dokumentacja o używaniu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google. Jeśli chcesz poznać ten protokół interaktywnie, zalecamy skorzystanie z Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą Stack Overflow, oznacz swoje pytania tagiem „google-oauth”.
Konfigurowanie protokołu OAuth 2.0
Zanim 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 w celu uzyskania danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania i (opcjonalnie) dostosować informacje o marce widoczne dla użytkowników na ekranie zgody użytkownika. Możesz też użyć API Console do utworzenia konta usługi, włączenia płatności, skonfigurowania filtrowania i wykonania innych zadań. 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.
要查看给定OAuth 2.0凭据的客户端ID和客户端密钥,请单击以下文本: 选择凭据 。在打开的窗口中,选择您的项目和所需的凭证,然后单击“ 查看” 。
或者,从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥:
- Go to the Credentials page.
- 单击您的凭证名称或铅笔( create )图标。您的客户ID和密码位于页面顶部。
Ustaw identyfikator URI przekierowania
Identyfikator URI przekierowania ustawiony w API Console określa, gdzie Google wysyła odpowiedzi na Twoje żądania uwierzytelniania.
要创建,查看或编辑给定OAuth 2.0凭据的重定向URI,请执行以下操作:
- Go to the Credentials page.
- 在页面的OAuth 2.0客户端ID部分中,点击一个凭据。
- 查看或编辑重定向URI。
如果“凭据”页面上没有OAuth 2.0客户端ID部分,则您的项目没有OAuth凭据。要创建一个,点击创建凭证 。
Dostosowywanie ekranu zgody użytkownika
Dla użytkowników funkcja uwierzytelniania OAuth 2.0 obejmuje ekran zgody z opisem informacji udostępnianych przez użytkownika oraz obowiązujących warunków. Na przykład podczas logowania użytkownik może zostać poproszony o przyznanie aplikacji dostępu do swojego adresu e-mail i podstawowych informacji o koncie. Prosisz o dostęp do tych informacji za pomocą parametru scope
, który znajduje się w prośbie o uwierzytelnienie aplikacji. Możesz też używać zakresów, aby prosić o dostęp do innych interfejsów API Google.
Ekran zgody użytkownika zawiera też informacje dotyczące marki, takie jak nazwa produktu, logo i adres URL strony głównej. Kontrolujesz informacje o marce 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 to m.in. Google Identity Services 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 w dalszej części tego dokumentu, w których opisano przepływy żądań HTTP, które są dostępne w ramach dostępnych bibliotek.
Uwierzytelnianie użytkownika
Uwierzytelnienie użytkownika obejmuje uzyskanie tokena tożsamości i jego weryfikację. Tokeny tożsamości to ustandaryzowane funkcja OpenID Connect, która służy do udostępniania potwierdzeń tożsamości w internecie.
Najczęściej stosowane metody uwierzytelniania użytkownika i uzyskiwania tokena identyfikatora nazywane są przepływem „serwera” i „przepływem niejawnym”. Przepływ po stronie serwera pozwala serwerowi backendu aplikacji zweryfikować tożsamość osób korzystających 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 mieć bezpośredni dostęp do interfejsów API, a nie przez 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 związane z obsługą i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć proces niejawny, zalecamy użycie usług tożsamości Google.
Przepływ serwera
Skonfiguruj aplikację w: API Console, aby umożliwić korzystanie z tych protokołów i uwierzytelnianie użytkowników. Gdy użytkownik próbuje zalogować się przez Google, musisz:
- Utwórz token służący do zapobiegania oszustwom
- Wysyłanie żądania uwierzytelniania do Google
- Potwierdzanie tokena stanu zapobiegania fałszowaniu
- Exchange
code
na potrzeby tokena dostępu i tokena tożsamości - Uzyskiwanie informacji o użytkowniku za pomocą tokena tożsamości
- Uwierzytelnienie użytkownika
1. Utwórz token stanu do zapobiegania 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 dopasujesz ten unikalny token sesji do odpowiedzi uwierzytelniającej zwróconej przez usługę logowania Google OAuth, aby sprawdzić, czy użytkownik wysyła żądanie, a nie złośliwe oprogramowanie. Tokeny te są często nazywane tokenami sfałszowania żądania z innych witryn (CSRF).
Dobrym wyborem w przypadku tokena stanu jest ciąg składający się z około 30 znaków utworzony za pomocą wysokiej jakości generatora liczb losowych. Kolejny to hasz wygenerowany przez podpisanie niektórych zmiennych stanu sesji kluczem, który jest tajny w zapleczu.
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 uwierzytelniania do Google
Następnym krokiem jest utworzenie żądania HTTPS GET
z odpowiednimi parametrami identyfikatora URI.
Zwróć uwagę, że na wszystkich etapach tego procesu jest używany protokół HTTPS zamiast HTTP, ponieważ połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint
. W dalszej części prezentacji założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth
.
W przypadku żądania podstawowego podaj te parametry:
client_id
, które otrzymujesz z: API Console Credentials page .response_type
, który w podstawowym żądaniu przepływu kodu autoryzacji powinien mieć wartośćcode
. (Więcej informacji znajdziesz naresponse_type
).scope
, którego wartość w podstawowym żądaniu powinna wynosićopenid email
. (Więcej informacji znajdziesz nascope
).redirect_uri
powinien być punktem końcowym HTTP na serwerze, który będzie otrzymywać odpowiedź od Google. Wartość musi być dokładnie taka sama jak jeden z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany tutaj: 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, który nie służy do zapobiegania oszustwom, a także wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wraca do 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 adresulogin_hint
, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zatwierdzenie zwolnienia adresu e-mail użytkownika w Twojej aplikacji. Więcej informacji:login_hint
.- Parametr
hd
służy do optymalizacji procesu OpenID Connect dla użytkowników określonej domeny powiązanej z organizacją Google Workspace lub Cloud (więcej informacji znajdziesz na stroniehd
).
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órego wcześniej nie zatwierdziła.
3. Potwierdź token stanu zapobiegania fałszowaniu
Odpowiedź zostanie wysł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. 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. Wymień code
na token dostępu i token identyfikatora
Odpowiedź zawiera parametr code
, czyli 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 tej prezentacji założono, że punkt końcowy to https://oauth2.googleapis.com/token
. Żądanie musi zawierać w treści POST
te parametry:
Pola | |
---|---|
code |
Kod autoryzacji zwracany w wyniku wstępnego żądania. |
client_id |
Identyfikator klienta otrzymany z API Console Credentials page, 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 do określonego zasobu client_id , który jest podany w API Console
Credentials pagezgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania. |
grant_type |
To pole musi zawierać wartość authorization_code
zgodnie ze specyfikacją OAuth 2.0. |
Rzeczywiste żądanie może wyglądać tak:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Pomyślna odpowiedź na to żądanie zawiera te pola w tablicy JSON:
Pola | |
---|---|
access_token |
Token, który można wysłać do interfejsu API Google. |
expires_in |
Pozostały czas życia tokena dostępu w sekundach. |
id_token |
JWT zawierający informacje o tożsamości użytkownika podpisanego cyfrowo przez Google. |
scope |
Zakresy dostępu przyznane przez zasadę access_token w postaci listy ciągów znaków rozdzielonych spacjami (z uwzględnieniem wielkości liter). |
token_type |
Określa typ zwracanego tokena. Obecnie to pole zawsze ma wartość Bearer .
|
refresh_token |
(opcjonalnie)
To pole występuje tylko wtedy, gdy parametr |
5. Uzyskiwanie informacji o użytkowniku z tokena identyfikatora
Token identyfikatora to JWT (token sieciowy JSON), czyli kryptograficznie podpisany obiekt JSON zakodowany w standardzie Base64. Zazwyczaj ważne jest, aby weryfikować token tożsamości przed jego użyciem. Ponieważ jednak komunikujesz się bezpośrednio z Google przez niezależny kanał HTTPS i używasz tajnego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token faktycznie pochodzi od Google i jest prawidłowy. Jeśli serwer przekazuje token identyfikatora do innych komponentów aplikacji, bardzo ważne jest, aby pozostałe 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 analizowania wewnątrz pliku JSON, więc prawdopodobnie mimo to przejdziesz 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órych jest przeznaczony ten token tożsamości. Musi to być jeden z identyfikatorów klienta OAuth 2.0 Twojej aplikacji. |
exp |
zawsze | Data ważności, po której token tożsamości nie może zostać akceptowany. Wartość reprezentuje czas uniksowy (całkowita liczba sekund). |
iat |
zawsze | Czas wystawienia tokena tożsamości. Wartość reprezentowana w czasie uniksowym (całkowita liczba sekund). |
iss |
zawsze | Identyfikator wystawcy odpowiedzi. W przypadku tokenów tożsamości Google zawsze jest to https://accounts.google.com lub accounts.google.com . |
sub |
zawsze | Identyfikator użytkownika, unikalny 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 identyfikatora użytkownika. Maksymalna długość to 255 znaków ASCII z uwzględnieniem wielkości liter. |
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 prowadzącego. Ta deklaracja jest potrzebna tylko wtedy, gdy strona żądająca tokena identyfikatora nie jest taka sama jak grupa odbiorców tokena. W Google może tak być w przypadku aplikacji hybrydowych, gdy aplikacja internetowa i aplikacja na Androida mają inny protokół OAuth 2.0 client_id , ale korzystają z tego samego projektu interfejsów API Google. |
|
email |
Adres e-mail użytkownika. Podany tylko wtedy, gdy w żądaniu uwzględniono zakres email . Wartość tego roszczenia może nie być unikalna dla tego konta i z czasem może się zmieniać, dlatego nie używaj tej wartości jako podstawowego identyfikatora do powiązania
z Twoim wpisem użytkownika. Nie może też polegać na domenie deklaracji email do identyfikowania użytkowników organizacji Google Workspace lub Cloud. Zamiast tego użyj deklaracji hd . |
|
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 istnieje roszczenie name . |
|
given_name |
Imię lub nazwisko użytkownika. Może być podany, gdy istnieje roszczenie name . |
|
hd |
Domena powiązana z organizacją Google Workspace lub Cloud użytkownika. Podaje się tylko wtedy, gdy użytkownik należy do organizacji Google Cloud. Musisz zaznaczyć to deklarację, gdy ograniczasz dostęp do zasobu tylko do użytkowników z określonych domen. Brak takiego roszczenia oznacza, że konto nie należy do domeny hostowanej przez Google. | |
locale |
Język użytkownika określony za pomocą tagu języka BCP 47.
Może być podany, gdy istnieje roszczenie name . |
|
name |
Imię i nazwisko użytkownika w wyświetlanej formie. Może być podany, gdy:
Gdy dostępne są roszczenia |
|
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 być podany, gdy:
Gdy dostępne są roszczenia |
|
profile |
Adres URL strony profilu użytkownika. Może być podany, gdy:
Gdy dostępne są roszczenia |
6. Uwierzytelnij użytkownika
Po uzyskaniu informacji o użytkowniku z tokena identyfikatora wyślij zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik już istnieje w Twojej 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 go przekierować do procesu rejestracji nowych użytkowników. Możesz automatycznie zarejestrować użytkownika na podstawie informacji otrzymanych od Google lub możesz wstępnie wypełnić wiele wymaganych pól w formularzu rejestracyjnym. Oprócz informacji w tokenie identyfikatora możesz uzyskać dodatkowe informacje o profilach użytkowników w punktach końcowych profilu.
Tematy zaawansowane
W sekcjach poniżej znajdziesz bardziej szczegółowe informacje o interfejsie 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 potrzebne zakresy w prośbie 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 odpowiednią prośbę. Token dostępu, który otrzymujesz od Google, umożliwia Ci dostęp do wszystkich interfejsów API związanych z zakresami dostępu, o które prosisz i które zostały Ci przyznane.
Odśwież tokeny
W prośbie o dostęp do interfejsu API możesz poprosić o token odświeżania, który zostanie zwrócony podczas giełdy code
. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy nie ma użytkownika w aplikacji. Aby poprosić o token odświeżania, dodaj parametr access_type
do offline
w żądaniu uwierzytelnienia.
Uwagi:
- Pamiętaj, by przechowywać token odświeżania w bezpieczny i trwały, ponieważ token odświeżania możesz uzyskać tylko za pierwszym razem, gdy wykonasz proces wymiany kodu.
- Obowiązują limity liczby wystawionych tokenów odświeżania: jeden limit na kombinację klienta/użytkownika i jeden na użytkownika w przypadku wszystkich klientów. Jeśli Twoja aplikacja żąda zbyt wielu tokenów odświeżania, mogą zostać osiągnięte te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.
Więcej informacji znajdziesz w sekcji o odświeżaniu tokena dostępu (dostęp offline).
Proszenie o ponowne wyrażenie zgody
Możesz poprosić użytkownika o ponowną autoryzację aplikacji, ustawiając parametr prompt
na consent
w prośbie o uwierzytelnienie. Jeśli dołączony jest prompt=consent
, ekran zgody jest wyświetlany za każdym razem, gdy Twoja aplikacja żą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.
Więcej informacji o parametrze prompt
znajdziesz w sekcji prompt
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 | Wymagane | 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 odtwarzaniem. |
response_type |
(Wymagane) | Jeśli wartość to code , uruchamia podstawowy przepływ kodu autoryzacji, wymagający POST w punkcie końcowym tokena w celu uzyskania tokenów. Jeśli wartość to token id_token lub id_token token , uruchamia proces niejawny, co wymaga użycia JavaScriptu w identyfikatorze URI przekierowania w celu pobrania tokenów z identyfikatora #fragment identyfikatora URI. |
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 autoryzowanych przekierowania ustawionych w ramach funkcji API Console Credentials page (łącznie ze schematem HTTP lub HTTPS, wielkością liter oraz końcowym znakiem „/”, jeśli występuje). |
scope |
(Wymagane) | Parametr zakresu musi zaczynać się od wartości Jeśli wartość zakresu Jeśli wartość zakresu Oprócz tych zakresów związanych z identyfikatorem 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: Informacje o dostępnych zakresach znajdziesz w artykule na temat zakresów protokołu OAuth 2.0 dla interfejsów API Google oraz w dokumentacji interfejsu API Google, którego chcesz używać. |
state |
(Opcjonalne, ale zdecydowanie zalecane) | Nieprzejrzysty ciąg znaków, który jest zwracany w obie strony protokołu, czyli jest zwracany jako parametr URI w przepływie podstawowym oraz w identyfikatorze URI Interfejs |
access_type |
(Opcjonalne) | Dozwolone wartości to offline i online . Efekt jest opisany w sekcji Dostęp offline. Jeśli wymagane jest żądanie tokena dostępu, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość offline . |
display |
(Opcjonalne) | Wartość ciągu ASCII określająca sposób wyświetlania przez serwer autoryzacji stron interfejsu uwierzytelniania i prośby o zgodę na przetwarzanie danych. 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) | usprawnić proces logowania się na konta należące do organizacji Google Cloud; Uwzględnij domenę organizacji Google Cloud (na przykład mycollege.edu), aby wskazać, że interfejs wyboru konta powinien być zoptymalizowany pod kątem kont w tej domenie. Aby przeprowadzić optymalizację pod kątem kont organizacji w Google Cloud, a nie tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki ( Nie korzystaj z tej optymalizacji UI do kontrolowania, kto może korzystać z 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 ten parametr jest podany o wartości true , a żądanie autoryzacji zostanie przyznane, autoryzacja będzie obejmować wszystkie wcześniejsze autoryzacje przyznane tej kombinacji użytkownika i aplikacji na potrzeby innych zakresów. Więcej informacji znajdziesz w sekcji Autoryzacja przyrostowa.
Pamiętaj, że w ramach procesu Zainstalowana aplikacja nie można przeprowadzić autoryzacji przyrostowej. |
login_hint |
(Opcjonalne) | Gdy aplikacja będzie wiedzieć, który użytkownik próbuje się uwierzytelnić, może podać ten parametr jako wskazówkę dla serwera uwierzytelniania. Przekazanie tej podpowiedzi powoduje wyłączenie funkcji wyboru konta i powoduje wstępne wypełnienie pola e-mail w formularzu logowania lub wybranie odpowiedniej 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 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 zgodę na przetwarzanie danych. 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 tożsamości na swoim serwerze, chyba że wiesz, że pochodzą bezpośrednio od Google. Na przykład Twój serwer musi weryfikować jako autentyczne tokeny tożsamości, które otrzymuje z aplikacji klienckich.
Oto typowe sytuacje, w których możesz wysyłać tokeny identyfikacyjne na swój serwer:
- Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny tożsamości informują o konkretnym użytkowniku wysyłającym żądanie i kliencie, któremu przyznano ten token.
Tokeny tożsamości są poufne i w przypadku ich przechwycenia mogą zostać niewłaściwie użyte. Musisz upewnić się, ż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 na swoim serwerze przechowujesz tokeny tożsamości, musisz też je bezpiecznie przechowywać.
Jedną z zalet tokenów tożsamości jest możliwość przekazywania ich do różnych komponentów aplikacji. Komponenty te mogą wykorzystać token identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Zanim jednak będzie można używać informacji z tokena identyfikatora lub polegać na nich jako o uwierzytelnieniach uwierzytelnionych przez użytkownika, musisz je zweryfikować.
Weryfikacja tokena tożsamości składa się z kilku etapów:
- Sprawdź, czy wydawca prawidłowo podpisał token tożsamości. 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ść deklaracji
aud
w tokenie identyfikatora jest równa identyfikatorowi klienta Twojej aplikacji. - Sprawdź, czy termin ważności (roszczenie
exp
) tokena tożsamości 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ą w 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 skomplikowany i obejmuje sprawdzanie podpisu kryptograficznego. Na potrzeby debugowania możesz użyć punktu końcowego tokeninfo
Google, aby porównać dane z przetwarzaniem lokalnym zaimplementowanym na serwerze lub urządzeniu. Załóżmy, że wartość tokena tożsamości wynosi XYZ123
. W takim przypadku należy usunąć odniesienie do identyfikatora URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Jeśli podpis tokena jest prawidłowy, odpowiedzią jest ładunek JWT w formularzu 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 za pomocą wartości metadanych jwks_uri
. Żądania wysyłane do punktu końcowego debugowania mogą być ograniczane lub w inny sposób mogą powodować przejściowe błędy.
Google rzadko zmienia swoje klucze publiczne, dlatego możesz je buforować, korzystając z instrukcji buforowania odpowiedzi HTTP. W większości przypadków lokalna weryfikacja przeprowadzana jest o wiele wydajniej niż przy użyciu punktu końcowego tokeninfo
. Ta weryfikacja wymaga pobrania i analizy certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Aby było to możliwe, istnieją dobrze zdebugowane biblioteki w wielu różnych językach (patrz 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, aby był uwzględniony adres e-mail użytkownika, możesz określić dodatkową wartość zakresu
email
. Aby określić zarównoprofile
, jak iemail
, możesz uwzględnić ten parametr w identyfikatorze URI żądania uwierzytelniania:scope=openid%20profile%20email
- Dodaj token dostępu do nagłówka autoryzacji i wyślij żądanie HTTPS
GET
do punktu końcowego informacji o użytkowniku, które musisz pobrać z dokumentu Discovery za pomocą wartości metadanychuserinfo_endpoint
. Odpowiedź dotycząca informacji o użytkowniku zawiera informacje o użytkowniku (zgodnie z opisem w sekcjiOpenID Connect Standard Claims
) i wartość metadanychclaims_supported
dokumentu Discovery. Użytkownicy lub ich organizacje mogą podać lub wstrzymać określone pola, więc możesz nie uzyskać informacji o niektórych polach dla autoryzowanych zakresów dostępu.
Dokument Discovery
Protokół OpenID Connect wymaga używania wielu punktów końcowych do uwierzytelniania użytkowników i żą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 korzystanie z dokumentu Discovery – dokumentu JSON znajdującego się w dobrze znanej lokalizacji, zawierającego pary klucz-wartość zawierające szczegółowe informacje o konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokena, unieważnienia, informacje o użytkowniku i punktów końcowych 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 zakodować w swojej 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 punktu końcowego. Aby na przykład uwierzytelnić użytkownika, kod pobiera 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 znajdziesz w tym dokumencie). Wartości mają charakter czysto poglądowy i mogą się zmieniać, chociaż 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" ] }
Możesz uniknąć obiegu protokołu HTTP, buforując wartości z dokumentu wykrywania. Używane są standardowe nagłówki buforowania HTTP i należy je respektować.
Biblioteki klienta
Te biblioteki klienta upraszczają implementację protokołu 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 .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 na potrzeby narzędzi internetowych Google
- Zestaw narzędzi Google dla kontrolerów OAuth 2.0 na komputery 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 działania z OpenID Connect, powinien z nią współpracować (z wyjątkiem obiektu żądania OpenID).