Interfejsy API Google używają protokołu OAuth 2.0 do uwierzytelniania i autoryzacji. Google obsługuje typowe scenariusze korzystania z protokołu OAuth 2.0, takie jak te dla serwerów WWW oraz aplikacji działających po stronie klienta, zainstalowanych i na urządzeniach z ograniczoną możliwością wprowadzania danych.
Na początek uzyskaj dane logowania klienta OAuth 2.0 w Konsoli interfejsów API Google. Następnie aplikacja kliencka wysyła żądanie tokena dostępu na serwer autoryzacji Google, wyodrębnia token z odpowiedzi i wysyła go do interfejsu API Google, do którego chcesz uzyskać dostęp. Aby zobaczyć interaktywną prezentację korzystania z OAuth 2.0 w Google (w tym opcję używania własnych danych logowania klienta), wypróbuj OAuth 2.0 Playground.
Na tej stronie znajdziesz omówienie scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google, oraz linki do bardziej szczegółowych informacji. Więcej informacji o używaniu OAuth 2.0 do uwierzytelniania znajdziesz w dokumentacji OpenID Connect.
Podstawowe czynności
Wszystkie aplikacje korzystające z interfejsu API Google za pomocą OAuth 2.0 postępują według tego samego schematu. Ogólnie rzecz biorąc, należy wykonać 5 czynności:
1. Uzyskaj dane logowania OAuth 2.0 w Konsoli interfejsów API Google.
Otwórz Konsolę interfejsów API Google, aby uzyskać dane logowania OAuth 2.0, takie jak identyfikator klienta i tajny klucz klienta, które są znane zarówno Google, jak i Twojej aplikacji. Zestaw wartości różni się w zależności od typu tworzonej aplikacji. Na przykład aplikacja JavaScript nie wymaga tajnego klucza, ale aplikacja serwera WWW już tak.
Musisz utworzyć klienta OAuth odpowiedniego dla platformy, na której będzie działać Twoja aplikacja, np.:
-
W przypadku aplikacji na Androida użyj
Android . -
W przypadku aplikacji na iOS i macOS użyj
typu klienta iOS . -
code
W przypadku aplikacji internetowych po stronie serwera lub JavaScript użyj
typu klienta
Aplikacja internetowa . Nie używaj tego typu klienta w przypadku innych aplikacji, np. natywnych lub mobilnych. - chrome_extension W przypadku rozszerzeń Chrome użyj typu klienta Rozszerzenie Chrome.
-
tv
W przypadku urządzeń z ograniczoną możliwością wpisywania, takich jak telewizory lub urządzenia wbudowane, użyj typu klienta
Telewizory i urządzenia z ograniczoną możliwością wpisywania . - host W przypadku interakcji między serwerami używaj kont usługi. Identyfikator klienta OAuth nie jest wymagany.
2. Uzyskaj token dostępu z serwera autoryzacji Google.
Zanim aplikacja uzyska dostęp do danych prywatnych za pomocą interfejsu API Google, musi uzyskać
token dostępu, który przyznaje dostęp do tego interfejsu. Pojedynczy token dostępu może przyznawać różny stopień
dostępu do wielu interfejsów API. Zestaw zasobów i operacji, na które zezwala token dostępu, jest kontrolowany przez parametr zmienny o nazwie scope. Podczas żądania tokena dostępu,
aplikacja wysyła co najmniej 1 wartość w parametrze scope.
Istnieje kilka sposobów wysłania tego żądania, które różnią się w zależności od typu tworzonej aplikacji. Na przykład aplikacja JavaScript może poprosić o token dostępu, używając przekierowania przeglądarki do Google, a aplikacja zainstalowana na urządzeniu bez przeglądarki używa żądań usługi internetowej. Więcej informacji o tym, jak wysłać żądanie, znajdziesz w sekcji Scenarios oraz w szczegółowych przewodnikach implementacji dla każdego typu aplikacji.
Niektóre żądania wymagają uwierzytelnienia, podczas którego użytkownik loguje się na swoje konto Google. Po zalogowaniu użytkownik jest pytany, czy chce przyznać co najmniej 1 uprawnienie, o które prosi Twoja aplikacja. Ten proces nazywa się zgodą użytkownika.
Jeśli użytkownik przyzna co najmniej 1 uprawnienie, serwer autoryzacji Google wyśle do Twojej aplikacji token dostępu (lub kod autoryzacji, którego aplikacja może użyć do uzyskania tokena dostępu) oraz listę zakresów dostępu przyznanych przez ten token. Jeśli użytkownik nie przyzna uprawnienia, serwer zwróci błąd.
Zasadniczo najlepszym rozwiązaniem jest żądanie zakresów przyrostowo, w momencie, gdy wymagany jest dostęp, a nie z góry. Na przykład aplikacja, która ma obsługiwać zapisywanie wydarzenia w kalendarzu nie powinna prosić o dostęp do Kalendarza Google, dopóki użytkownik nie kliknie przycisku „Dodaj do Kalendarza”. Więcej informacji znajdziesz w sekcji Autoryzacja przyrostowa.
3. Sprawdź zakresy dostępu przyznane przez użytkownika.
Porównaj zakresy zawarte w odpowiedzi tokena dostępu z zakresami wymaganymi do uzyskania dostępu do funkcji i funkcjonalności aplikacji, które zależą od dostępu do powiązanego interfejsu API Google. Wyłącz wszystkie funkcje aplikacji, które nie mogą działać bez dostępu do powiązanego interfejsu API.
Zakres zawarty w żądaniu może nie odpowiadać zakresowi zawartemu w odpowiedzi, nawet
jeśli użytkownik przyznał wszystkie żądane zakresy. Wymagane zakresy dostępu znajdziesz w dokumentacji każdego interfejsu API Google. Interfejs API może mapować wiele wartości ciągu zakresu na jeden
zakres dostępu, zwracając ten sam ciąg zakresu dla wszystkich wartości dozwolonych w żądaniu.
Przykład: interfejs Google People API może zwrócić zakres
https://www.googleapis.com/auth/contacts gdy aplikacja poprosi użytkownika o autoryzację
zakresu https://www.google.com/m8/feeds/; metoda interfejsu Google People API
people.updateContact
wymaga przyznanego zakresu https://www.googleapis.com/auth/contacts.
4. Wyślij token dostępu do interfejsu API.
Gdy aplikacja uzyska token dostępu, wysyła go do interfejsu API Google w nagłówku żądania HTTP Authorization. Tokeny można wysyłać jako parametry ciągu zapytania URI, ale nie zalecamy tego, ponieważ parametry URI mogą trafić do plików dziennika, które nie są w pełni bezpieczne. Ponadto warto unikać tworzenia niepotrzebnych nazw parametrów URI.
Tokeny dostępu są ważne tylko w przypadku zestawu operacji i zasobów opisanych w
scope żądania tokena. Jeśli na przykład token dostępu zostanie wydany dla interfejsu Google Calendar API, nie przyzna dostępu do interfejsu Google Contacts API. Możesz jednak, wysłać ten token dostępu do interfejsu Kalendarza Google API kilka razy w przypadku podobnych operacji.
5. W razie potrzeby odśwież token dostępu.
Tokeny dostępu mają ograniczony czas ważności. Jeśli aplikacja potrzebuje dostępu do interfejsu API Google po upływie czasu ważności pojedynczego tokena dostępu, może uzyskać token odświeżania. Token odświeżania umożliwia aplikacji uzyskanie nowych tokenów dostępu.
Scenarios
Te scenariusze opisują, jak używać OAuth 2.0 do żądania kodów autoryzacji oraz uzyskiwania tokenów dostępu i odświeżania w przypadku różnych typów aplikacji.
Aplikacje serwera WWW
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwera WWW, które używają języków i platform takich jak PHP, Java, Go, Python, Ruby i ASP.NET.
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google . Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. Wynikiem jest kod autoryzacji, który aplikacja może wymienić na token dostępu i token odświeżania.
Aplikacja powinna przechowywać token odświeżania do wykorzystania w przyszłości i używać tokena dostępu do uzyskiwania dostępu do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja używa tokena odświeżania aby uzyskać nowy.
Zainstalowane aplikacje
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje zainstalowane na urządzeniach takich jak komputery, urządzenia mobilne i tablety. Gdy tworzysz identyfikator klienta w Konsoli interfejsów API Google, określ, że jest to zainstalowana aplikacja, a następnie jako typ aplikacji wybierz Android, Rozszerzenie Chrome, iOS, lub Aplikacja na komputer.
W wyniku tego procesu otrzymasz identyfikator klienta, a w niektórych przypadkach także tajny klienta, który umieścisz w kodzie źródłowym aplikacji. (W tym kontekście tajny klucz klienta nie jest oczywiście traktowany jako tajny).
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google . Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. Wynikiem jest kod autoryzacji, który aplikacja może wymienić na token dostępu. Aplikacja powinna zweryfikować token dostępu, zanim uwzględni go w żądaniu interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.
Opcjonalnie serwer backendu może wymienić kod autoryzacji na token odświeżania, zapisać go w bezpiecznym miejscu. Gdy token dostępu wygaśnie, serwer backendu używa tokena odświeżania, aby uzyskać nowy token dla aplikacji.
Więcej informacji znajdziesz w artykułach Autoryzowanie dostępu do danych użytkownika Google na Androidzie, oraz OAuth 2.0 w przypadku aplikacji na iOS i komputer.
Aplikacje po stronie klienta (JavaScript)
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje JavaScript, które działają w przeglądarce.
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google . Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika.
Wynikiem jest token dostępu, który klient powinien zweryfikować, zanim uwzględni go w żądaniu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.
Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 w aplikacjach po stronie klienta.
Aplikacje na urządzeniach z ograniczoną możliwością wpisywania
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje, które działają na urządzeniach z ograniczoną możliwością wpisywania, takich jak konsole do gier, kamery wideo i drukarki.
Sekwencja autoryzacji rozpoczyna się od wysłania przez aplikację żądania usługi sieciowej do adresu URL Google w celu uzyskania kodu autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod, które aplikacja wyświetla użytkownikowi.
Użytkownik uzyskuje adres URL i kod z urządzenia, a następnie przechodzi na inne urządzenie lub komputer z większymi możliwościami wpisywania. Użytkownik uruchamia przeglądarkę, otwiera podany adres URL, loguje się i wpisuje kod.
W międzyczasie aplikacja co określony czas wysyła zapytanie do adresu URL Google. Gdy użytkownik zatwierdzi dostęp, odpowiedź z serwera Google będzie zawierać token dostępu i token odświeżania. Aplikacja powinna przechowywać token odświeżania do wykorzystania w przyszłości i używać tokena dostępu do uzyskiwania dostępu do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja używa tokena odświeżania, aby uzyskać nowy.
Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 na urządzeniach.
Konta usługi
Interfejsy API Google, takie jak Prediction API i Google Cloud Storage, mogą działać w imieniu Twojej aplikacji bez dostępu do informacji o użytkownikach. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość w interfejsie API, ale nie jest wymagana zgoda użytkownika. Podobnie w scenariuszach firmowych aplikacja może poprosić o przekazanie dostępu do niektórych zasobów.
W przypadku tego typu interakcji między serwerami potrzebujesz konta usługi, które jest kontem należącym do Twojej aplikacji, a nie do indywidualnego użytkownika. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgoda użytkownika nie jest wymagana. (W scenariuszach innych niż konta usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników, a zgoda użytkownika jest czasami wymagana).
Dane logowania konta usługi, które uzyskujesz w Konsoli interfejsów API Google, obejmują wygenerowany adres e-mail, który jest unikalny, identyfikator klienta i co najmniej 1 parę kluczy publicznych i prywatnych. Używasz identyfikatora klienta i 1 klucza prywatnego do utworzenia podpisanego tokena JWT i utworzenia żądania tokena dostępu w odpowiednim formacie. Następnie aplikacja wysyła żądanie tokena na serwer autoryzacji Google OAuth 2.0, który zwraca token dostępu. Aplikacja używa tokena do uzyskiwania dostępu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.
Więcej informacji znajdziesz w dokumentacji kont usługi.
Rozmiar tokena
Rozmiar tokenów może się różnić, ale nie może przekraczać tych limitów:
Tokeny dostępu zwracane przez interfejs Security Token Service API w Google Cloud mają podobną strukturę do tokenów dostępu OAuth 2.0 interfejsu API Google, ale mają inne limity rozmiaru tokena. Więcej informacji znajdziesz w dokumentacji API.
Google zastrzega sobie prawo do zmiany rozmiaru tokena w ramach tych limitów, a Twoja aplikacja musi obsługiwać zmienne rozmiary tokenów.
Wygasanie tokena odświeżania
Musisz napisać kod, który będzie uwzględniał możliwość, że przyznany token odświeżania może przestać działać. Token odświeżania może przestać działać z jednego z tych powodów:
Projekt Google Cloud Platform ze skonfigurowanym ekranem zgody OAuth dla typu użytkownika zewnętrznego i stanem publikowania „Testowanie” otrzymuje token odświeżania, który wygasa po 7 dniach, chyba że jedyne żądane zakresy OAuth są podzbiorem zakresów nazwy, adresu e-mail i profilu użytkownika (za pomocą zakresów
userinfo.email, userinfo.profile, openid lub ich odpowiedników OpenID Connect).
Obecnie obowiązuje limit 100 tokenów odświeżania na konto Google na identyfikator klienta OAuth 2.0. Jeśli ten limit zostanie przekroczony, utworzenie nowego tokena odświeżania automatycznie unieważnia najstarszy token odświeżania. Dzieje się to bez ostrzeżenia. Ten limit nie dotyczy kont usługi.
Obowiązuje też większy limit łącznej liczby tokenów odświeżania, które konto użytkownika lub konto usługi może mieć we wszystkich klientach. Większość zwykłych użytkowników nie przekroczy tego limitu, ale może to zrobić konto dewelopera używane do testowania implementacji.
Jeśli musisz autoryzować wiele programów, maszyn lub urządzeń, jednym z rozwiązań jest ograniczenie liczby klientów autoryzowanych na konto Google do 15 lub 20. Jeśli jesteś administratorem Google Workspace, możesz utworzyć dodatkowych użytkowników z uprawnieniami administratora i użyć ich do autoryzowania niektórych klientów.
Obsługa zasad kontroli sesji w organizacjach Google Cloud Platform (GCP)
Administratorzy organizacji GCP mogą wymagać częstego ponownego uwierzytelniania użytkowników podczas
uzyskiwania dostępu do zasobów GCP za pomocą
funkcji kontroli sesji Google Cloud. Te zasady wpływają na dostęp do konsoli Google Cloud, do
pakietu Google Cloud SDK (znanego też jako gcloud
CLI) i dowolnej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli użytkownik ma włączone zasady kontroli sesji, po upływie czasu trwania sesji wywołania interfejsu API będą kończyć się błędem podobnym do tego, który występuje w przypadku unieważnienia tokena odświeżania – wywołanie zakończy się niepowodzeniem z typem błędu invalid_grant; pole error_subtype może służyć do rozróżniania między unieważnionym tokenem a błędem spowodowanym zasadami kontroli sesji (np. "error_subtype": "invalid_rapt"). Ponieważ czas trwania sesji może być bardzo ograniczony (od 1 do 24 godzin), ten scenariusz należy obsługiwać w sposób płynny, ponownie uruchamiając sesję uwierzytelniania.
Nie wolno też używać danych logowania użytkownika ani zachęcać do ich używania w przypadku wdrożenia międzyserwerowego. Jeśli dane logowania użytkownika są wdrażane na serwerze w przypadku długotrwałych zadań lub operacji i klient stosuje do takich użytkowników zasady kontroli sesji, aplikacja serwera zakończy się niepowodzeniem, ponieważ nie będzie można ponownie uwierzytelnić użytkownika po upływie czasu trwania sesji.
Więcej informacji o tym, jak pomóc klientom we wdrożeniu tej funkcji, znajdziesz w tym artykule w Centrum pomocy dla administratorów.
Biblioteki klienta
Te biblioteki klienta integrują się z popularnymi platformami, co ułatwia implementację OAuth 2.0. Z czasem do bibliotek zostaną dodane kolejne funkcje.
- Biblioteka Google Auth do języka Java
- Biblioteka klienta interfejsów API Google do języka Python
- Biblioteka klienta interfejsów API Google do języka Dart
- Biblioteka klienta interfejsów API Google do języka Go
- Biblioteka klienta interfejsów API Google do języka .NET
- Biblioteka klienta interfejsów API Google do języka Ruby
- Biblioteka klienta interfejsów API Google do języka PHP
- Biblioteka klienta interfejsów API Google do języka JavaScript
- GTMAppAuth – biblioteka klienta OAuth do komputerów Mac i iOS