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, np. używane po stronie serwera WWW, po stronie klienta, zainstalowane lub używające urządzeń wejściowych o ograniczonym dostępie.

Aby rozpocząć, uzyskaj dane logowania klienta OAuth 2.0 z Google API Console. Następnie aplikacja kliencka żąda tokena dostępu z serwera autoryzacji Google, wyodrębnia token z odpowiedzi i wysyła go do interfejsu API Google, do którego chcesz uzyskać dostęp. Jeśli chcesz przeprowadzić interaktywną demonstrację używania OAuth 2.0 w Google (wraz z możliwością używania własnych danych logowania klienta), poeksperymentuj z narzędziem OAuth 2.0 Playground.

Ta strona zawiera przegląd scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google oraz linki do bardziej szczegółowych informacji. Szczegółowe informacje o używaniu OAuth 2.0 do uwierzytelniania znajdziesz na stronie OpenID Connect.

Podstawowe czynności

Wszystkie aplikacje uzyskujące dostęp do interfejsu API Google przy użyciu protokołu OAuth 2.0 postępują zgodnie z podstawowym wzorcem. Ogólnie rzecz biorąc, musisz wykonać 5 kroków:

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

Otwórz Google API Console, aby uzyskać dane logowania OAuth 2.0, takie jak identyfikator klienta i tajny klucz klienta, znane Google i Twojej aplikacji. Zestaw wartości różni się w zależności od typu tworzonej aplikacji. Na przykład aplikacja JavaScript nie wymaga obiektu tajnego, a aplikacja serwera WWW – tak.

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

W przypadku aplikacji internetowych po stronie serwera lub aplikacji internetowych JavaScript należy używać typu klienta „web”. Nie używaj tego typu klienta do żadnej innej aplikacji, na przykład aplikacji natywnej lub mobilnej.
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 platformy uniwersalnej systemu Windows użyj typu klienta „Universal Windows Platform”.
W przypadku ograniczonych urządzeń wejściowych, np. telewizora lub urządzeń do umieszczenia na stronie, wybierz typ klienta „Telewizory i urządzenia z ograniczonym dźwiękiem”.
W przypadku interakcji między serwerami użyj kont usługi.

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

Zanim aplikacja będzie mogła 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óżne poziomy dostępu do wielu interfejsów API. Parametr zmienny scope steruje zbiorem zasobów i operacji, na które zezwala token dostępu. Podczas żądania tokena dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.

Istnieje kilka sposobów na wysłanie takiej prośby. Różnią się one w zależności od typu tworzonej aplikacji. Na przykład aplikacja w języku JavaScript może zażądać tokena dostępu przy użyciu przekierowania przeglądarki do Google, a aplikacja zainstalowana na urządzeniu bez przeglądarki korzysta z żądań usług internetowych.

Niektóre żądania wymagają etapu uwierzytelniania, podczas którego użytkownik loguje się na swoje konto Google. Po zalogowaniu się użytkownik jest pytany, czy chce przyznać 1 lub więcej uprawnień, których żąda Twoja aplikacja. Ten proces nazywa się zgodą użytkownika.

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

Ogólnie sprawdzoną metodą jest wysyłanie próśb o zakresy stopniowo, w momencie, gdy jest wymagany dostęp, a nie z góry. Na przykład aplikacja, która chce umożliwić zapisywanie wydarzenia w kalendarzu, nie powinna prosić o dostęp do Kalendarza Google, dopóki użytkownik nie kliknie przycisku „Dodaj do kalendarza”. Patrz 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 zależnych od dostępu do powiązanego interfejsu Google API. Wyłącz wszystkie funkcje aplikacji, które nie działają 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 Google API. Interfejs API może zmapować wiele wartości ciągu znaków zakresu na jeden zakres dostępu, zwracając ten sam ciąg znaków dla wszystkich wartości dozwolonych w żądaniu. Przykład: interfejs Google People API może zwracać zakres https://www.googleapis.com/auth/contacts, gdy aplikacja prosi użytkownika o autoryzację zakresu https://www.google.com/m8/feeds/, a metoda Google People API people.updateContact wymaga przyznania 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 Google API w nagłówku żądania autoryzacji HTTP. Możesz wysyłać tokeny jako parametry ciągu zapytania URI, ale nie jest to zalecane, ponieważ parametry URI mogą się trafiać do plików dziennika, które nie są całkowicie bezpieczne. Warto też unikać tworzenia zbędnych nazw parametrów URI przy użyciu REST.

Tokeny dostępu są ważne tylko dla zbioru operacji i zasobów opisanych w scope żądania tokena. Na przykład token dostępu dla interfejsu Google Calendar API nie przyznaje dostępu do tego interfejsu. Możesz jednak wielokrotnie wysyłać ten token dostępu do interfejsu Google Calendar API podczas wykonywania podobnych operacji.

5. W razie potrzeby odśwież token dostępu.

Okres ważności tokenów dostępu jest ograniczony. Jeśli aplikacja będzie potrzebować dostępu do interfejsu API Google po wygaśnięciu pojedynczego tokena dostępu, może uzyskać token odświeżania. Token odświeżania pozwala aplikacji uzyskiwać nowe tokeny dostępu.

Scenariusze

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ę pod adres URL Google. Adres URL zawiera parametry zapytania wskazujące typ żądanego dostępu. Za uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika odpowiada Google. Rezultatem 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 do wykorzystania w przyszłości i używać go do uzyskiwania dostępu do interfejsu API Google. Po wygaśnięciu tokena dostępu aplikacja używa tokena odświeżania, aby uzyskać nowy.

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

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 w aplikacjach udostępnianych przez serwer WWW.

Zainstalowane aplikacje

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje instalowane na urządzeniach takich jak komputery, urządzenia mobilne i tablety. Podczas tworzenia identyfikatora klienta za pomocą Google API Console określ, że jest to zainstalowana aplikacja, a jako typ aplikacji wybierz Android, aplikacja Chrome, iOS, Universal Windows Platform (UWP) lub Aplikacja komputerowa.

W wyniku tego procesu otrzymujemy identyfikator klienta, a w niektórych przypadkach tajny klucz klienta, który musisz umieścić w kodzie źródłowym aplikacji. (W tym kontekście tajny klucz klienta oczywiście nie jest traktowany jak obiekt tajny).

Więcej informacji znajdziesz w artykule na temat używania 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.

Rezultatem 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.

Aplikacja JS wysyła żądanie tokena do serwera autoryzacji Google, otrzymuje token, weryfikuje go i używa go do wywołania 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 ograniczonym wykorzystaniem sygnału

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje, które działają na urządzeniach o ograniczonym dostępie, takich jak konsole do gier, kamery wideo i drukarki.

Sekwencja autoryzacji zaczyna 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 pobiera adres URL i kod z urządzenia, a potem przełącza się na inne urządzenie lub komputer z większymi możliwościami wprowadzania danych. Użytkownik uruchamia przeglądarkę, przechodzi do określonego adresu URL, loguje się i wpisuje kod.

Tymczasem 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 przechowywać token odświeżania do wykorzystania w przyszłości i używać go do uzyskiwania dostępu do interfejsu API Google. Po wygaśnięciu tokena dostępu aplikacja używa tokena odświeżania, aby uzyskać nowy.

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

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 na urządzeniach.

Konta usługi

Interfejsy API Google, takie jak Prediction API czy Google Cloud Storage, mogą działać w imieniu Twojej aplikacji, ale nie mają dostępu do informacji o użytkowniku. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość dla interfejsu API, ale zgoda użytkownika nie jest wymagana. Podobnie w scenariuszach firmowych 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, czyli konta należącego do Twojej aplikacji, a nie do indywidualnego użytkownika końcowego. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgoda użytkownika nie jest wymagana. (W przypadku scenariuszy, które nie dotyczą konta usługi, aplikacja wywołuje interfejsy API Google w imieniu użytkowników, co czasem wymaga zgody użytkownika).

Dane uwierzytelniające konta usługi uzyskane z Google API Consolezawierają unikalny adres e-mail, identyfikator klienta i co najmniej 1 parę kluczy publiczny/prywatny. Za pomocą identyfikatora klienta i jednego klucza prywatnego możesz utworzyć podpisany token JWT oraz żądanie tokena dostępu w odpowiednim formacie. 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 powtarza ten proces.

Aplikacja serwera używa tokena JWT, aby zażądać tokena z serwera autoryzacji Google, a następnie używa tego tokena do wywołania punktu końcowego interfejsu API Google. Żaden użytkownik końcowy nie korzysta z tej usługi.

Więcej informacji znajdziesz w dokumentacji konta usługi.

Rozmiar tokena

Rozmiar tokenów może wynosić maksymalnie:

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

Tokeny dostępu zwrócone przez Google Cloud Security Token Service API mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsu Google API, ale mają inne limity rozmiaru tokenów. Więcej informacji znajdziesz w dokumentacji interfejsu API.

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

Wygaśnięcie tokena odświeżania

Musisz napisać kod, aby przewidzieć 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 cofnął dostęp aplikacji.
Token odświeżania nie był używany od 6 miesięcy.
Użytkownik zmienił hasła, a token odświeżania zawiera zakresy Gmaila.
Na koncie użytkownika przekroczono maksymalną liczbę przyznanych (aktywnych) tokenów odświeżania.
Jeśli administrator ustawił dowolną z usług żądanych w zakresach aplikacji na Ograniczone (błąd to admin_policy_enforced).
W przypadku interfejsów API Google Cloud Platform mogła zostać przekroczona długość sesji ustawiona przez administratora.

W przypadku projektu Google Cloud Platform z ekranem zgody OAuth skonfigurowanym pod kątem zewnętrznego typu użytkownika i ze stanem publikacji „Testowanie” token odświeżania, który wygasa za 7 dni, otrzymujemy 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 równoważnikó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 zostanie osiągnięty, utworzenie nowego tokena odświeżania automatycznie unieważnia najstarszy token odświeżania (bez ostrzeżenia). Ten limit nie dotyczy kont usługi.

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ć u wszystkich klientów. Większość zwykłych użytkowników nie przekracza tego limitu, ale może to zrobić na koncie dewelopera używanym do testowania implementacji.

Jeśli chcesz autoryzować wiele programów, komputerów lub urządzeń, możesz obejść ten problem, ograniczając liczbę klientów autoryzowanych na jednym koncie Google do 15 lub 20. Jeśli jesteś administratorem Google Workspace, możesz utworzyć dodatkowych użytkowników z uprawnieniami administratora i użyć ich do autoryzacji niektórych klientów.

Obsługa zasad kontroli sesji w organizacjach Google Cloud Platform (GCP)

Administratorzy organizacji GCP mogą wymagać częstego ponownego uwierzytelniania użytkowników, gdy uzyskują oni dostęp do zasobów GCP przy użyciu funkcji kontroli sesji Google Cloud. Ta zasada wpływa na dostęp do konsoli Google Cloud, pakietu SDK Google Cloud (zwanego też interfejsem wiersza poleceń gcloud) i każdej zewnętrznej aplikacji OAuth, która wymaga zakresu Cloud Platform. Jeśli użytkownik wdrożył zasadę kontroli sesji, po upływie czasu trwania sesji wywołania interfejsu API będą kończyć się błędem podobnie do tego, co miałoby miejsce w przypadku anulowania tokena odświeżania – wywołanie zakończy się błędem typu invalid_grant. Pole error_subtype może służyć do rozróżnienia między unieważnionym tokenem a niepowodzeniem w związku z zasadą kontroli sesji (np. "error_subtype": "invalid_rapt") ze względu na konieczność zapewnienia pełnego czasu trwania sesji przez 2 godziny. Proces ten musi być bardzo ograniczony do 4 godzin.

Nie wolno też używać danych logowania użytkownika do wdrażania serwer-serwer 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 do nich zasady kontroli sesji, aplikacja serwera zakończy się niepowodzeniem, ponieważ nie będzie możliwości ponownego uwierzytelnienia użytkownika po upływie czasu trwania sesji.

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

Biblioteki klienta

Wymienione poniżej biblioteki klienta integrują się z popularnymi platformami, co ułatwia implementację protokołu OAuth 2.0. Z czasem do bibliotek będziemy dodawać kolejne funkcje.