Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google

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 serwer internetowy oraz aplikacje zainstalowane i działające po stronie klienta oraz na urządzeniach z ograniczoną liczbą sposobów wprowadzania danych.

Aby rozpocząć, uzyskaj dane logowania klienta OAuth 2.0 z Google API Console. 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 z opcją użycia 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 treści. Szczegółowe informacje o używaniu OAuth 2.0 do uwierzytelniania znajdziesz w artykule OpenID Connect.

Podstawowe czynności

Wszystkie aplikacje uzyskujące dostęp do interfejsu API Google za pomocą protokołu OAuth 2.0 stosują podstawowy wzorzec. Ogólnie rzecz biorąc, należy wykonać 5 kroki:

1. Uzyskaj dane logowania OAuth 2.0 ze strony Google API Console.

Otwórz Google API Console, 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 zależy od typu tworzonej aplikacji. Na przykład aplikacja JavaScript nie wymaga obiektu tajnego, ale wymaga go aplikacja serwera WWW.

Musisz utworzyć klienta OAuth odpowiedniego dla platformy, na której będzie działać aplikacja, na przykład:

2. Uzyskaj token dostępu od serwera autoryzacji Google.

Zanim aplikacja uzyska dostęp do danych prywatnych za pomocą interfejsu API Google, musi uzyskać token dostępu, który umożliwia dostęp do tego interfejsu. Pojedynczy token dostępu może przyznawać różne poziomy dostępu do wielu interfejsów API. Parametr zmienny o nazwie scope kontroluje zestaw zasobów i operacji, które zezwala wykonywać token dostępu. Podczas żądania tokena dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.

Istnieje kilka sposobów przesłania tego żądania. Różnią się one 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, które nie ma przeglądarki, używa żądań usługi internetowej.

Niektóre żądania wymagają uwierzytelniania, w którym użytkownik loguje się na swoje konto Google. Po zalogowaniu użytkownik zostaje poproszony o przyznanie co najmniej jednego uprawnienia, o które prosi Twoja aplikacja. Ten proces jest nazywany zgodą użytkownika.

Jeśli użytkownik przyzna co najmniej 1 uprawnienie, serwer autoryzacji Google wyśle Twojej aplikacji token dostępu (lub kod autoryzacji, za pomocą którego aplikacja może uzyskać token dostępu) oraz listę zakresów dostępu przyznanych przez ten token. Jeśli użytkownik nie udzieli uprawnień, serwer zwróci błąd.

Zwykle zaleca się, aby zakresy były przyznawane stopniowo, w momencie, gdy jest to konieczne, a nie z góry. Na przykład aplikacja, która obsługuje 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 Stopniowe udzielanie uprawnień.

3. Sprawdź zakresy dostępu przyznane przez użytkownika.

Porównaj zakresy dostępu podane w odpowiedzi na żądanie tokena dostępu z zakresami dostępu wymaganymi do korzystania z funkcji i funkcjonalności aplikacji zależnych 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 zawarty w żądaniu może nie pasować do zakresu 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. API może mapować wiele wartości ciągu zakresu na jeden zakres dostępu, zwracając ten sam ciąg znaków 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 w identyfikatorze URI, ale nie zalecamy tego, ponieważ parametry URI mogą trafić do plików logowania, które nie są w pełni bezpieczne. Dobrą praktyką REST jest też unikanie 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 np. token dostępu zostanie wydany dla interfejsu Google Calendar API, nie przyzna on dostępu do interfejsu Google Contacts API. Możesz jednak wysłać ten token dostępu do interfejsu Google Calendar 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 Google API przez czas dłuższy niż czas 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

Aplikacje serwera WWW

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwerów 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ę do adresu URL Google, który zawiera parametry zapytania wskazujące typ żądanego dostępu. Google obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. W efekcie aplikacja otrzymuje kod autoryzacji, który może wymienić na token dostępu i token odświeżania.

Aplikacja powinna przechowywać token odświeżania na przyszłość i używać tokena dostępu do uzyskiwania dostępu do interfejsu Google API. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy.

Aplikacja wysyła żądanie tokena do serwera autoryzacji Google, odbiera kod autoryzacji, wymienia kod na token i używa go do wywołania punktu końcowego interfejsu API Google.

Więcej informacji znajdziesz w artykule Używanie 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 za pomocą interfejsu Google API Console, określ, że jest to zainstalowana aplikacja, a następnie jako typ aplikacji wybierz Android, Aplikacja Chrome, iOS, Platforma uniwersalna Windows (UWP) lub Aplikacja komputerowa.

W wyniku tego procesu otrzymujesz identyfikator klienta, a w niektórych przypadkach tajny klucz klienta, który należy umieścić w kodzie źródłowym aplikacji. (W tym kontekście klucz klienta oczywiście nie jest traktowany jako tajemnica).

Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google, który zawiera parametry zapytania wskazujące 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 na przyszłość i używać tokena dostępu do uzyskiwania dostępu do interfejsu Google API. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy.

Aplikacja wysyła żądanie tokena do serwera autoryzacji Google, otrzymuje kod autoryzacji, zamienia go na token i używa go do wywołania punktu końcowego interfejsu Google API.

Szczegółowe informacje znajdziesz w artykule Korzystanie z OAuth 2.0 w zainstalowanych aplikacjach.

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, który zawiera parametry zapytania wskazujące 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 umieścisz go w żądaniu do interfejsu Google API. Gdy token wygaśnie, aplikacja powtórzy ten proces.

Aplikacja JS wysyła żądanie tokena do serwera autoryzacji Google, otrzymuje token, weryfikuje go i używa do wywołania punktu końcowego interfejsu Google API.

Więcej informacji znajdziesz w artykule Używanie 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 ograniczonym wejściem, takich jak konsole do gier, kamery wideo i drukarki.

Sekwencja autoryzacji zaczyna 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óry aplikacja wyświetla użytkownikowi.

Użytkownik pobiera adres URL i kod z urządzenia, a potem przełącza się na inne urządzenie lub komputer z bardziej rozbudowanymi funkcjami wprowadzania danych. Użytkownik uruchamia przeglądarkę, przechodzi do podanego adresu URL, loguje się i wpisuje kod.

Aplikacja sprawdza adres URL Google w określonym odstępie 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 na przyszłość i używać tokena dostępu do uzyskiwania dostępu do interfejsu Google API. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy.

Użytkownik loguje się na osobnym urządzeniu z przeglądarką.

Szczegółowe informacje znajdziesz w artykule Używanie OAuth 2.0 na urządzeniach.

Konta usługi

Interfejsy API Google, takie jak interfejs 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ść interfejsowi API, ale nie wymaga to zgody użytkownika. Podobnie w scenariuszach korporacyjnych aplikacja może prosić o przekazanie dostępu 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 końcowego. Aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgody użytkownika nie jest wymagana. (w scenariuszach innych niż korzystanie z konta usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników końcowych, a czasem wymagana jest zgoda użytkownika).

Dane logowania konta usługi, które uzyskujesz z  Google API Console, obejmują wygenerowany, unikalny adres e-mail, identyfikator klienta i co najmniej 1 parę kluczy publiczno-prywatnych. Używasz identyfikatora klienta i jednego klucza prywatnego, aby utworzyć podpisany token JWT i utworzyć żą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 do uzyskiwania dostępu do interfejsu Google API. Gdy token wygaśnie, aplikacja powtórzy ten proces.

Aplikacja serwera używa tokena JWT, aby zażądać tokena z serwera autoryzacji Google, a następnie używa go do wywołania punktu końcowego interfejsu API Google. Nie ma żadnego użytkownika końcowego.

Szczegółowe informacje znajdziesz w  dokumentacji dotyczącej kont usługi.

Rozmiar tokena

Rozmiar tokenów może się różnić, ale nie może przekraczać tych limitów:

  • Kody autoryzacji: 256 bajtów
  • Tokeny dostępu: 2048 bajtów
  • Tokeny odświeżania: 512 bajtów

Tokeny dostępu zwracane przez interfejs Security Token Service API w Google Cloud mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsu Google API, ale mają inne limity rozmiaru tokenów. Szczegółowe informacje znajdziesz w  dokumentacji interfejsu API.

Google zastrzega sobie prawo do zmiany rozmiaru tokena w tych granicach, a Twoja aplikacja musi odpowiednio obsługiwać zmienne rozmiary tokenów.

Wygaśnięcie tokena odświeżania

Twój kod musi 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 skonfigurowanym dla zewnętrznego typu użytkownika i ze stanem publikowania „Testowanie” wydany jest token odświeżania, który wygasa za 7 dni, chyba że jedynymi żądanymi zakresami protokołu OAuth są podzbiór nazwy, adresu e-mail i profilu użytkownika (za pomocą zakresów userinfo.email, userinfo.profile, openid lub ich odpowiedników OpenID Connect).

Obecnie można utworzyć maksymalnie 100 tokenów odświeżania na konto Google na każdy identyfikator klienta OAuth 2.0. Po osiągnięciu limitu utworzenie nowego tokena odświeżania automatycznie unieważnia najstarszy token odświeżania 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ć na wszystkich klientach. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto dewelopera używane do testowania implementacji może.

Jeśli musisz autoryzować wiele programów, maszyn lub urządzeń, możesz ograniczyć liczbę 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żywać ich do autoryzowania niektórych klientów.

Zarządzanie zasadami kontroli sesji w organizacjach Google Cloud Platform (GCP)

Administratorzy organizacji GCP mogą wymagać częstego ponownego uwierzytelniania użytkowników podczas uzyskiwania przez nich 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 (zwanego też gcloud CLI) i dowolnej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli użytkownik ma obowiązującą zasadę kontroli sesji, po upływie czasu trwania sesji wywołania interfejsu API będą powodować błąd podobny do tego, który wystąpiłby w przypadku cofnięcia tokena odświeżania – wywołanie zakończy się niepowodzeniem z typem błędu invalid_grant; pole error_subtype można wykorzystać do rozróżnienia błędu spowodowanego cofnięciem tokena i błędu spowodowanego zasadą kontroli sesji (na przykład "error_subtype": "invalid_rapt"). Ponieważ czas trwania sesji może być bardzo krótki (od 1 do 24 godzin), w tym przypadku należy ponownie uruchomić sesję uwierzytelniania.

Podobnie nie można używać danych logowania użytkownika do wdrażania między serwerami ani zachęcać do ich używania. Jeśli dane logowania użytkownika są wdrożone na serwerze na potrzeby długotrwałych zadań lub operacji, a klient zastosuje zasady kontroli sesji wobec takich użytkowników, aplikacja serwera zakończy działanie, ponieważ nie będzie możliwości ponownego uwierzytelnienia użytkownika po wygaśnięciu sesji.

Więcej informacji o tym, jak pomóc klientom w wdrożeniu tej funkcji, znajdziesz w tym artykule dla administratorów.

Biblioteki klienta

Poniższe biblioteki klienta integrują się z popularnymi platformami, co ułatwia wdrożenie OAuth 2.0. Z czasem do bibliotek dodamy więcej funkcji.