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. aplikacje serwera WWW, aplikacje zainstalowane po stronie klienta, aplikacje na urządzenia 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 go do interfejsu API Google, do którego chcesz uzyskać dostęp. Aby zobaczyć interaktywną demonstrację używania OAuth 2.0 w usługach Google (w tym możliwość używania własnych danych logowania klienta), poeksperymentuj z narzędziem 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 materiałów. Więcej informacji 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 przez OAuth 2.0 korzystają z podstawowego wzorca. Ogólnie rzecz biorąc, wykonaj 5 kroków:

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

Otwórz stronę Google API Console, aby uzyskać dane uwierzytelniające protokołu OAuth 2.0, np. 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 kompilowanej aplikacji. Na przykład aplikacja JavaScript nie wymaga obiektu tajnego, a aplikacja serwera WWW go wymaga.

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 używaj klienta typu „internetowy”. Nie używaj tego typu klienta w żadnych innych aplikacjach, 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 platformy uniwersalnej systemu Windows użyj typu klienta „Uniwersalna platforma Windows”.
W przypadku ograniczonych urządzeń wejściowych, np. telewizora lub urządzeń umieszczonych na stronie, należy używać typu klienta „Telewizory i urządzenia z ograniczonym wejściem”.
W przypadku interakcji między serwerami użyj kont usługi.

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

Aby aplikacja mogła uzyskiwać dostęp do prywatnych danych za pomocą interfejsu Google API, musi uzyskać token dostępu, który zapewnia dostęp do tego interfejsu. Jeden token dostępu może przyznawać różne poziomy dostępu do wielu interfejsów API. Parametr zmiennej o nazwie 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 przesłania tego żądania, które różnią się w zależności od typu kompilowanej aplikacji. Na przykład aplikacja JavaScript może zażądać tokena dostępu, korzystając z przekierowania przeglądarki do Google, a aplikacja zainstalowana na urządzeniu bez przeglądarki – żądania 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ć co najmniej 1 uprawnienie, o które prosi Twoja aplikacja. Ten proces jest nazywany uzyskiwaniem zgody użytkownika.

Jeśli użytkownik przyzna co najmniej jedno uprawnienie, serwer autoryzacji Google wysyła do aplikacji token dostępu (lub kod autoryzacji, za pomocą którego aplikacja może uzyskać token 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 wysyłanie żądań o zakres stopniowo, w momencie, gdy jest wymagany dostęp, a nie z góry. Na przykład aplikacja, która chce zapisywać wydarzenie 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 i funkcji aplikacji zależnych od dostępu do powiązanego interfejsu Google API. Wyłącz wszystkie funkcje aplikacji, które nie będą działać bez dostępu do powiązanego interfejsu API.

Zakres uwzględniony w żądaniu może nie pasować do zakresu uwzględnionego w Twojej odpowiedzi, nawet jeśli użytkownik przyznał wszystkie żądane zakresy. Zakresy wymagane do uzyskania dostępu znajdziesz w dokumentacji każdego interfejsu 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 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 zażąda do użytkownika autoryzowania zakresu https://www.google.com/m8/feeds/. Metoda 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, wysyła go do interfejsu Google API w nagłówku żądania autoryzacji HTTP. Istnieje możliwość wysyłania tokenów jako parametrów ciągu zapytania URI, ale nie jest to zalecane, ponieważ parametry URI mogą trafiać do plików dziennika, które nie są całkowicie bezpieczne. Zalecamy też, by unikać tworzenia zbędnych nazw parametrów URI.

Tokeny dostępu są ważne tylko dla zbioru operacji i zasobów opisanych w scope żądania tokena. Jeśli na przykład zostanie wydany token dostępu dla interfejsu Google Calendar API, nie przyzna 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 Twoja aplikacja wymaga dostępu do interfejsu API Google po zakończeniu okresu ważności 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 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ę do adresu 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 wymieniać 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 Google API. Po wygaśnięciu tokena dostępu aplikacja wykorzystuje token odświeżania, aby uzyskać nowy.

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

Szczegółowe informacje znajdziesz w artykule o używaniu OAuth 2.0 w internetowych aplikacjach serwerowych.

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, uniwersalna platforma Windows (UWP) lub aplikacja komputerowa.

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

Szczegółowe informacje znajdziesz w artykule o używaniu 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.

Rezultatem jest token dostępu, który klient powinien zweryfikować przed uwzględnieniem go w żądaniu do interfejsu Google API. Po wygaśnięciu tokena aplikacja powtarza ten proces.

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 Google API.

Więcej informacji znajdziesz w artykule o używaniu OAuth 2.0 w aplikacjach po stronie klienta.

Aplikacje na urządzeniach z ograniczonym wejściem

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje, które działają na urządzeniach o ograniczonych danych wejściowych, takich jak konsole do gier, kamery wideo i drukarki.

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

Tymczasem aplikacja sprawdza 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 Google API. Gdy token dostępu wygaśnie, aplikacja użyje tokena odświeżania, aby uzyskać nowy.

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

Szczegółowe informacje 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żytkowniku. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość w interfejsie API, ale zgoda użytkownika nie jest wymagana. Podobnie w sytuacjach biznesowych 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, które jest kontem należącym do Twojej aplikacji, a nie do poszczególnych użytkowników. Twoja aplikacja wywołuje interfejsy API Google w imieniu konta usługi i zgoda użytkownika nie jest wymagana. (W przypadku sytuacji, 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 wygenerowany adres e-mail, identyfikator klienta i co najmniej 1 para kluczy publiczny/prywatny. Za pomocą identyfikatora klienta i jednego klucza prywatnego możesz utworzyć podpisany token JWT i żądanie tokena dostępu w odpowiednim formacie. Aplikacja wysyła następnie żądanie tokena na serwer 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 Google API. Nie korzysta z niego żaden użytkownik.

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

Rozmiar tokena

Rozmiar tokenów 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 w Google Cloud mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsu Google API, ale mają inne limity wielkości 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ć ryzyko, ż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ło, 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 Twojej aplikacji na Ograniczone (błąd to admin_policy_enforced).
W przypadku interfejsów API Google Cloud Platform czas trwania sesji ustawiony przez administratora mógł zostać przekroczony.

W przypadku projektu Google Cloud Platform, w którym ekran zgody OAuth jest skonfigurowany pod kątem użytkownika zewnętrznego, a stan publikacji to „Testowanie”, token odświeżania wygasa za 7 dni, chyba że jedynymi żądanymi zakresami protokołu OAuth są podzbiór nazwy, adresu e-mail i profilu użytkownika (poprzez zakresy userinfo.email, userinfo.profile, openid lub ich odpowiedniki w OpenID Connect).

Obecnie można utworzyć maksymalnie 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.

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 może to spowodować konto dewelopera użyte do przetestowania implementacji.

Jeśli musisz autoryzować wiele programów, komputerów lub urządzeń, możesz obejść ten problem, ograniczając liczbę klientów do 15 lub 20 na konto Google. 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 uzyskujących dostęp do zasobów GCP za pomocą funkcji kontroli sesji Google Cloud. Ta zasada wpływa na dostęp do Google Cloud Console, pakietu SDK Google Cloud (znanego też jako interfejs wiersza poleceń gcloud) i każdej zewnętrznej aplikacji OAuth, która wymaga zakresu Cloud Platform. Jeśli dla użytkownika obowiązują zasady kontroli sesji, to po upływie czasu trwania sesji wywołania interfejsu API będą generowały błędy, podobnie jak w przypadku anulowania tokena odświeżania – wywołanie zakończy się niepowodzeniem z błędem typu invalid_grant. Za pomocą pola error_subtype można odróżnić unieważniony token od błędu ze względu na zasadę kontroli sesji (na przykład "error_subtype": "invalid_rapt"). Czas oczekiwania na ponowne uruchomienie sesji może być bardzo ograniczony (od 2 godzin od ponownego uwierzytelniania)

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 w przypadku długotrwałych zadań lub operacji, a klient zastosuje do tych użytkowników zasady kontroli sesji, aplikacja serwera nie zadziała, 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 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 implementację protokołu OAuth 2.0. Z czasem dodamy więcej funkcji do bibliotek.