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 działające po stronie klienta, zainstalowane i na urządzeniach z ograniczonymi możliwościami wprowadzania danych.

Na początek uzyskaj dane uwierzytelniające klienta OAuth 2.0 z  Google API Console. 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ą demonstrację 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 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 z Google API Console.

Odwiedź Google API Console, aby uzyskać dane uwierzytelniające 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 klucza tajnego, ale aplikacja serwera internetowego już tak.

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

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. Pojedynczy token dostępu może przyznawać różny stopień dostępu do wielu interfejsów API. Zmienny parametr o nazwie scope kontroluje zestaw zasobów i operacji, na które zezwala token dostępu. Podczas wysyłania żądania tokena dostępu aplikacja przesyła co najmniej 1 wartość w parametrze scope.

Możesz to zrobić na kilka sposobów, w zależności od typu aplikacji, którą tworzysz. 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.

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.

Zwykle zaleca się, aby prosić o zakresy stopniowo, w momencie, gdy dostęp jest wymagany, a nie z wyprzedzeniem. 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 naciśnie 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 pasować do zakresu uwzględnionego 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 Google Calendar API, nie przyznaje dostępu do interfejsu Google Contacts API. Możesz jednak wysłać ten token dostępu do interfejsu Google Calendar 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

Aplikacje serwera WWW

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwera internetowego, 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.

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

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. Podczas tworzenia identyfikatora klienta w  Google API Console określ, że jest to aplikacja zainstalowana, a następnie wybierz jako typ aplikacji Android, aplikację Chrome, iOS, uniwersalną platformę Windows (UWP) 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 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 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.

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

Szczegółowe informacje znajdziesz w artykule o  używaniu OAuth 2.0 w aplikacjach instalowanych.

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ć przed uwzględnieniem go w żądaniu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.

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

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 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 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ż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 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 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 aplikacji, a nie do indywidualnego użytkownika końcowego. 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 z  Google API Console, obejmują wygenerowany adres e-mail, który jest unikalny, identyfikator klienta i co najmniej 1 parę kluczy publicznego i prywatnego. 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.

Aplikacja serwera używa tokena JWT do wysyłania żądań tokena do serwera autoryzacji Google, a następnie używa tokena do wywoływania punktu końcowego interfejsu API Google. Nie jest zaangażowany żaden użytkownik.

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:

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

Tokeny dostępu zwracane przez interfejs 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.

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:

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 żądane zakresy OAuth są podzbiorem zakresów dotyczących imienia i nazwiska, 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 błędem typu 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 takiej sytuacji należy wznowić sesję uwierzytelniania.

Nie możesz też używać danych logowania użytkownika do wdrożenia typu serwer-serwer ani zachęcać do tego innych osób. 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.