Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Do uwierzytelniania i autoryzacji Google API używa protokołu OAuth 2.0. Google obsługuje typowe scenariusze OAuth 2.0, takie jak te dotyczące serwera WWW, 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 aplikacja kliencka żąda tokena 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. Interaktywne przedstawienie demonstracji korzystania z protokołu OAuth 2.0 w usługach Google (w tym opcji użycia własnych danych logowania klienta) znajdziesz w narzędziu OAuth 2.0.

Na tej stronie znajduje się omówienie scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google oraz linki do bardziej szczegółowych informacji. Szczegółowe informacje o korzystaniu z uwierzytelniania OAuth 2.0 znajdziesz w artykule OpenID Connect.

Podstawowe czynności

Podczas uzyskiwania dostępu do interfejsu API Google przy użyciu OAuth 2.0 wszystkie aplikacje korzystają z podstawowego wzorca. Aby to zrobić, 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 zależy od typu tworzonej aplikacji. Na przykład aplikacja w języku JavaScript nie wymaga obiektu tajnego, ale aplikacja serwera WWW tego wymaga.

2. Uzyskanie tokena dostępu z serwera autoryzacji Google.

Aby aplikacja mogła uzyskać dostęp do danych prywatnych za pomocą interfejsu Google API, musi uzyskać token dostępu, który przyzna dostęp do tego interfejsu. 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 dozwolonych przez token dostępu. Podczas wysyłania żądania dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.

Jest kilka sposobów, aby przesłać tę prośbę, w zależności od typu tworzonej aplikacji. Na przykład aplikacja JavaScript może zażądać tokena dostępu przy użyciu przekierowania do przeglądarki, a aplikacja zainstalowana na urządzeniu bez przeglądarki korzysta z żądań usług internetowych.

Niektóre żądania wymagają kroku uwierzytelniania, podczas którego użytkownik loguje się na swoje konto Google. Po zalogowaniu się użytkownik otrzymuje pytanie, czy chce przyznać co najmniej 1 uprawnienie, o które prosi aplikacja. Ten proces jest nazywany zgodą użytkownika.

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

Ogólnie sprawdzoną metodą jest wysyłanie żądań zakresów stopniowo, gdy wymagany jest dostęp, a nie z góry. Aplikacja, która obsługuje zapisywanie wydarzenia w kalendarzu, nie może na przykład prosić o dostęp do Kalendarza Google, dopóki użytkownik nie kliknie przycisku „Dodaj do kalendarza”. Patrz Autoryzacja przyrostowa.

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

Porównaj zakresy uwzględnione w odpowiedzi tokenu dostępu z zakresami wymaganymi do uzyskania dostępu do funkcji aplikacji w zależności od powiązanego interfejsu API Google. Wyłącz wszystkie funkcje aplikacji, które nie mogą działać bez dostępu do powiązanego interfejsu API.

Zakres w żądaniu może nie odpowiadać zakresowi zawartemu w odpowiedzi, nawet jeśli użytkownik przyznał wszystkie wymagane zakresy. Informacje o zakresach wymaganych do uzyskania dostępu znajdziesz w dokumentacji każdego interfejsu API Google. Interfejs API może zmapować wiele wartości ciągu znaków na 1 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 zwracać zakres https://www.googleapis.com/auth/contacts, gdy aplikacja żą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 otrzyma token dostępu, wyśle go do interfejsu API Google 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. Zalecamy też, aby unikać tworzenia niepotrzebnych nazw parametrów URI.

Tokeny dostępu działają tylko w przypadku zbioru operacji i zasobów opisanych w scope żądaniu żądania tokena. Na przykład token dostępu przyznawany dla interfejsu Google Calendar API nie przyznaje dostępu do interfejsu Google Contacts API. Możesz jednak wielokrotnie wysłać ten token dostępu do interfejsu Google Calendar API, aby wykonywać podobne działania.

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

Tokeny dostępu są ograniczone czasowo. Jeśli aplikacja potrzebuje dostępu do interfejsu API Google poza okresem ważności tokena dostępu, może uzyskać token odświeżania. Token odświeżania pozwala aplikacji na uzyskanie nowych tokenów dostępu.

Sytuacja

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, Python, Ruby i ASP.NET.

Sekwencja autoryzacji rozpoczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie, wybieranie sesji i uzyskiwanie zgody użytkownika. Tak powstał 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 uzyskać nowy.

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

Szczegółowe informacje znajdziesz w artykule o używaniu 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. Podczas tworzenia identyfikatora klienta za pomocą Google API Console wskaż, że jest to aplikacja zainstalowana, a jako typ aplikacji wybierz Android, aplikacja Chrome, iOS, uniwersalna platforma Windows lub UWP.

Powoduje to utworzenie identyfikatora klienta, a w niektórych przypadkach – klucza klienta, który umieszczasz w kodzie źródłowym 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ę do adresu URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie, wybieranie sesji i uzyskiwanie zgody użytkownika. Tak powstał 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 uzyskać nowy.

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

Szczegółowe informacje znajdziesz w artykule o używaniu 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ę do adresu URL Google. Adres URL zawiera parametry zapytania, które wskazują typ żądanego dostępu. Google obsługuje uwierzytelnianie, wybieranie sesji i uzyskiwanie zgody użytkownika.

Wynik to token dostępu, który klient powinien zweryfikować przed umieszczeniem go w żądaniu interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza 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.

Szczegółowe informacje znajdziesz w artykule o używaniu OAuth 2.0 na potrzeby aplikacji po stronie klienta.

Aplikacje na urządzeniach z ograniczonym dostępem

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 tego, czy aplikacja wysyła żądanie usługi internetowej do adresu URL Google na potrzeby kodu autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod wyświetlany użytkownikowi.

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

Tymczasem aplikacja wysyła URL Google z określoną częstotliwością. 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 API Google. Gdy token dostępu wygaśnie, aplikacja użyje nowego, 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 Google API, takie jak Prediction API i Google Cloud Storage, mogą działać w imieniu aplikacji bez dostępu do informacji o użytkownikach. W takich przypadkach aplikacja musi potwierdzić swoją tożsamość za pomocą interfejsu API, ale użytkownik nie potrzebuje zgody użytkownika. Analogicznie w scenariuszach firmowych aplikacja może poprosić o przekazanie dostępu do niektórych zasobów.

W przypadku takich interakcji między serwerami potrzebujesz konta usługi, które należy do aplikacji, a nie do jednego użytkownika. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi, a zgoda użytkownika nie jest wymagana. (W przypadkach spoza konta usługi aplikacja wywołuje interfejsy API Google w imieniu użytkowników, a w niektórych przypadkach konieczna jest zgoda użytkownika).

Dane logowania konta usługi uzyskane od Google API Consolezawierają wygenerowany, niepowtarzalny adres e-mail, identyfikator klienta oraz co najmniej jedną parę kluczy publiczny/prywatny. Aby utworzyć podpisany token JWT i utworzyć żądanie dostępu do klucza 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 będzie powtarzać ten proces.

Aplikacja serwera używa tokena JWT do żądania tokena z serwera autoryzacji Google, a następnie używa go do wywoływania punktu końcowego interfejsu API Google. Nie występuje tu ż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 zwrócone przez Google Cloud Token Service API mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsu Google API, ale mają różne limity rozmiaru tokenów. Więcej informacji znajdziesz w dokumentacji interfejsu API.

Google zastrzega sobie prawo do zmiany rozmiaru tokena, a aplikacja musi obsługiwać odpowiednie rozmiary tokenów.

Odświeżenie ważności tokena

Musisz napisać kod, aby przewidzieć, że dany 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ł Ci dostęp do aplikacji.
  • Token odświeżania nie był używany od 6 miesięcy.
  • Użytkownik zmienił hasło, a token odświeżania zawiera zakresy Gmaila.
  • Przekroczono maksymalną dozwoloną liczbę (aktywnych) tokenów odświeżania na koncie użytkownika.
  • Użytkownik należy do organizacji Google Cloud Platform, która ma włączone zasady kontroli sesji.

Projekt Google Cloud Platform z ekranem zgody OAuth skonfigurowanym dla typu użytkownika zewnętrznego i stanem publikacji to „Testing"” otrzymuje token odświeżania wygasający w ciągu 7 dni.

Obecnie na każdym koncie Google obowiązuje limit 100 tokenów odświeżania na identyfikator klienta OAuth 2.0. 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.

Obowiązuje też większy limit łącznej liczby tokenów odświeżania na koncie użytkownika lub koncie usługi we wszystkich klientach. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto dewelopera wykorzystane do przetestowania wdrożenia może.

Jeśli chcesz autoryzować wiele programów, komputerów lub urządzeń, możesz obejść ten problem przez 15 lub 20 klientów. Jeśli jesteś administratorem Google Workspace, możesz tworzyć dodatkowych użytkowników z uprawnieniami administratora i używać ich do autoryzacji niektórych klientów.

Postępowanie 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 przy użyciu funkcji kontroli sesji Google Cloud. Ta zasada wpływa na dostęp do Google Cloud Console, pakietu SDK Google Cloud (interfejsu wiersza poleceń gcloud) oraz dowolnej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli w trakcie sesji stosowane są zasady kontroli sesji, po wygaśnięciu sesji wywołania interfejsu API będą kończyć się błędem podobnym do tego, co miałoby miejsce, jeśli token odświeżania został unieważniony – wywołanie zakończy się niepowodzeniem z typem błędu invalid_token. Typu błędu podrzędnego można użyć do odróżnienia tokena unieważnionego od nieudanej z powodu zasady kontroli sesji. Czas trwania sesji może być bardzo ograniczony (od 1 do 24 godzin), więc ten scenariusz musi przebiegać w sposób płynny, uruchamiając ponownie sesję uwierzytelniania.

Podobnie nie wolno używać danych logowania użytkownika do serwera między serwerami ani ich zachęcać. Jeśli dane logowania użytkownika są wdrażane na serwerze przez długotrwałe zadania lub operacje, a klient stosuje zasady kontroli sesji w przypadku takich użytkowników, aplikacja serwera nie zadziała, ponieważ po wygaśnięciu sesji nie będzie można ponownie uwierzytelnić użytkownika.

Więcej informacji o tym, jak pomóc klientom wdrożyć tę funkcję, znajdziesz w tym artykule pomocy dla administratorów.

Biblioteki klienta

Poniższe biblioteki klienta integrują się z popularnymi platformami, co ułatwia wdrażanie OAuth 2.0. Z czasem dodamy do bibliotek kolejne funkcje.