Interfejsy API Google używają do uwierzytelniania i autoryzacji protokołu OAuth 2.0. Google obsługuje typowe scenariusze OAuth 2.0, takie jak te dotyczące aplikacji na serwerze WWW, po stronie klienta, zainstalowanych i na urządzeniach z ograniczonymi możliwościami wprowadzania danych.
Aby rozpocząć, uzyskaj dane uwierzytelniające klienta OAuth 2.0 z Konsoli interfejsów API Google. Następnie aplikacja kliencka żąda tokena dostępu od 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 protokołu OAuth 2.0 w Google (w tym opcję użycia 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 informacji. Szczegółowe informacje o używaniu protokołu OAuth 2.0 do uwierzytelniania znajdziesz w artykule o OpenID Connect.
Podstawowe czynności
Wszystkie aplikacje korzystające z interfejsów API Google za pomocą protokołu OAuth 2.0 działają według podstawowego wzorca. Ogólnie rzecz biorąc, należy wykonać 5 czynności:
1. Uzyskaj dane logowania OAuth 2.0 z Konsoli interfejsów API Google.
Odwiedź 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, na przykład:
- W przypadku aplikacji na Androida użyj typu aplikacji Android.
-
W przypadku aplikacji na iOS użyj typu aplikacji iOS.
- desktop_windows W przypadku aplikacji komputerowych (takich jak aplikacje na systemy Windows, macOS lub Linux albo narzędzia CLI) użyj typu aplikacji Aplikacja komputerowa.
- code – w przypadku aplikacji po stronie serwera lub aplikacji internetowych JavaScript użyj typu aplikacji Aplikacja internetowa. Nie używaj tego typu aplikacji w przypadku innych aplikacji, takich jak aplikacje natywne lub mobilne.
- chrome_extension W przypadku rozszerzeń do Chrome użyj typu aplikacji Rozszerzenie do Chrome.
- tv W przypadku urządzeń wejściowych z ograniczoną możliwością wpisywania, takich jak telewizory lub urządzenia wbudowane, użyj typu aplikacji TV 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. uzyskać token dostępu z serwera autoryzacji Google,
Zanim aplikacja będzie mogła uzyskać dostęp do prywatnych danych za pomocą interfejsu API Google, musi uzyskać token dostępu, który umożliwia dostęp do tego interfejsu API. Pojedynczy token dostępu może przyznawać różne poziomy dostępu do wielu interfejsów API. Zbiorem zasobów i operacji, na które zezwala token dostępu, steruje zmienny parametr o nazwie scope. Podczas żądania tokena dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.
Istnieje kilka sposobów na przesłanie takiego żądania, które różnią się w zależności od typu tworzonej aplikacji. Na przykład aplikacja w języku JavaScript może poprosić o token dostępu, przekierowując przeglądarkę do Google, podczas gdy aplikacja zainstalowana na urządzeniu bez przeglądarki używa żądań usług internetowych. Więcej informacji o tym, jak wysłać żądanie, znajdziesz w sekcji Scenarios oraz w szczegółowych przewodnikach po implementacji dla poszczególnych typów aplikacji.
Niektóre żądania wymagają uwierzytelnienia, podczas którego użytkownik loguje się na swoje konto Google. Po zalogowaniu się użytkownik jest pytany, czy chce przyznać co najmniej 1 uprawnienie, o które prosi aplikacja. Ten proces nazywa się uzyskiwaniem zgody użytkownika.
Jeśli użytkownik przyzna co najmniej jedno uprawnienie, serwer autoryzacji Google wysyła do 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.
Zgodnie ze sprawdzonymi metodami zakresy należy żądać przyrostowo, w momencie gdy dostęp jest wymagany, a nie z góry. Na przykład aplikacja, która chce obsługiwać zapisywanie wydarzenia w kalendarzu, nie powinna prosić o dostęp do Kalendarza Google, dopóki użytkownik nie naciśnie przycisku „Dodaj do kalendarza”. Zobacz Autoryzacja przyrostowa.
3. Sprawdź zakresy dostępu przyznane przez użytkownika.
Porównaj zakresy uwzględnione w odpowiedzi tokena dostępu z zakresami wymaganymi do uzyskania dostępu do funkcji 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 uwzględniony w żądaniu może nie odpowiadać zakresowi uwzględnionemu 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 people.updateContact interfejsu Google People API wymaga przyznanego zakresu https://www.googleapis.com/auth/contacts.
4. wysłać token dostępu do interfejsu API,
Po uzyskaniu tokena dostępu aplikacja wysyła go do interfejsu API Google w nagłówku żądania autoryzacji HTTP. Można wysyłać tokeny jako parametry ciągu zapytania identyfikatora URI, ale nie zalecamy tego, ponieważ parametry identyfikatora URI mogą trafić do plików dziennika, które nie są całkowicie bezpieczne. Zgodnie ze sprawdzonymi metodami REST warto też unikać tworzenia niepotrzebnych nazw parametrów identyfikatora 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 Kalendarza Google API, nie będzie on przyznawał dostępu do interfejsu Kontaktów Google API. Możesz jednak wielokrotnie wysyłać ten token dostępu do interfejsu Kalendarza Google API w przypadku podobnych operacji.
5. W razie potrzeby odśwież token dostępu.
Tokeny dostępu mają ograniczony okres ważności. Jeśli aplikacja potrzebuje dostępu do interfejsu API Google po upływie okresu 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
Te scenariusze opisują, jak używać protokołu OAuth 2.0 do żądania kodów autoryzacji oraz uzyskiwania tokenów dostępu i tokenów 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ę 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 zgodą użytkownika. W wyniku otrzymasz kod autoryzacji, który aplikacja może wymienić na token dostępu i token odświeżania.
Aplikacja powinna zapisać token odświeżania do wykorzystania w przyszłości i użyć tokena dostępu, aby uzyskać dostęp do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy token dostępu.
Więcej informacji 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 zainstalowana aplikacja, a następnie wybierz typ aplikacji: Android, rozszerzenie do Chrome, iOS lub aplikacja komputerowa.
W wyniku tego procesu otrzymasz identyfikator klienta, a w niektórych przypadkach także tajny klucz klienta, który należy umieścić 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ę 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 zgodą użytkownika. Wynikiem jest kod autoryzacji, który aplikacja może wymienić na token dostępu. Aplikacja powinna zweryfikować token dostępu, zanim dołączy go do żądania do interfejsu API Google. Gdy token wygaśnie, aplikacja powtórzy ten proces.
Opcjonalnie serwer backendu może wymienić kod autoryzacji na token odświeżania i zapisać go w bezpiecznej lokalizacji. Gdy token dostępu wygaśnie, serwer backendu użyje tokena odświeżania, aby uzyskać nowy token dla aplikacji.
Szczegółowe informacje znajdziesz w artykułach Autoryzowanie dostępu do danych użytkownika Google na Androidzie, Dostęp do interfejsów API Google w aplikacji na iOS i OAuth 2.0 w aplikacjach komputerowych.
Aplikacje po stronie klienta (JavaScript)
Punkt końcowy Google OAuth 2.0 obsługuje aplikacje w języku JavaScript, które działają 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 zgodą użytkownika.
Wynikiem jest token dostępu, który klient powinien zweryfikować, zanim dołączy go do żądania do interfejsu API Google. Gdy token wygaśnie, aplikacja powtórzy 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 internetowej do adresu 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ę, przechodzi pod podany adres URL, loguje się i wpisuje kod.
W tym czasie aplikacja odpytuje adres 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 zapisać token odświeżania do wykorzystania w przyszłości i użyć tokena dostępu, aby uzyskać dostęp do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy token dostępu.
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żytkowniku. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość w interfejsie API, ale zgoda użytkownika nie jest konieczna. Podobnie w scenariuszach korporacyjnych aplikacja może poprosić o delegowany dostęp do niektórych zasobów.
W przypadku tego typu interakcji między serwerami potrzebujesz konta usługi, które należy do Twojej 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 bez konta 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 uzyskasz z Konsoli interfejsów API Google, obejmują wygenerowany unikalny adres e-mail, identyfikator klienta i co najmniej 1 parę kluczy publiczny/prywatny. Używasz identyfikatora klienta i jednego klucza prywatnego, aby utworzyć podpisany token JWT i skonstruować żądanie tokena dostępu w odpowiednim formacie. Następnie aplikacja wysyła żądanie tokena do serwera autoryzacji Google OAuth 2.0, który zwraca token dostępu. Aplikacja używa tokena, aby uzyskać dostęp do interfejsu API Google. Gdy token wygaśnie, aplikacja powtórzy ten proces.
Szczegółowe informacje znajdziesz w dokumentacji konta usługi.
Rozmiar tokena
Tokeny mogą mieć różne rozmiary, ale nie mogą przekraczać tych limitów:
Tokeny dostępu zwracane przez Security Token Service API Google Cloud mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsów API Google, ale mają 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 odpowiednio obsługiwać zmienne rozmiary tokenów.
Wygaśnięcie tokena odświeżania
Musisz napisać kod, który uwzględnia możliwość, że przyznany token odświeżania może już nie działać. Token odświeżania może przestać działać z jednego z tych powodów:
Projekt Google Cloud Platform z ekranem zgody OAuth skonfigurowanym dla zewnętrznego typu użytkownika i stanem publikacji „Testowanie” otrzymuje token odświeżania, który wygasa po 7 dniach, chyba że jedynymi żądanymi zakresami OAuth są podzbiory 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 istniejący token odświeżania. Dzieje się to bez ostrzeżenia. Ten limit nie dotyczy kont usługi.
Istnieje 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 się to zdarzyć w przypadku konta dewelopera używanego do testowania implementacji.
Jeśli musisz autoryzować wiele programów, komputerów lub urządzeń, możesz obejść ten problem, ograniczając liczbę klientów autoryzowanych na konto Google do 15–20. Jeśli jesteś administratorem Google Workspace, możesz utworzyć dodatkowych użytkowników z uprawnieniami administratora i używać ich do autoryzowania niektórych klientów.
Zasady 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. Ta zasada wpływa na dostęp do konsoli Google Cloud, Google Cloud SDK (znanego też jako gcloud CLI) i wszelkich aplikacji OAuth innych firm, które wymagają zakresu Cloud Platform. Jeśli użytkownik ma zasadę 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 po unieważnieniu tokena odświeżania. Wywołanie nie powiedzie się i zostanie zwrócony błąd typu invalid_grant. Pole error_subtype może służyć do odróżnienia unieważnionego 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), ten scenariusz musi być obsługiwany przez ponowne uruchomienie sesji uwierzytelniania.
Nie wolno też używać ani zachęcać do używania danych logowania użytkownika do wdrożenia między serwerami. Jeśli dane logowania użytkownika są wdrażane na serwerze na potrzeby długotrwałych zadań lub operacji, a klient stosuje zasady kontroli sesji do takich użytkowników, aplikacja serwera nie będzie działać, ponieważ po upływie 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 upraszcza implementację protokołu OAuth 2.0. Z czasem do bibliotek dodamy 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 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 na komputery Mac i urządzenia z iOS