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 serwera WWW oraz aplikacje działające po stronie klienta, zainstalowane i na urządzenia z ograniczonymi możliwościami wprowadzania danych.
Na początek uzyskaj dane uwierzytelniające klienta OAuth 2.0 w Konsoli interfejsów API Google. Następnie aplikacja kliencka wysyła żądanie tokena dostępu do serwera 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ą demonstrację korzystania z OAuth 2.0 w Google (w tym opcję używania własnych danych uwierzytelniających 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 treści. Szczegółowe informacje o używaniu OAuth 2.0 do uwierzytelniania znajdziesz w artykule OpenID Connect.
Podstawowe czynności
Wszystkie aplikacje korzystające z interfejsu API Google za pomocą OAuth 2.0 postępują według podstawowego wzorca. Ogólnie rzecz biorąc, musisz wykonać 5 kroków:
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 w JavaScripcie nie wymaga klucza tajnego, 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 typu klienta
Android . -
W przypadku aplikacji na iOS i macOS użyj typu klienta iOS . -
code
W przypadku aplikacji internetowych po stronie serwera lub aplikacji internetowych JavaScript użyj typu klienta
Aplikacja internetowa . Nie używaj tego typu klienta w przypadku innych aplikacji, np. aplikacji natywnych lub mobilnych. - chrome_extension W przypadku rozszerzeń do Chrome użyj typu klienta Rozszerzenie do Chrome.
-
tv
W przypadku urządzeń z ograniczoną możliwością wpisywania, takich jak telewizory lub urządzenia wbudowane, użyj typu klienta
TV i urządzenia z ograniczoną możliwością wpisywania . - host W przypadku interakcji międzyserwerowych używaj kont usługi. Nie jest wymagany identyfikator klienta OAuth.
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 API. Jeden token dostępu może przyznawać różny poziom dostępu do wielu interfejsów API. Parametr zmienny o nazwie scope określa zbiór zasobów i operacji, na które zezwala token dostępu. Podczas wysyłania żądania tokena dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.
Istnieje kilka sposobów wysłania takiego żą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, przekierowując przeglądarkę do Google, a aplikacja zainstalowana na urządzeniu bez przeglądarki może używać żądań usługi internetowej. Więcej informacji o tym, jak wysłać żądanie, znajdziesz w sekcji Scenarios oraz w szczegółowych przewodnikach wdrażania dla poszczególnych typów 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 aplikacja. Ten proces nazywa się uzyskiwaniem zgody użytkowników.
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 uprawnień, serwer zwróci błąd.
Sprawdzoną metodą jest proszenie o zakresy przyrostowo, w momencie, gdy dostęp jest wymagany, 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 Google API. Wyłącz wszystkie funkcje aplikacji, które nie mogą działać bez dostępu do powiązanego interfejsu API.
Zakres uwzględniony w Twoim żądaniu może nie być zgodny z zakresem uwzględnionym w odpowiedzi, nawet jeśli użytkownik przyznał wszystkie żądane zakresy. Zakresy wymagane do uzyskania dostępu znajdziesz w dokumentacji poszczególnych interfejsów 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 autoryzacji HTTP. 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. Zgodnie z zasadami REST nie należy tworzyć niepotrzebnych nazw parametrów URI.
Tokeny dostępu są ważne tylko w przypadku operacji i zasobów opisanych w scope żądania tokena. Jeśli np. token dostępu zostanie wydany dla interfejsu Kalendarza Google API, nie przyznaje dostępu do interfejsu Kontaktów Google API. Możesz jednak wysłać ten token dostępu do interfejsu Kalendarza Google API wiele 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 dłużej niż przez okres ważności pojedynczego tokena dostępu, może uzyskać token odświeżania. Token odświeżania umożliwia aplikacji uzyskiwanie nowych tokenów dostępu.
Scenariusze
W tych scenariuszach opisujemy, 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 korzystają z języków i platform takich jak PHP, Java, Go, Python, Ruby i ASP.NET.
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę na adres URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google zajmuje się uwierzytelnianiem użytkowników, wyborem sesji i uzyskiwaniem zgody użytkowników. W rezultacie otrzymasz 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 Google API. Gdy token dostępu wygaśnie, aplikacja używa tokena odświeżania, aby uzyskać nowy token.
Szczegółowe informacje znajdziesz w artykule o używaniu OAuth 2.0 w internetowych aplikacjach serwerowych.
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 aplikacja zainstalowana, a następnie wybierz jako typ aplikacji Android, rozszerzenie Chrome, iOS lub aplikację na komputer.
W wyniku tego procesu otrzymasz identyfikator klienta, a w niektórych przypadkach także klucz klienta, który musisz umieścić w kodzie źródłowym aplikacji. (W tym kontekście klucz tajny klienta oczywiście nie jest traktowany jako tajny).
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę na adres URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google zajmuje się uwierzytelnianiem użytkowników, wyborem sesji i uzyskiwaniem zgody użytkowników. 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 i przechowywać go w bezpiecznym miejscu. Gdy token dostępu wygaśnie, serwer backendu używa tokena odświeżania, aby uzyskać nowy token dla aplikacji.
Szczegółowe informacje znajdziesz w artykule Autoryzowanie dostępu do danych użytkownika Google na Androidzie i OAuth 2.0 w przypadku aplikacji na iOS i komputery.
Aplikacje po stronie klienta (JavaScript)
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje JavaScript działające w przeglądarce.
Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę na adres URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google zajmuje się uwierzytelnianiem użytkowników, wyborem sesji i uzyskiwaniem zgody użytkowników.
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.
Szczegółowe informacje 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 działające na urządzeniach z ograniczonymi możliwościami wprowadzania danych, takich jak konsole do gier, kamery wideo i drukarki.
Sekwencja autoryzacji rozpoczyna się od wysłania przez aplikację żądania usługi sieciowej na adres URL Google w celu uzyskania kodu autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod, który aplikacja wyświetla użytkownikowi.
Użytkownik uzyskuje adres URL i kod z urządzenia, a następnie przełącza się na inne urządzenie lub komputer z większymi możliwościami wprowadzania danych. Użytkownik uruchamia przeglądarkę, otwiera podany adres URL, loguje się i wpisuje kod.
W tym czasie aplikacja wysyła zapytania do adresu URL Google w określonych odstępach czasu. 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 Google API. Gdy token dostępu wygaśnie, aplikacja używa tokena odświeżania, aby uzyskać nowy token.
Szczegółowe informacje 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 przypadku scenariuszy firmowych aplikacja może poprosić o przekazywanie dostępu do niektórych zasobów.
W przypadku tego typu interakcji między serwerami potrzebujesz konta usługi, które należy do aplikacji, a nie do indywidualnego użytkownika. Aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgoda użytkownika nie jest wymagana. (W przypadku scenariuszy niezwiązanych z kontami usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników, a czasami wymagana jest zgoda użytkownika).
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. Aby utworzyć podpisany token JWT i żądanie tokena dostępu w odpowiednim formacie, użyj identyfikatora klienta i jednego klucza prywatnego. Następnie Twoja aplikacja wyśle żądanie tokena na serwer autoryzacji Google OAuth 2.0, który zwróci token dostępu. Aplikacja używa tokena do uzyskiwania dostępu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.
Szczegółowe informacje znajdziesz w dokumentacji konta 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 Security Token Service API Google Cloud mają podobną strukturę do tokenów dostępu OAuth 2.0 interfejsu Google API, ale obowiązują w nich inne limity rozmiaru tokena. Szczegółowe informacje znajdziesz w dokumentacji interfejsu API.
Google zastrzega sobie prawo do zmiany rozmiaru tokena w tych granicach, a aplikacja musi obsługiwać różne rozmiary tokenów.
Wygaśnięcie tokena odświeżania
Musisz napisać kod tak, aby 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:
W przypadku projektu Google Cloud Platform ze skonfigurowanym ekranem zgody OAuth dla zewnętrznego typu użytkownika i stanem publikowania „Testuję” wydawany jest token odświeżania, który wygasa po 7 dniach, chyba że jedynymi żądanymi zakresami OAuth są podzbiory 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 limit ten 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ług.
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ć na wszystkich klientach. Większość zwykłych użytkowników nie przekracza tego limitu, ale może to zrobić konto dewelopera używane do testowania wdrożenia.
Jeśli musisz autoryzować wiele programów, maszyn lub urządzeń, możesz ograniczyć liczbę klientów autoryzowanych na koncie Google do 15–20. Jeśli jesteś administratorem Google Workspace, możesz utworzyć dodatkowych użytkowników z uprawnieniami administracyjnymi i użyć ich do autoryzacji niektórych klientów.
Postępowanie w przypadku 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, pakietu SDK Google Cloud (znanego też jako gcloud CLI) i dowolnej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli użytkownik ma włączoną zasadę kontroli sesji, po upływie czasu trwania sesji wywołania interfejsu API będą zwracać błąd podobny do tego, który występuje w przypadku cofnięcia 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 odróżnienia cofniętego tokena od błędu spowodowanego zasadą kontroli sesji (np. "error_subtype": "invalid_rapt"). Ponieważ czas trwania sesji może być bardzo ograniczony (od 1 godziny do 24 godzin), w takim przypadku należy płynnie wznowić sesję uwierzytelniania.
Nie możesz też używać danych logowania użytkownika ani zachęcać do ich używania w przypadku wdrożenia typu serwer-serwer. Jeśli dane logowania użytkownika są wdrażane na serwerze w przypadku długotrwałych zadań lub operacji, a klient stosuje do takich użytkowników zasady kontroli sesji, aplikacja serwera ulegnie awarii, ponieważ po wygaśnięciu czasu trwania sesji nie będzie można ponownie uwierzytelnić użytkownika.
Więcej informacji o tym, jak pomóc klientom we wdrożeniu tej funkcji, znajdziesz w tym artykule pomocy dla administratorów.
Biblioteki klienta
Te biblioteki klienta są zintegrowane z popularnymi platformami, co ułatwia wdrażanie OAuth 2.0. Z czasem dodamy do bibliotek więcej funkcji.
- Biblioteka uwierzytelniania Google 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 .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 JavaScriptu
- GTMAppAuth – biblioteka klienta OAuth na Maca i iOS