Korzystanie z protokołu OAuth 2.0 w celu uzyskania dostępu do interfejsów API Google

API Google użyć 2.0 protokołu OAuth do uwierzytelniania i autoryzacji. Google obsługuje typowe scenariusze OAuth 2.0, takie jak te dotyczące serwerów internetowych, aplikacji zainstalowanych po stronie klienta i urządzeń z ograniczoną liczbą danych wejściowych.

Aby rozpocząć, należy uzyskać poświadczenia OAuth 2.0 klienta 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. Na interaktywnej demonstracji przy użyciu protokołu OAuth 2.0 z Google (w tym możliwość korzystania z własnego poświadczenia klienta), eksperyment z OAuth 2.0 Playground .

Ta strona zawiera przegląd scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google oraz linki do bardziej szczegółowych treści. Aby uzyskać szczegółowe informacje na temat korzystania z OAuth 2.0 do uwierzytelniania, zobacz OpenID Connect .

Podstawowe kroki

Wszystkie aplikacje korzystają z podstawowego wzorca podczas uzyskiwania dostępu do interfejsu API Google przy użyciu protokołu OAuth 2.0. Na wysokim poziomie wykonujesz pięć kroków:

1. Uzyskanie poświadczenia OAuth 2.0 z Google API Console.

Odwiedź Google API Console do uzyskania poświadczenia OAuth 2.0, takich jak identyfikator klienta i klienta tajemnicy, które są znane zarówno Google i 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 WWW tak.

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

Zanim Twoja aplikacja będzie mogła uzyskać dostęp do prywatnych danych 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óżne stopnie dostępu do wielu interfejsów API. Parametr zmienna o nazwie scope kontroli zbiór zasobów i operacji, że token dostępu pozwolenia. Podczas żądania dostępu token, aplikacja wysyła jeden lub więcej wartości w scope parametru.

Istnieje kilka sposobów zgłaszania tego żądania i różnią się one w zależności od typu tworzonej aplikacji. Na przykład aplikacja JavaScript może zażądać tokena dostępu za pomocą przekierowania przeglądarki do Google, podczas gdy aplikacja zainstalowana na urządzeniu bez przeglądarki korzysta z żądań usług internetowych.

Niektóre żądania wymagają etapu uwierzytelniania, w którym użytkownik loguje się na swoje konto Google. Po zalogowaniu użytkownik jest pytany, czy chce przyznać jedno lub więcej uprawnień, o które prosi Twoja aplikacja. Proces ten nazywany jest zgoda użytkownika.

Jeśli użytkownik przyzna co najmniej jedno uprawnienie, serwer autoryzacji Google wysyła 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 udzieli pozwolenia, serwer zwróci błąd.

Generalnie najlepszą praktyką jest stopniowe żądanie zakresów w czasie, gdy wymagany jest dostęp, 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 zezwolenia przyrostowe .

3. Zbadaj zakresy dostępu przyznane przez użytkownika.

Porównaj zakresy zawarte w odpowiedzi na token dostępu z zakresami wymaganymi do uzyskania dostępu do funkcji i funkcji Twojej 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 odpowiadać zakresowi zawartemu w odpowiedzi, nawet jeśli użytkownik przyznał wszystkie żądane zakresy. Zapoznaj się z dokumentacją każdego interfejsu API Google, aby poznać zakresy wymagane do uzyskania dostępu. Interfejs API może mapować wiele wartości ciągu zakresu do jednego zakresu dostępu, zwracając ten sam ciąg zakresu dla wszystkich wartości dozwolonych w żądaniu. Przykład: Google Ludzie API może zwrócić zakres https://www.googleapis.com/auth/contacts gdy aplikacja zwróciła użytkownik upoważnić zakresu https://www.google.com/m8/feeds/ ; metoda API Google Ludzie people.updateContact wymaga przyznanego zakresu https://www.googleapis.com/auth/contacts .

4. Wyślij token dostępu do API.

Po aplikacja uzyskuje dostęp Reklamowe, wysyła żeton do API Google w nagłówka żądania HTTP odpowiedzialnego . Możliwe jest wysyłanie tokenów jako parametrów ciągu zapytania URI, ale nie zalecamy tego, ponieważ parametry URI mogą trafić do plików dziennika, które nie są całkowicie bezpieczne. Dobrą praktyką REST jest również unikanie tworzenia niepotrzebnych nazw parametrów URI.

Tokeny dostępowe są ważne tylko dla zestawu operacji i zasobów opisanych w scope wniosku tokena. Jeśli na przykład zostanie wydany token dostępu do interfejsu Google Calendar API, nie zapewnia on dostępu do interfejsu Google Contacts API. Możesz jednak wielokrotnie wysłać ten token dostępu do interfejsu API Kalendarza Google w przypadku podobnych operacji.

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

Tokeny dostępu mają ograniczony czas życia. Jeśli Twoja aplikacja potrzebuje dostępu do interfejsu API Google po okresie istnienia pojedynczego tokenu dostępu, może uzyskać token odświeżania. Odśwież token umożliwia aplikacji uzyskanie nowych tokenów dostępu.

Scenariusze

Aplikacje serwera WWW

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwera internetowego korzystające z języków i platform, takich jak PHP, Java, 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 obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. Wynikiem jest kod autoryzacyjny, 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 API Google. Po wygaśnięciu tokenu dostępu aplikacja używa tokenu odświeżania w celu uzyskania nowego.

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

Aby uzyskać szczegółowe informacje, patrz Korzystanie z protokołu OAuth 2.0 dla aplikacji serwera 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. Po utworzeniu identyfikatora klienta poprzez Google API Console określić, że jest to aplikacja zainstalowana, a następnie wybierz aplikację Chrome, Android, iOS Uniwersalna platforma Windows (UWP) lub aplikację pulpitu jak typ aplikacji.

Wynikiem procesu jest identyfikator klienta i, w niektórych przypadkach, tajny klucz klienta, który osadzasz w kodzie źródłowym swojej 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 obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika. Wynikiem jest kod autoryzacyjny, 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 API Google. Po wygaśnięciu tokenu dostępu aplikacja używa tokenu odświeżania w celu uzyskania nowego.

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

Aby uzyskać szczegółowe informacje, patrz Korzystanie z protokołu OAuth 2.0 dla zainstalowanych aplikacji .

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 obsługuje uwierzytelnianie użytkownika, wybór sesji i zgodę użytkownika.

Wynikiem jest token dostępu, który klient powinien zweryfikować przed umieszczeniem go w żądaniu interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza proces.

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

Aby uzyskać szczegółowe informacje, patrz Korzystanie z protokołu OAuth 2.0 dla aplikacji po stronie klienta .

Aplikacje na urządzeniach z ograniczoną liczbą wejść

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje działające na urządzeniach z ograniczoną liczbą danych wejściowych, takich jak konsole do gier, kamery wideo i drukarki.

Sekwencja autoryzacji rozpoczyna się od zgłoszenia przez aplikację żądania usługi internetowej do adresu URL Google w celu uzyskania kodu autoryzacyjnego. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod, który aplikacja pokazuje użytkownikowi.

Użytkownik uzyskuje adres URL i kod z urządzenia, a następnie przełącza się na oddzielne urządzenie lub komputer z bogatszymi możliwościami wprowadzania danych. Użytkownik uruchamia przeglądarkę, przechodzi do określonego adresu URL, loguje się i wprowadza kod.

W międzyczasie aplikacja odpytuje adres URL Google w określonych odstępach czasu. Gdy użytkownik zatwierdzi dostęp, odpowiedź z serwera Google 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 API Google. Po wygaśnięciu tokenu dostępu aplikacja używa tokenu odświeżania w celu uzyskania nowego.

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

Aby uzyskać szczegółowe informacje, patrz Korzystanie z protokołu OAuth 2.0 dla urządzeń .

Konta usług

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 udowodnić swoją tożsamość w interfejsie API, ale nie jest wymagana zgoda użytkownika. Podobnie w scenariuszach korporacyjnych aplikacja może zażądać delegowanego dostępu do niektórych zasobów.

Dla tego typu serwer-serwer interakcji trzeba konto usługi, które to konto, które należy do aplikacji zamiast 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 scenariuszach bez konta usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników końcowych, a czasami wymagana jest zgoda użytkownika).

Poświadczenia konto usługi, który otrzymasz od Google API Console, to wygenerowany adres e-mail, który jest unikalny, identyfikator klienta, a co najmniej jeden pary 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. Twoja aplikacja wysyła następnie żądanie tokena do serwera autoryzacji Google OAuth 2.0, który zwraca token dostępu. Aplikacja korzysta z tokena w celu uzyskania dostępu do interfejsu Google API. Gdy token wygaśnie, aplikacja powtarza proces.

Twoja aplikacja serwera używa tokena JWT do żądania tokenu z serwera autoryzacji Google, a następnie używa go do wywołania punktu końcowego interfejsu API Google. Żaden użytkownik końcowy nie jest zaangażowany.

Szczegółowe informacje można znaleźć w dokumentacji usługi konta .

Rozmiar tokena

Tokeny mogą mieć różny rozmiar, do następujących limitów:

  • Kody autoryzacyjne: 256 bajtów
  • Tokeny dostępu: 2048 bajtów
  • Odśwież tokeny: 512 bajtów

Dostęp żetony zwrócone przez Google Cloud za token usług API są skonstruowane podobnie do Google API OAuth 2.0 tokenów dostępu, ale mają różne limity tokenów size. Szczegółowe informacje można znaleźć w dokumentacji 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.

Odśwież wygaśnięcie tokena

Musisz napisać swój kod, aby przewidzieć 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:

  • Użytkownik został odwołany dostęp do swojej aplikacji .
  • Refresh token nie był używany od sześciu 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.
  • Użytkownik należy do organizacji Google Cloud Platform, która ma obowiązujące zasady kontroli sesji.

Projekt Google Cloud Platform z ekranem akceptacji OAuth skonfigurowanym dla typu użytkownika zewnętrznego i stanem publikacji „Testowanie” otrzymuje token odświeżania, który wygasa za 7 dni.

Obecnie obowiązuje limit 50 tokenów odświeżania na konto Google na identyfikator klienta OAuth 2.0. Jeśli limit zostanie osiągnięty, utworzenie nowego tokenu odświeżania automatycznie unieważni najstarszy token odświeżania bez ostrzeżenia. Ograniczenie to nie ma zastosowania do kont usług .

Istnieje również większy limit łącznej liczby tokenów odświeżania, które może mieć konto użytkownika lub konto usługi dla wszystkich klientów. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto programisty używane do testowania implementacji może.

Jeśli trzeba autoryzować wiele programów, maszyn lub urządzeń, jednym rozwiązaniem jest ograniczenie liczby klientów, które zezwalają na konto Google, do 15 lub 20. Jeśli jesteś administratorem Google Workspace można tworzyć dodatkowych użytkowników z uprawnieniami administracyjnymi oraz użyj ich do autoryzacji niektórych klientów.

Postępowanie z zasadami kontroli sesji dla organizacji Google Cloud Platform (GCP)

Administratorzy organizacji GCP może wymagać częstego ponownego uwierzytelniania użytkowników, podczas gdy dostęp do zasobów GCP, korzystając z funkcji sterowania sesja Google Cloud . Polityka ta wpływa dostęp do Google Cloud Console, w chmurze Google SDK (znany również jako CLI gcloud) oraz dowolnej aplikacji OAuth osoby trzeciej, która wymaga zakresu Cloud Platform. Jeśli użytkownik ma politykę kontroli sesji w miejscu następnie po upływie czasu trwania sesji, twoje wywołania API będzie się błędu podobny do tego, co by się stało, jeśli token odświeżania został odwołany - połączenie nie powiedzie się z rodzajem błędu invalid_token ; podtyp błędu może być użyty do rozróżnienia między tokenem odwołania a niepowodzeniem z powodu zasad kontroli sesji. Ponieważ czas trwania sesji może być bardzo ograniczony (od 1 do 24 godzin), z tym scenariuszem należy sobie poradzić, uruchamiając ponownie sesję uwierzytelniania.

Podobnie nie wolno używać ani zachęcać do korzystania z poświadczeń użytkownika w celu wdrożenia serwera z serwerem. Jeśli poświadczenia użytkownika zostaną wdrożone na serwerze do długotrwałych zadań lub operacji, a klient zastosuje zasady kontroli sesji na takich użytkownikach, aplikacja serwera zakończy się niepowodzeniem, ponieważ nie będzie możliwości ponownego uwierzytelnienia użytkownika po wygaśnięciu sesji.

Aby uzyskać więcej informacji o tym, jak pomóc klientom wdrożyć tę funkcję, odnoszą się do tego admina-skoncentrowany artykule pomocy.

Biblioteki klienta

Poniższe biblioteki klienckie integrują się z popularnymi frameworkami, co upraszcza implementację OAuth 2.0. Z czasem do bibliotek zostanie dodanych więcej funkcji.