Interfejsy API Google OAuth 2.0 mogą być używane do uwierzytelniania i autoryzacji. Ten dokument opisuje nasz sposób uwierzytelniania OAuth 2.0 zgodny ze specyfikacją OpenID Connect oraz certyfikat OpenID. Zastosowana jest również dokumentacja o używaniu dostępu przez OAuth 2.0 do interfejsów API Google. Jeśli chcesz korzystać z tego protokołu w interaktywny sposób, zalecamy stronę Google OAuth 2.0 Playground. Aby uzyskać pomoc dotyczącą usługi Stack Overflow, oznacz swoje pytania tagiem „google-oauth”.
Konfigurowanie protokołu OAuth 2.0
Zanim Twoja aplikacja będzie mogła używać systemu uwierzytelniania Google OAuth 2.0 do logowania się użytkowników, musisz skonfigurować projekt w Google API Console uzyskiwaniu danych logowania OAuth 2.0, ustawić identyfikator URI przekierowania oraz (opcjonalnie) dostosować informacje o marce, które użytkownicy zobaczą 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 wykonywać 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, gdzie Google wysyła odpowiedzi na żądania uwierzytelniania.
To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:
- Go to the Credentials page.
- In the OAuth 2.0 client IDs section of the page, click a credential.
- View or edit the redirect URIs.
If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.
Dostosowywanie ekranu zgody użytkownika
W przypadku użytkowników uwierzytelnianie OAuth 2.0 obejmuje ekran zgody, który opisuje informacje udostępniane przez użytkownika oraz obowiązujące warunki. Na przykład po zalogowaniu się użytkownik może zobaczyć prośbę 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 Twoja aplikacja uwzględnia w żądaniu uwierzytelniania. Zakresy możesz też wykorzystać, aby żądać dostępu do innych interfejsów Google API.
Na ekranie zgody użytkownika są też wyświetlane informacje o marce, takie jak nazwa produktu, logo i adres URL strony głównej. Ty zarządzasz informacjami 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 .
Podane niżej okno z prośbą o zgodę pokazuje, co zobaczy użytkownik po połączeniu w żądaniu zakresów protokołu OAuth 2.0 i Dysku Google. To ogólne okno dialogowe zostało utworzone za pomocą platformy Google OAuth 2.0 Playground, więc nie zawiera informacji o marce, które byłyby 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 dotyczących uwierzytelniania użytkowników i uzyskiwania 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 w pozostałej części tego dokumentu, które opisują przepływy żądań HTTP, które udostępniają przestarzałe biblioteki.
Uwierzytelnianie użytkownika
Uwierzytelnianie użytkownika wymaga jego uzyskania i zweryfikowania. Tokeny identyfikatorów to standardowa funkcja OpenID Connect przeznaczona do udostępniania potwierdzeń tożsamości w internecie.
Najczęściej stosowanym sposobem uwierzytelniania użytkowników i uzyskiwania tokena identyfikatora jest proces „serwer” i „domyślny”. Przepływ serwera pozwala serwerowi backendu aplikacji na weryfikację tożsamości osoby przy użyciu przeglądarki lub urządzenia mobilnego. Przepływ niejawny jest używany, gdy aplikacja po stronie klienta (zazwyczaj aplikacja JavaScript działająca w przeglądarce) potrzebuje dostępu do interfejsów API bezpośrednio zamiast przez serwer backendu.
Ten dokument zawiera opis sposobu wykonywania procesu na serwerze w celu uwierzytelniania użytkownika. Przepływ niejawny jest znacznie bardziej skomplikowany ze względu na zagrożenia związane z obsługą i używaniem tokenów po stronie klienta. Jeśli chcesz wdrożyć komunikat pośredni, zalecamy użycie usług tożsamości Google.
Przepływ serwera
Pamiętaj, aby skonfigurować aplikację w: API Console, aby umożliwić jej korzystanie z tych protokołów i uwierzytelnianie użytkowników. Gdy użytkownik próbuje zalogować się przez Google, musisz:
- Tworzenie tokena stanu antyfałszerstwa
- Wyślij do Google prośbę o uwierzytelnienie
- Potwierdzanie tokena stanu fałszowania
- Wymień
code
na token dostępu i token tożsamości - Pobieranie informacji o użytkowniku z tokena identyfikatora
- Uwierzytelnianie użytkownika
1. Tworzenie tokena stanu antyfałszerstwa
Musisz chronić bezpieczeństwo użytkowników, zapobiegając atakom polegającym na fałszowaniu wyników. Pierwszym krokiem jest utworzenie unikalnego tokena sesji, który zachowuje stan między aplikacją a klientem użytkownika. Później dopasowujesz ten unikalny token sesji do odpowiedzi uwierzytelniania zwróconej przez usługę logowania Google OAuth, aby potwierdzić, że użytkownik wysyła żądanie, a nie złośliwe oprogramowanie. Tokeny te są często określane jako tokeny fałszowania żądań z innej witryny (CSRF).
Jednym z porządków w przypadku tokena stanu jest ciąg 30 znaków utworzony przy użyciu wysokiej jakości generatora liczb losowych. Inny jest skrót wygenerowany przez podpisanie niektórych zmiennych stanu sesji kluczem, który jest tajny w backendzie.
Ten 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 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
W następnym kroku utwórz żądanie HTTPS GET
z odpowiednimi parametrami URI.
Pamiętaj, że na każdym etapie tego procesu używane jest HTTPS, a nie HTTP. Połączenia HTTP są odrzucane. Podstawowy identyfikator URI należy pobrać z dokumentu Discovery za pomocą wartości metadanych authorization_endpoint
. W poniższej dyskusji założono, że podstawowy identyfikator URI to https://accounts.google.com/o/oauth2/v2/auth
.
W przypadku żądania podstawowego określ te parametry:
client_id
uzyskany z API ConsoleCredentials page.response_type
, które w podstawowym żądaniu kodu autoryzacji powinno mieć postaćcode
. (Więcej informacji znajdziesz na stronieresponse_type
).scope
, które w podstawowym żądaniu powinno mieć wartośćopenid email
. (Więcej informacji znajdziesz nascope
).redirect_uri
powinien być punktem końcowym HTTP na serwerze, który będzie otrzymywać odpowiedzi od Google. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials page. Jeśli ta wartość nie będzie pasować do autoryzowanego identyfikatora URI, żądanie zakończy się niepowodzeniem i wyświetli się błądredirect_uri_mismatch
.- Pole
state
powinno zawierać wartość tokena zapobiegającego fałszowaniu identyfikatorów sesji oraz wszelkie inne informacje potrzebne do odzyskania kontekstu, gdy użytkownik wróci do aplikacji, np. początkowy adres URL. (Więcej informacji znajdziesz nastate
). nonce
to losowa wartość generowana przez aplikację, która umożliwia ochronę przed ponownym odtwarzaniem, jeśli jest włączona.login_hint
może być adresem e-mail użytkownika lub ciągiem znakówsub
, który jest odpowiednikiem identyfikatora Google użytkownika. Jeśli nie podasz danychlogin_hint
, a użytkownik jest obecnie zalogowany, na ekranie zgody pojawi się prośba o zgodę na zwolnienie adresu e-mail użytkownika Twojej aplikacji. (Więcej informacji:login_hint
).- Użyj parametru
hd
, aby zoptymalizować procedurę OpenID Connect dla użytkowników określonej domeny powiązanej z organizacją Google Cloud. (Więcej informacji znajdziesz na stroniehd
).
Oto przykład pełnego identyfikatora URI uwierzytelniania OpenID Connect z podziałami wiersza i miejscami do odczytania:
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 będzie prosić o nowe informacje na ich temat lub z prośbą o dostęp do konta, który wcześniej nie został zatwierdzony.
3. Potwierdź token stanu fałszowania
Odpowiedź jest wysyłana do redirect_uri
wskazanego 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ć, czy state
otrzymany od Google jest zgodny z tokenem sesji utworzonym w kroku 1. Ta weryfikacja w obie strony pomaga upewnić się, że żądanie wykonuje użytkownik, a nie złośliwy skrypt.
Ten kod potwierdza 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 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 tożsamości
Odpowiedź zawiera parametr code
– jednorazowy kod autoryzacji, który Twój serwer może wymienić na token dostępu i token tożsamości. Serwer dokonuje tej wymiany, wysyłając żądanie HTTPS POST
. Żądanie POST
jest wysyłane do punktu końcowego tokena, który należy pobrać z dokumentu wykrywania za pomocą wartości metadanych token_endpoint
. W tej dyskusji zakładamy, że punkt końcowy to https://oauth2.googleapis.com/token
. Żądanie musi zawierać te parametry w treści POST
:
Pola | |
---|---|
code |
Kod autoryzacji zwracany z wstępnego żądania. |
client_id |
Identyfikator klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
client_secret |
Tajny klucz klienta uzyskany z API ConsoleCredentials pagezgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
redirect_uri |
Autoryzowany identyfikator URI przekierowania dla danego atrybutu client_id określony w API ConsoleCredentials page, zgodnie z opisem w sekcji Ustawianie identyfikatora URI przekierowania. |
grant_type |
To pole musi zawierać wartość authorization_code zdefiniowaną w specyfikacji OAuth 2.0. |
Rzeczywiste żądanie może wyglądać 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 następujące 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 do 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 przyznawane przez access_token mają postać listy ciągów znaków rozdzielanych spacjami, w których jest rozróżniana wielkość liter. |
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 w żądaniu uwierzytelniania parametr |
5. Uzyskiwanie informacji o użytkowniku z tokena tożsamości
Token identyfikatora to JWT (token sieciowy JSON), czyli zaszyfrowany kryptograficznie obiekt JSON zakodowany w standardzie Base64. Zwykle ważne jest, aby przed użyciem tokena identyfikatora zweryfikować go. Ponieważ komunikujesz się bezpośrednio z Google przez kanał HTTPS bez pośredników i używasz swojego klucza klienta do uwierzytelniania się w Google, możesz mieć pewność, że otrzymany token naprawdę pochodzi od Google i jest prawidłowy. Jeśli serwer przekazuje token identyfikatora do innych komponentów aplikacji, bardzo ważne jest, aby przed sprawdzeniem każdy z nich sprawdził token.
Większość bibliotek interfejsów API łączy weryfikację z procesem dekodowania wartości zakodowanych w formacie base64url i analizowania wewnątrz kodu JSON, więc prawdopodobnie ostatecznie okaże się, że token zostanie uruchomiony podczas uzyskiwania dostępu do tokenów.
Ładunek tokena tożsamości
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 identyfikatorów Google mogą zawierać te pola (nazywane deklaracjami):
Roszczenie | zapisana karta | Opis |
---|---|---|
aud |
zawsze | Lista odbiorców, do której jest przypisany 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ć przyjęty. Wartość jest podawana w czasie uniksowym (liczba całkowita w sekundach). |
iat |
zawsze | Godzina wydania tokena tożsamości. Wartość jest podawana w czasie uniksowym (liczba całkowita w sekundach). |
iss |
zawsze | Identyfikator wydawcy odpowiedzi. Zawsze https://accounts.google.com lub accounts.google.com w przypadku tokenów tożsamości Google. |
sub |
zawsze | Unikalny identyfikator użytkownika używany na wszystkich kontach 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 (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 wywoływany z wartością access_token w przepływie serwera, to twierdzenie jest zawsze uwzględniane. Tego roszczenia można użyć jako alternatywnego mechanizmu do ochrony przed atakami mających na celu fałszowanie żądań innych witryn, ale jeśli wykonasz krok 1 i krok 3, nie musisz weryfikować tokena dostępu. |
|
azp |
client_id autoryzowanego prowadzącego. To roszczenie jest potrzebne tylko wtedy, gdy strona żądająca tokena tożsamości różni się od jego odbiorców. Możliwe, że tak samo będzie w przypadku aplikacji hybrydowych, w których aplikacja internetowa i aplikacja na Androida mają inny protokół OAuth 2.0 (client_id ), ale współdzielą ten sam projekt interfejsów API Google. |
|
email |
Adres e-mail użytkownika. Ta wartość może nie być unikalna dla tego użytkownika i nie może być używana jako klucz podstawowy. Podane tylko wtedy, gdy zakres zawiera wartość zakresu email . |
|
email_verified |
Wartość to „prawda”, jeśli adres e-mail użytkownika został zweryfikowany. W przeciwnym razie „fałsz”. | |
family_name |
Nazwisko użytkownika. Można je podać, jeśli istnieje roszczenie name . |
|
given_name |
Imię użytkownika lub imię. Można je podać, jeśli istnieje roszczenie name . |
|
hd |
Domena powiązana z organizacją użytkownika Google Cloud. Podawana tylko wtedy, gdy użytkownik należy do organizacji Google Cloud. | |
locale |
Region użytkownika, podany za pomocą tagu języka BCP 47.
Wartość może być podana, jeśli istnieje roszczenie name . |
|
name |
Pełne imię i nazwisko użytkownika w wyświetlanej formie. Wartość może być podana, jeśli:
Jeśli masz |
|
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. Wartość może być podana, jeśli:
Jeśli masz |
|
profile |
Adres URL strony profilu użytkownika. Wartość może być podana, jeśli:
Jeśli masz |
6. Uwierzytelnianie użytkownika
Po uzyskaniu informacji o użytkowniku z tokena identyfikatora należy wykonać zapytanie do bazy danych użytkowników aplikacji. Jeśli użytkownik istnieje już w bazie danych, musisz rozpocząć sesję aplikacji dla tego użytkownika, jeśli wszystkie wymagania dotyczące logowania są spełnione przez odpowiedź interfejsu API Google.
Jeśli użytkownik nie istnieje w bazie danych użytkowników, musisz przekierować go do nowego procesu rejestracji. Możesz mieć możliwość automatycznego zarejestrowania użytkownika na podstawie informacji otrzymanych od Google, a dodatkowo możesz być w stanie wstępnie wypełnić wiele pól wymaganych w formularzu rejestracyjnym. Oprócz informacji z tokena tożsamości w naszych punktach końcowych profili użytkowników możesz znaleźć dodatkowe informacje o profilu użytkownika.
Tematy zaawansowane
Więcej informacji o interfejsie Google OAuth 2.0 API znajdziesz w poniższych sekcjach. Te informacje są przeznaczone dla deweloperów, którzy mają zaawansowane wymagania związane z uwierzytelnianiem i autoryzacją.
Dostęp do innych interfejsów API Google
Jedną z zalet uwierzytelniania OAuth 2.0 jest to, że aplikacja może uzyskiwać uprawnienia do korzystania z innych interfejsów Google API w imieniu użytkownika (np. YouTube, Dysk Google, Kalendarz lub Kontakty) w momencie uwierzytelniania użytkownika. Aby to zrobić, dołącz inne potrzebne zakresy w żądaniu uwierzytelniania wysłanym do Google. Aby na przykład dodać do żądania 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 korzystać ze wszystkich interfejsów API powiązanych z zakresami dostępu, których prośba została przyznana.
Odśwież tokeny
W swojej prośbie o dostęp do interfejsu API możesz poprosić o zwrot tokena odświeżania podczas wymiany code
. Token odświeżania zapewnia aplikacji stały dostęp do interfejsów API Google, gdy użytkownika nie ma w aplikacji. Aby zażądać tokena odświeżania, dodaj w żądaniu uwierzytelniania parametr access_type
na wartość offline
.
Uwagi:
- Token odświeżania należy przechowywać w bezpieczny i trwały sposób, ponieważ token odświeżania można uzyskać tylko po pierwszym uruchomieniu procesu wymiany kodu.
- Obowiązuje limit liczby tokenów odświeżania: jeden limit na jedną kombinację klienta i użytkownika oraz jeden na użytkownika we wszystkich klientach. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, mogą one zostać ograniczone, co sprawi, że starsze tokeny odświeżania przestaną działać.
Więcej informacji znajdziesz w artykule Odświeżanie tokena dostępu (dostęp offline).
Uzyskiwanie ponownej zgody
Możesz poprosić użytkownika o ponowne przyznanie uprawnień dostępu aplikacji, ustawiając parametr prompt
na consent
w żądaniu uwierzytelniania. Po uwzględnieniu obiektu prompt=consent
ekran zgody wyświetla się za każdym razem, gdy aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przyznane projektowi interfejsów API Google. Z tego powodu dodaj prompt=consent
tylko wtedy, gdy jest to konieczne.
Więcej informacji o parametrze prompt
znajdziesz w tabeli prompt
w tabeli Uwierzytelnianie identyfikatora URI.
Parametry identyfikatora uwierzytelniania
Poniższa tabela zawiera bardziej szczegółowe opisy parametrów akceptowanych przez interfejs API uwierzytelniania OAuth 2.0 Google.
Parametr | Wymagany | Opis |
---|---|---|
client_id |
(Wymagane) | Ciąg identyfikatora klienta uzyskany z API ConsoleCredentials page, zgodnie z opisem w sekcji Uzyskiwanie danych logowania OAuth 2.0. |
nonce |
(Wymagane) | Losowa wartość wygenerowana przez aplikację, która włącza ochronę przed ponownym odtwarzaniem. |
response_type |
(Wymagane) | Jeśli wartość to code , uruchamia podstawowy przepływ kodu autoryzacji, który wymaga POST do punktu końcowego tokena, aby uzyskać tokeny. Jeśli wartość to token id_token lub id_token token , uruchamia niejawny przepływ, który wymaga użycia kodu JavaScript w identyfikatorze URI przekierowania do pobierania tokenów z identyfikatora #fragment identyfikatora. |
redirect_uri |
(Wymagane) | Określa, gdzie jest wysyłana odpowiedź. Wartość tego parametru musi dokładnie odpowiadać jednej z autoryzowanych wartości przekierowania ustawionych w polu API ConsoleCredentials page (w tym schematu HTTP lub HTTPS, wielkości liter oraz końcowego znaku „/”, jeśli taki jest). |
scope |
(Wymagane) | Parametr zakresu musi zaczynać się od wartości Jeśli wartość zakresu Jeśli wartość zakresu Oprócz tych zakresów, argumentu zakres może też zawierać inne wartości zakresu. Wszystkie wartości zakresu muszą być rozdzielone spacjami. Jeśli np. chcesz mieć dostęp do pliku na Dysku Google użytkownika, parametr zakresu może wyglądać tak: Informacje o dostępnych zakresach znajdziesz w artykule Zakresy OAuth 2.0 dla interfejsów API Google lub w dokumentacji interfejsu Google API, której chcesz użyć. |
state |
(Opcjonalne, ale zdecydowanie zalecane) | Ciąg nieprzejrzysty, który jest przesyłane w obie strony zgodnie z protokołem, co oznacza, że jest zwracany jako parametr URI w procesie podstawowym oraz w identyfikatorze Funkcja |
access_type |
(Opcjonalne) | Dozwolone wartości to offline i online . Efekt jest udokumentowany w sekcji Dostęp offline. Jeśli zostanie zażądany token dostępu, klient nie otrzyma tokena odświeżania, chyba że zostanie określona wartość offline . |
display |
(Opcjonalne) | Wartość ciągu znaków ASCII określająca, w jaki sposób serwer autoryzacji wyświetla strony interfejsu uwierzytelniania i uzyskiwania zgody. Serwery Google obsługują te wartości, które są akceptowane i akceptowane oraz nie mają na nie wpływu: page , popup , touch i wap . |
hd |
(Opcjonalne) | Usprawnij proces logowania się na konta należące do organizacji Google Cloud. Dodają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 przeprowadzać optymalizację pod kątem kont organizacji w Google Cloud, a nie tylko jednej domeny organizacji Google Cloud, ustaw wartość gwiazdki ( Nie polegaj na tej optymalizacji interfejsu użytkownika, aby kontrolować, kto ma dostęp do Twojej aplikacji – żądania wysyłane po stronie klienta można modyfikować. Pamiętaj, aby sprawdzić, czy zwrócony token dokumentu tożsamości ma wartość roszczenia |
include_granted_scopes |
(Opcjonalne) | Jeśli ten parametr ma wartość true i prośba o autoryzację została przyznana, autoryzacja obejmuje wszystkie wcześniejsze autoryzacje dla tej kombinacji użytkownika i aplikacji w innych zakresach. Zobacz Autoryzacja przyrostowa.
Pamiętaj, że w procesie instalacji aplikacji nie można stopniowo zwiększać autoryzacji. |
login_hint |
(Opcjonalne) | 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łnienie pola e-maila w formularzu logowania lub wybranie odpowiedniej sesji (jeśli użytkownik korzysta z wielokrotnego logowania), co może pomóc w uniknięciu problemów, jeśli 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ągu określających, czy serwer autoryzacji prosi użytkownika o ponowne uwierzytelnienie i zgodę. Możliwe wartości:
Jeśli nie określisz żadnej wartości, a użytkownik nie wyraził wcześniej zgody na dostęp, zostanie wyświetlony ekran zgody. |
Weryfikowanie tokena tożsamości
Musisz zweryfikować wszystkie tokeny na serwerze, chyba że pochodzą one bezpośrednio od Google. Na przykład serwer musi zweryfikować jako autentyczne tokeny identyfikacyjne otrzymywane z aplikacji klienckich.
Oto kilka typowych sytuacji, w których możesz wysyłać tokeny tożsamości na swój serwer:
- Wysyłanie tokenów tożsamości z żądaniami, które wymagają uwierzytelnienia. Tokeny identyfikatorów informują o konkretnych użytkownikach wysyłających żądania i w przypadku klientów, którym przyznano tokeny.
Tokeny dokumentów tożsamości mają charakter poufny i mogą być używane w przypadku przechwycenia. Musisz się upewnić, że tokeny są obsługiwane w bezpieczny sposób, przesyłając je tylko przez HTTPS i tylko przez dane POST lub w nagłówkach żądań. Jeśli przechowujesz na serwerze tokeny tożsamości, musisz je też bezpiecznie przechowywać.
Tokeny identyfikatorów są przydatne, bo możesz je przekazywać między różnymi komponentami aplikacji. Te komponenty mogą używać tokena identyfikatora jako lekkiego mechanizmu uwierzytelniania uwierzytelniającego aplikację i użytkownika. Zanim jednak użyjesz informacji w tokenie identyfikatora lub będziesz używać go jako potwierdzenia, że użytkownik się uwierzytelnił, musisz je zweryfikować.
Weryfikacja tokena tożsamości wymaga kilku kroków:
- Sprawdź, czy wydawca dokumentu tożsamości ma prawidłowy podpis. Tokeny wydane przez Google są podpisane jednym z certyfikatów wymienionych w identyfikatorze URI podanym w wartości metadanych
jwks_uri
dokumentu Discovery. - Sprawdź, czy wartość roszczenia
iss
w tokenie identyfikatora wynosihttps://accounts.google.com
lubaccounts.google.com
. - Sprawdź, czy wartość roszczenia
aud
w tokenie identyfikatora jest równa identyfikatorowi klienta aplikacji. - Sprawdź, czy nie upłynął termin ważności (roszczenia:
exp
) tokena tożsamości. - Jeśli w żądaniu określono wartość parametru hd, sprawdź, czy token identyfikatora ma deklarację
hd
pasującą do akceptowanej domeny powiązanej z organizacją Google Cloud.
Kroki 2–5 obejmują tylko proste porównanie ciągów znaków i dat, więc nie będziemy ich tu szczegółowo omawiać.
Pierwszy krok jest bardziej złożony i wymaga sprawdzenia podpisu kryptograficznego. Do debugowania możesz użyć punktu końcowego tokeninfo
Google, aby porównać je z przetwarzaniem lokalnym wdrożonym na serwerze lub urządzeniu. Załóżmy, że wartość tokena identyfikatora to XYZ123
. Następnie musisz usunąć identyfikator URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Jeśli podpis tokena jest prawidłowy, odpowiedź będzie ładunkiem JWT w odkodowanym formularzu obiektu JSON.
Punkt końcowy tokeninfo
przydaje się do debugowania, ale do celów produkcyjnych pobieraj klucze publiczne Google z punktu końcowego kluczy i przeprowadzaj 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ć ograniczane lub mogą występować błędy przejściowe.
Google rzadko zmienia klucze publiczne, dlatego możesz zapisywać je w pamięci podręcznej, używając dyrektyw HTTP HTTP. W większości przypadków przeprowadzasz lokalną weryfikację o wiele skuteczniej niż za pomocą punktu końcowego tokeninfo
. Ta weryfikacja wymaga pobrania i analizy certyfikatów oraz wykonania odpowiednich wywołań kryptograficznych w celu sprawdzenia podpisu. Jest to możliwe w przypadku dobrze zdefiniowanych bibliotek dostępnych w wielu różnych językach (zobacz jwt.io).
Uzyskiwanie informacji o profilu użytkownika
Aby uzyskać dodatkowe informacje o użytkowniku, możesz użyć tokena dostępu (który aplikacja otrzymuje podczas procesu uwierzytelniania) i standardu OpenID Connect:
Aby zapewnić zgodność z identyfikatorem OpenID, w żądaniu uwierzytelniania musisz podać 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ównoprofile
, jak iemail
, możesz uwzględnić ten parametr w żądaniu URI uwierzytelnienia: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óry należy pobrać z dokumentu Discovery za pomocą wartości metadanychuserinfo_endpoint
. Odpowiedź dotycząca informacji o użytkowniku zawiera informacje na temat użytkownika opisane wOpenID Connect Standard Claims
i wartości metadanychclaims_supported
dokumentu Discovery. Użytkownicy lub ich organizacje mogą udostępniać lub wstrzymywać określone pola, więc niektóre pola mogą nie być widoczne w przypadku autoryzowanych zakresów dostępu.
Dokument Discovery
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żytkownikach i kluczy publicznych.
Aby uprościć implementacje i zwiększyć elastyczność, OpenID Connect umożliwia korzystanie z „dokumentu Discovery” – dokumentu JSON znajdującego się w dobrze znanej lokalizacji. Para klucz-wartość zawiera szczegóły dotyczące konfiguracji dostawcy OpenID Connect, w tym identyfikatory URI autoryzacji, tokenów, unieważnień, informacji o użytkownikach i punktów końcowych kluczy publicznych. Dokument Discovery usługi Google OpenID Connect można pobrać z:
https://accounts.google.com/.well-known/openid-configuration
Aby korzystać z usług OpenID Connect Google, musisz zakodować na stałe identyfikator URI dokumentu Discovery (https://accounts.google.com/.well-known/openid-configuration
) w aplikacji.
Aplikacja pobiera dokument, stosuje reguły buforowania w odpowiedzi, a następnie w razie potrzeby pobiera z niego identyfikatory URI punktu końcowego. Aby na przykład uwierzytelnić użytkownika, kod pobierze wartość metadanych authorization_endpoint
(w przykładzie poniżej: https://accounts.google.com/o/oauth2/v2/auth
) jako podstawowy identyfikator URI żądań uwierzytelniania wysyłanych do Google.
Oto przykład dokumentu. Nazwy pól są podane w OpenID Connect Discovery 1.0 (opis znaczenia tych dokumentów). Wartości mają charakter poglądowy i mogą się zmienić, chociaż zostaną skopiowane 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 danych w obie strony, buforując wartości w dokumencie Discovery. Używane są standardowe nagłówki buforowania HTTP i należy je przestrzegać.
Biblioteki klienta
Te biblioteki klienta ułatwiają wdrożenie OAuth 2.0, integrując je z popularnymi platformami:
- Biblioteka klienta interfejsów API Google dla języka Java
- Biblioteka klienta interfejsów API Google dla języka Python
- Biblioteka klienta interfejsów API Google dla .NET
- Biblioteka klienta interfejsów API Google dla systemu Ruby
- Biblioteka klienta interfejsów API Google dla PHP
- Biblioteka OAuth 2.0 dla Google Web Toolkit
- Zestaw narzędzi Google dla kontrolerów OAuth 2.0 na Macu
Zgodność z OpenID Connect
System uwierzytelniania Google OAuth 2.0 obsługuje wymagane funkcje w specyfikacji OpenID Connect Core. Każdy klient, który został zaprojektowany do obsługi połączeń OpenID Connect, powinien współpracować z tą usługą (z wyjątkiem obiektu żądania OpenID).