Ta strona została przetłumaczona przez Cloud Translation API.

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 klienta wysyła żądanie tokena dostępu do serwera autoryzacji Google, wyodrębnia token z odpowiedzi i wysyła go do interfejsu Google API, 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 korzystające z interfejsu API Google za pomocą OAuth 2.0 stosują podstawowy schemat. Ogólnie rzecz biorąc, należy wykonać 5 kroki:

1. Uzyskaj dane logowania OAuth 2.0 z Google API Console.

Odwiedź stronę 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 zależy od typu tworzonej aplikacji. Na przykład aplikacja JavaScript nie wymaga klucza tajnego, ale aplikacja serwera WWW już tak.

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

W przypadku aplikacji po stronie serwera lub aplikacji internetowych w JavaScript użyj typu klienta „internet”. Nie używaj tego typu klienta do innych aplikacji, takich jak aplikacje natywne czy mobilne.
W przypadku aplikacji na Androida użyj typu klienta „Android”.
W przypadku aplikacji na iOS i macOS użyj typu klienta „iOS”.
W przypadku aplikacji na platformę Universal Windows Platform użyj typu klienta „Universal Windows Platform”.
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”.
W przypadku interakcji między serwerami używaj kont usługi.

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.

Możesz to zrobić na kilka sposobów, które różnią się w zależności od typu tworzysz aplikację. 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 nazywa się 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, którego Twoja 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 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 podany w Twoim żądaniu może się różnić od zakresu podanego w odpowiedzi, nawet jeśli użytkownik zezwolił na wszystkie żądane zakresy. Aby poznać zakresy wymagające dostępu, zapoznaj się z dokumentacją 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.

Po uzyskaniu tokena dostępu aplikacja wysyła go do interfejsu Google API w nagłówku żądania HTTP Authorization. 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 serwera internetowego, które korzystają z języków i frameworków 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, 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 Używanie protokołu 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 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 Universal Windows (UWP) lub aplikacja na komputer.

W wyniku tego procesu otrzymujesz identyfikator klienta, a w niektórych przypadkach także tajny klucz klienta, które umieszczasz w źródle aplikacji. (W tym kontekście klucz klienta oczywiście nie jest traktowany jako tajemnica).

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 uruchamiane w przeglądarce.

Wynikiem jest token dostępu, który klient powinien zweryfikować przed dodaniem go do żądania 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 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óre 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 wyrazi zgodę na 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 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ść interfejsowi API, ale nie wymaga to zgody użytkownika. Podobnie w scenariuszach korporacyjnych 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 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 poprosić o token od serwera autoryzacji Google, a następnie używa tego tokena do wywołania punktu końcowego interfejsu Google API. 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 Google Cloud mają podobną strukturę do tokenów dostępu OAuth 2.0 interfejsów API Google, ale mają inne limity rozmiaru. 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:

Użytkownik odebrał dostęp aplikacji.
Token odświeżania nie był używany przez 6 miesięcy.
Użytkownik zmienił hasła, a token odświeżania zawiera zakresy Gmaila.
Konto użytkownika przekroczyło maksymalną liczbę przyznanych (aktywnych) tokenów odświeżania.
Jeśli administrator ustawił ograniczenia dostępu do usług wymaganych w zakresie aplikacji (błąd admin_policy_enforced).
W przypadku interfejsów API Google Cloud Platform długość sesji ustawiona przez administratora mogła zostać przekroczona.

Projekt Google Cloud Platform z ekranem zgody OAuth skonfigurowanym dla zewnętrznego typu użytkownika i ze stanem publikowania „Testuję” otrzymuje token odświeżania, który wygasa za 7 dni, chyba że jedynymi żądanymi zakresami 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 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. 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ć 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 przywilejami administracyjnymi i wykorzystać 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.

Nie możesz też używać ani zachęcać do używania danych logowania użytkowników na potrzeby wdrożenia między serwerami. 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

Biblioteki klienta wymienione poniżej integrują się z popularnymi frameworkami, co ułatwia implementowanie OAuth 2.0. Z czasem biblioteki zostaną wzbogacone o więcej funkcji.