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 te dotyczące serwerów internetowych, aplikacji po stronie klienta, zainstalowanych aplikacji i urządzeń z ograniczonym dostępem.

Aby rozpocząć, uzyskaj dane logowania klienta OAuth 2.0 z Google API Console. Następnie Twoja aplikacja kliencka wysyła token dostępu z serwera autoryzacji Google, wyodrębnia token z odpowiedzi i wysyła token do interfejsu Google API, do którego chcesz uzyskać dostęp. Interaktywny przykład korzystania z protokołu OAuth 2.0 z usługą Google (w tym użycia własnych danych logowania klienta) znajdziesz w witrynie Play 2.0 Playground.

Na tej stronie znajdziesz przegląd scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google oraz linki do szczegółowych treści. Szczegółowe informacje o używaniu OAuth 2.0 znajdziesz na stronie OpenID Connect.

Podstawowe czynności

Podczas uzyskiwania dostępu do interfejsu API Google przy użyciu protokołu OAuth 2.0 wszystkie aplikacje korzystają z podstawowego wzorca. 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, które są 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 internetowa.

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

Aby Twoja aplikacja mogła uzyskać dostęp do prywatnych danych za pomocą interfejsu Google API, musi uzyskać token dostępu, który przyznaje dostęp do tego interfejsu API. Pojedynczy token dostępu może przyznawać różne poziomy dostępu do wielu interfejsów API. Parametr zmiennej o nazwie scope kontroluje zestaw zasobów i operacji, na które pozwala token dostępu. Podczas żądania tokena dostępu aplikacja wysyła co najmniej jedną wartość z parametru scope.

Żądanie jest dostępne na kilka sposobów i różnią się w zależności od typu tworzonej aplikacji. Na przykład aplikacja w języku JavaScript może żądać tokena dostępu przy użyciu przekierowania przeglądarki do Google, a aplikacja zainstalowana na urządzeniu bez przeglądarki wykorzystuje żądania usług internetowych.

Niektóre żądania wymagają zalogowania się, gdy użytkownik loguje się na swoje konto Google. Po zalogowaniu się użytkownik zobaczy pytanie, czy chce przyznać co najmniej jedno uprawnienie, którego żąda Twoja aplikacja. Ten proces jest nazywany zgodą użytkownika.

Jeśli użytkownik udzieli co najmniej jednego uprawnienia, serwer autoryzacji Google wyśle do 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.

Ogólnie sprawdzoną metodą jest żądanie kolejnych zakresów w odpowiednim czasie, a nie z wyprzedzeniem. Na przykład aplikacja, która chce zapisywać wydarzenia w kalendarzu, nie powinna prosić o dostęp do Kalendarza Google, dopóki użytkownik nie kliknie przycisku „Dodaj do kalendarza”. Więcej informacji znajdziesz w artykule Autoryzacja przyrostowa.

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

Porównaj zakresy uwzględnione w odpowiedzi na token dostępu z zakresami wymaganymi do uzyskania dostępu do funkcji aplikacji w zależności od dostępu do powiązanego interfejsu API Google. Wyłącz wszystkie funkcje aplikacji bez dostępu do powiązanego interfejsu API.

Zakres uwzględniony w żądaniu może nie odpowiadać zakresowi zawartemu w odpowiedzi, nawet jeśli użytkownik udzielił wszystkich wymaganych zakresów. Zakresy wymagane do uzyskania dostępu znajdziesz w dokumentacji każdego interfejsu API Google. Interfejs API może zmapować wiele wartości ciągu znaków z jednego zakresu na jeden zakres dostępu, przywracając ten sam ciąg znaków 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 zażąda od użytkownika autoryzacji 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, wyśle go do interfejsu Google API w nagłówku żądania autoryzacji HTTP. Można przesyłać tokeny jako parametry ciągu zapytania URI, ale nie zalecamy tego, ponieważ parametry URI mogą prowadzić do plików dziennika, które nie są w pełni bezpieczne. Warto też unikać korzystania z REST, aby uniknąć tworzenia zbędnych nazw parametrów URI.

Tokeny dostępu są ważne tylko dla zestawu operacji i zasobów opisanych w scope żądania tokena. Jeśli na przykład zostanie przyznany token dostępu dla interfejsu Google Calendar API, nie przyzna on dostępu do interfejsu Google Contacts API. Możesz jednak kilka razy wysłać ten token dostępu do interfejsu Google Calendar API na potrzeby podobnych operacji.

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

Tokeny dostępu mają ograniczony czas trwania. Jeśli aplikacja potrzebuje dostępu do interfejsu API Google poza okresem ważności pojedynczego tokena dostępu, może uzyskać token odświeżania. Token odświeżania pozwala aplikacji uzyskać nowe tokeny dostępu.

Sytuacja

Aplikacje na serwerze WWW

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwerów WWW używające 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 oraz zgodę użytkownika. Wynik to 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 użycia w przyszłości i używać tokena dostępu do dostępu do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja użyje nowego, aby go uzyskać.

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

Więcej informacji znajdziesz w artykule o używaniu protokołu OAuth 2.0 na potrzeby aplikacji serwera WWW.

Zainstalowane aplikacje

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

Proces ten powoduje utworzenie identyfikatora klienta, a w niektórych przypadkach, tajnego klucza klienta, który jest umieszczony w kodzie źródłowym Twojej aplikacji. (W tym kontekście obiekt tajny klienta nie jest oczywiście traktowany jako obiekt 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 oraz zgodę użytkownika. Wynik to 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 użycia w przyszłości i używać tokena dostępu do dostępu do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja użyje nowego, aby go uzyskać.

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

Więcej informacji znajdziesz w artykule 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 oraz zgodę użytkownika.

Wynik to token dostępu, który klient powinien zweryfikować przed umieszczeniem go w żądaniu do interfejsu Google API. Gdy token wygaśnie, aplikacja powtarza cały proces.

Twoja aplikacja JS wysyła żądanie tokena do serwera autoryzacji Google, odbiera 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 objętych ograniczeniami

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje działające na urządzeniach z ograniczonym dostępem, takich jak konsole do gier, kamery wideo i drukarki.

Sekwencja autoryzacji zaczyna się od zgłoszenia przez aplikację internetową żądania adresu URL Google do autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod wyświetlany aplikacji.

Użytkownik uzyskuje adres URL i kod z urządzenia, a następnie używa innego urządzenia lub komputera z większymi możliwościami wprowadzania danych. Użytkownik uruchamia przeglądarkę, otwiera określony adres URL, loguje się i wpisuje kod.

Natomiast aplikacja odpytuje adres URL Google w określonym czasie. Gdy użytkownik zatwierdzi dostęp, odpowiedź z serwera Google będzie zawierać token dostępu oraz token odświeżania. Aplikacja powinna przechowywać token odświeżania do użycia w przyszłości i używać tokena dostępu do dostępu do interfejsu Google API. Gdy token dostępu wygaśnie, aplikacja używa nowego tokena odświeżania.

użytkownik loguje się na innym urządzeniu z przeglądarką,

Więcej informacji znajdziesz w artykule o używaniu protokołu 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żytkowniku. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość, ale nie potrzebuje zgody użytkownika. I podobnie w scenariuszach korporacyjnych Twoja 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 aplikacji, a nie do poszczególnych użytkowników. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgoda użytkownika nie jest wymagana. (W przypadku scenariuszy niezwiązanych z kontem usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników, a czasami wymagana jest zgoda użytkownika).

Dane uwierzytelniające konto usługi uzyskane z poziomu Google API Consolezawierają wygenerowany unikalny adres e-mail, identyfikator klienta oraz co najmniej 1 parę klucz publiczny/prywatny. Aby utworzyć podpisany token JWT i utworzyć żądanie tokena dostępu w odpowiednim formacie, użyj identyfikatora klienta i jednego klucza prywatnego. Aplikacja wyśle żądanie tokena do serwera autoryzacji Google OAuth 2.0, który zwróci token dostępu. Aplikacja używa tokena do uzyskania dostępu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.

Aplikacja serwera używa tokena JWT do żądania tokena z serwera autoryzacji Google, a następnie używa go do wywołania punktu końcowego Google API. Nie jest uwzględniony żaden użytkownik.

Szczegółowe informacje znajdziesz w dokumentacji konta usługi.

Rozmiar tokena

Tokeny mogą mieć różne rozmiary, maksymalnie do 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 Google Cloud Token Service API 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 ramach tych limitów. Twoja aplikacja musi odpowiednio obsługiwać rozmiary tokenów.

Odświeżenie tokena odświeżania

Musisz napisać kod, aby przewidzieć, że przydzielony 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 unieważnił dostęp Twojej aplikacji.
  • Token odświeżania nie był używany od sześciu miesięcy.
  • Użytkownik zmienił hasło, a token odświeżania zawiera zakresy Gmaila.
  • Przekroczono maksymalną liczbę przyznanych (aktywnych) tokenów odświeżania.
  • Użytkownik należy do organizacji Google Cloud Platform, w której obowiązują zasady kontroli sesji.

Projekt Google Cloud Platform z ekranem zgody OAuth skonfigurowanym dla zewnętrznego typu użytkownika ma stan publikowania „Test” i jest wydawany w ciągu 7 dni.

Obecnie na każdym koncie klienta OAuth 2.0 może przypadać maksymalnie 50 tokenów odświeżania. 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ż łączny limit tokenów odświeżania, jakie może mieć konto użytkownika lub konto usługi we wszystkich klientach. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto dewelopera używane do testowania implementacji może ulec zmianie.

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

Radzenie sobie z zasadami kontroli sesji dla organizacji 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. Ta zasada ma wpływ na dostęp do Google Cloud Console, pakietu SDK Google Cloud (zwanego też interfejsem wiersza poleceń gcloud) oraz wszelkich aplikacji OAuth innych firm, które wymagają zakresu Cloud Platform. Jeśli w przypadku użytkownika ustawiono zasady kontroli sesji, wywołania interfejsu API zakończą się niepowodzeniem w sposób podobny do tego, co miałoby miejsce w przypadku unieważnienia tokena odświeżania – wywołanie zakończy się niepowodzeniem typu błędu invalid_token. Podtyp błędu może posłużyć do odróżnienia unieważnionego tokena od błędu spowodowanego zasadą kontroli sesji. Czas trwania sesji może być bardzo ograniczony (od 1 do 24 godzin), dlatego ten scenariusz musi być płynnie przeprowadzony przez ponowne uruchomienie sesji uwierzytelniania.

W równym stopniu nie można używać danych logowania użytkownika do korzystania z serwerów podczas wdrażania ani zachęcać do korzystania z nich. Jeśli dane logowania użytkownika są wdrażane na serwerze podczas długotrwałych zadań lub operacji, a klient zastosuje do nich zasady kontroli sesji, aplikacja serwera nie zadziała, ponieważ po wygaśnięciu sesji nie będzie można ponownie uwierzytelnić użytkownika.

Więcej informacji o sposobach wdrażania tej funkcji na kontach Twoich klientów znajdziesz w tym artykule pomocy dla administratorów.

Biblioteki klienta

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