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

Do uwierzytelniania i autoryzacji interfejsy API Google wykorzystują protokół OAuth 2.0. Google obsługuje typowe scenariusze OAuth 2.0, takie jak serwer WWW, zainstalowane po stronie klienta, aplikacje z ograniczeniami oraz aplikacje działające z ograniczonym dostępem.

Aby rozpocząć, uzyskaj dane logowania klienta OAuth 2.0 z Google API Console. Następnie 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. Aby uzyskać interaktywny pokaz korzystania z protokołu OAuth 2.0 z Google (w tym opcję używania własnych danych logowania klienta), przeprowadź eksperyment w Playground 2.0.

Ta strona zawiera omówienie scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google oraz linki do szczegółowych treści. Więcej informacji na temat uwierzytelniania OAuth 2.0 znajdziesz w artykule OpenID Connect.

Podstawowe czynności

Podczas uzyskiwania dostępu do interfejsu API Google przy użyciu protokołu OAuth wszystkie aplikacje korzystają z podstawowego wzorca. Aby to zrobić, musisz wykonać 5 czynności:

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

Otwórz stronę Google API Console, aby uzyskać dane logowania OAuth 2.0, takie jak identyfikator klienta i tajny klucz klienta, które są znane zarówno firmie Google, jak 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 wymaga tego aplikacja serwera WWW.

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

W przypadku aplikacji internetowych po stronie serwera lub JavaScriptu używaj typu klienta „internetowego”. Nie używaj tego typu klienta w innych aplikacjach, takich jak natywne czy mobilne.
W przypadku aplikacji na Androida użyj typu klienta „Android”.
W przypadku aplikacji na iOS i macOS wybierz typ klienta „iOS”.
W przypadku aplikacji uniwersalnego systemu Windows użyj typu klienta „Universal Windows Platform”.
W przypadku urządzeń z ograniczonym dostępem, takich jak telewizory lub urządzenia osadzone, używaj typu klienta „Telewizory i urządzenia wejściowe z ograniczonym dostępem”.
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 danych prywatnych 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 dozwolonych przez token dostępu. Podczas żądania tokena dostępu aplikacja wysyła co najmniej 1 wartość w parametrze scope.

To żądanie można wysłać na kilka sposobów. 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 do przeglądarki Google, natomiast 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ę za pomocą konta Google. Po zalogowaniu się użytkownik zobaczy pytanie, czy chce przyznać co najmniej 1 uprawnienia, o które prosi Twoja aplikacja. Ten proces jest nazywany zgodą użytkownika.

Jeśli użytkownik przyzna co najmniej 1 uprawnienia, serwer autoryzacji Google wysyła do aplikacji token dostępu (lub kod autoryzacji, którego może użyć aplikacja w celu uzyskania tokena dostępu) oraz listę zakresów dostępu przyznanych przez ten token. Jeśli użytkownik nie udzieli tych uprawnień, serwer zwróci błąd.

Ogólnie sprawdzoną metodą jest stopniowe wysyłanie żądań zakresów w czasie, gdy wymagany jest dostęp, a nie z góry. 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. 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 w zależności od dostępu do 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 podany w żądaniu może nie pasować do zakresu podanego w odpowiedzi, nawet jeśli użytkownik przyznał wszystkie żądane zakresy. Informacje o zakresach wymaganych do uzyskania dostępu znajdziesz w dokumentacji każdego interfejsu Google API. Interfejs API może zmapować wiele wartości ciągu znaków 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 poprosi użytkownika o autoryzację 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 Google API w nagłówku żądania autoryzacji HTTP. Możesz przesyłać tokeny jako parametry ciągu zapytania URI, ale nie jest to zalecane, ponieważ parametry URI mogą się znaleźć w plikach dziennika, które nie są całkowicie bezpieczne. Warto też używać REST, aby nie tworzyć zbędnych nazw parametrów URI.

Tokeny dostępu są ważne tylko w przypadku zbioru operacji i zasobów opisanych w scope żądania tokena. Jeśli na przykład token dostępu dla interfejsu Google Calendar API został wydany, nie przyzna dostępu do interfejsu Google Contacts API. Możesz jednak wielokrotnie wysyłać ten token dostępu do interfejsu Google Calendar API.

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

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

Sytuacja

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 czy 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. Wynikiem 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 użycia w przyszłości i używać go do uzyskiwania dostępu do interfejsu API Google. Gdy token dostępu wygaśnie, aplikacja użyje nowego, aby uzyskać nowy.

Twoja aplikacja wysyła żądanie tokena do serwera autoryzacji Google, otrzymuje kod autoryzacji, wymienia kod tokena 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 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 w Google API Console określ, że jest to aplikacja zainstalowana, a następnie wybierz typ aplikacji Android, Chrome, iOS, Universal Windows Platform (UWP) lub aplikacja komputerowa.

Proces ten prowadzi do identyfikatora klienta, a w niektórych przypadkach do tajnego 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.

Więcej informacji znajdziesz w artykule Korzystanie z 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.

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

Aplikacja JS wysyła żądanie tokena do serwera autoryzacji Google, odbiera token, weryfikuje go i używa go do wywoływania 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 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 wysłania przez aplikację żądania usługi internetowej do adresu URL Google w celu uzyskania kodu autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod wyświetlany aplikacji użytkownikowi.

Użytkownik pobiera z urządzenia adres URL i kod, a potem przełącza się na oddzielne urządzenie lub komputer z lepszymi funkcjami wprowadzania. Użytkownik uruchamia przeglądarkę, otwiera określony URL, loguje się i wpisuje kod.

Tymczasem aplikacja odpytuje 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ć go do uzyskiwania 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ądzenia.

Konta usługi

Interfejsy Google API, takie jak Prediction API i Google Cloud Storage, mogą działać w imieniu Twojej aplikacji bez dostępu do informacji o użytkownikach. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość w interfejsie API, ale nie jest wymagana zgoda użytkownika. Analogicznie w scenariuszach firmowych aplikacja może żądać dostępu do niektórych zasobów.

W przypadku takich interakcji między serwerami potrzebujesz konta usługi, które należy do Twojej aplikacji, a nie do określonego użytkownika. 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 logowania konta usługi uzyskane z Google API Consolezawierają wygenerowany adres e-mail, identyfikator klienta oraz co najmniej jedną parę kluczy publiczny/prywatny. Użyj identyfikatora klienta i 1 klucza prywatnego, aby utworzyć podpisany token JWT i utworzyć żądanie tokena dostępu w odpowiednim formacie. Aplikacja następnie wysyła żądanie tokena do serwera autoryzacji Google OAuth 2.0, który zwraca token dostępu. Aplikacja używa tokena do uzyskiwania dostępu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtarza ten proces.

Aplikacja serwera używa tokena JWT do wysyłania żądania tokena z serwera autoryzacji Google, a następnie używa go do wywoływania punktu końcowego interfejsu API Google. Bez zaangażowania użytkownika.

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 interfejs Google Cloud Token Service API mają strukturę podobną do tokenów dostępu OAuth 2.0 do 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, a aplikacja musi obsługiwać odpowiednie rozmiary tokenów.

Odśwież ważność tokena

Musisz napisać kod, aby przewidzieć możliwość, że dany 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 cofnął dostęp Twojej 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ą liczbę wykorzystanych tokenów odświeżania na koncie użytkownika.
Jeśli administrator ustawił, że usługi wymagane w zakresach aplikacji są ograniczone (błąd to admin_policy_enforced).
W przypadku interfejsów API Google Cloud Platform długość sesji ustawiona przez administratora mogła zostać przekroczona.

Projekt Google Cloud Platform z ekranem zgody OAuth skonfigurowanym dla użytkowników zewnętrznych i stanem publikowania „Testowanie” jest wystawiany jako token odświeżania wygasający w ciągu 7 dni, chyba że jedyne żądane zakresy OAuth stanowią podzbiór nazwy, adresu e-mail i profilu użytkownika (za pomocą zakresów userinfo.email, userinfo.profile, openid lub ich odpowiedników w OpenID Connect).

Obecnie na 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.

Występuje też wyższy limit łącznej liczby tokenów odświeżania, jakie konto użytkownika lub konto usługi może mieć u wszystkich klientów. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto dewelopera wykorzystane do przetestowania implementacji może to zrobić.

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

radzenie sobie z zasadami kontroli sesji w organizacjach 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 wpływa na dostęp do Google Cloud Console, pakietu SDK Google Cloud (nazywanego też interfejsem wiersza poleceń gcloud) oraz każdej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli użytkownik ma ustawioną zasadę kontroli sesji, to po jej zakończeniu wywołania interfejsu API będą wyglądać tak samo jak w przypadku unieważnienia tokena odświeżania – wywołanie zakończy się niepowodzeniem w przypadku typu błędu invalid_grant. Pole error_subtype może służyć do rozróżniania unieważnionych tokenów od zasad kontroli sesji (np. "error_subtype": "invalid_rapt"). Czas trwania sesji można ograniczyć do 2 godzin (od 1 godziny do 2 godzin).

Podobnie nie wolno używać danych logowania użytkownika do celów serwer-serwer ani ich zachęcać. Jeśli dane logowania użytkownika są wdrażane na serwerze w związku z długotrwałymi zadaniami lub operacjami, a klient stosuje 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 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 więcej funkcji.