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 używają protokołu OAuth 2.0. Google obsługuje typowe scenariusze OAuth 2.0, takie jak serwer WWW, zainstalowane po stronie klienta aplikacje zainstalowane przez klienta oraz aplikacje z ograniczonym dostępem.

Zacznij od uzyskania danych 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 Google API, do którego chcesz uzyskać dostęp. Aby zobaczyć interaktywną prezentację korzystania z OAuth 2.0 w Google (w tym opcję korzystania z własnych danych logowania klienta), poeksperymentuj z placem zabaw OAuth 2.0.

Ta strona zawiera omówienie scenariuszy autoryzacji OAuth 2.0 obsługiwanych przez Google. Zawiera też linki do bardziej szczegółowych informacji. Więcej informacji o używaniu OAuth 2.0 do uwierzytelniania znajdziesz w artykule o 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 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 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 serwer WWW.

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 JavaScript użyj typu klienta „internet”. Nie używaj tego typu klienta w innych aplikacjach, takich jak aplikacje natywne czy mobilne.
W przypadku aplikacji na Androida wybierz typ klienta „Android”.
W przypadku aplikacji na iOS i macOS wybierz typ klienta „iOS”.
W przypadku aplikacji Universal Windows Platform użyj typu klienta „Universal Windows Platform”.
W przypadku ograniczonych urządzeń wejściowych, takich jak telewizory czy urządzenia wbudowane, użyj typu klienta „Telewizory i urządzenia z ograniczonym dostępem”.
W przypadku interakcji między serwerami używaj kont usługi.

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

Zanim Twoja aplikacja uzyska dostęp do prywatnych danych za pomocą interfejsu Google API, musi uzyskać token dostępu, który przyzna jej dostęp. Jeden 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 zezwala token dostępu. Podczas wysyłania tokena dostępu aplikacja wysyła co najmniej jedną wartość z parametru scope.

To żądanie można przesłać na kilka sposobów. Różnią się one w zależności od typu tworzonej aplikacji. Aplikacja JavaScript może na przykład poprosić o token dostępu za pomocą przekierowania do Google, podczas gdy aplikacja zainstalowana na urządzeniu bez przeglądarki korzysta z żądań usług internetowych.

Niektóre żądania wymagają uwierzytelnienia, na którym użytkownik loguje się przy użyciu swojego konta Google. Po zalogowaniu się użytkownik jest pytany, czy chce przyznać co najmniej 1 uprawnienie, którego żąda Twoja aplikacja. Taki proces nazywa się zgoda użytkownika.

Jeśli użytkownik przyzna co najmniej 1 uprawnienie, serwer autoryzacji Google wyśle do aplikacji token dostępu (lub kod autoryzacji, którego aplikacja może używać 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 stopniowe przesyłanie żądań dotyczących zakresów w momencie, 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 naciśnie przycisku „Dodaj do kalendarza”. Więcej informacji znajdziesz w artykule Autoryzacja przyrostowa.

3. Sprawdź zakresy dostępu przyznane przez użytkownika.

Porównaj zakresy zawarte 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 zawarty w żądaniu może nie być zgodny z zakresem określonym 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 żąda od użytkownika autoryzacji zakresu https://www.google.com/m8/feeds/. Metoda Google People API people.updateContact wymaga przypisanego zakresu https://www.googleapis.com/auth/contacts.

4. wysłać 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. Tokeny możesz wysyłać jako parametry ciągów zapytań URI, ale nie zalecamy tego, ponieważ mogą one nie być w pełni bezpieczne w plikach dziennika. Warto też używać protokołu REST i unikać tworzenia zbędnych nazw parametrów URI.

Tokeny dostępu są powiązane tylko z zestawem operacji i zasobów opisanych w żądaniu scope tokena. Jeśli na przykład dla interfejsu Google Calendar API zostanie wydany token dostępu, nie przyzna on dostępu do interfejsu Google Contacts API. W przypadku podobnych operacji możesz jednak wielokrotnie wysł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 Twoja aplikacja potrzebuje dostępu do interfejsu API Google wykraczającego poza okres 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.

Scenariusze

Aplikacje serwera WWW

Punkt końcowy Google OAuth 2.0 obsługuje aplikacje serwera WWW, które używają języków i platform takich jak PHP, Java, Python, Ruby i ASP.NET.

Sekwencja autoryzacji zaczyna się, gdy aplikacja przekierowuje przeglądarkę do adresu URL Google. Adres URL zawiera parametry zapytania, które wskazują rodzaj żądanego dostępu. Google obsługuje uwierzytelnianie użytkownika, wybór sesji i 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ć tokena dostępu do uzyskiwania 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 i używa go do wywołania punktu końcowego interfejsu API Google.

Więcej informacji znajdziesz w artykule Korzystanie z 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. Podczas tworzenia identyfikatora klienta za pomocą właściwości Google API Console określ, że jest to aplikacja zainstalowana, a jako typ aplikacji wybierz Androida, aplikację Chrome, iOS, uniwersalną platformę Windows lub UWP.

Ten proces powoduje wygenerowanie identyfikatora klienta, a w niektórych przypadkach – 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 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 działające w przeglądarce.

Wynikiem jest token dostępu, który klient powinien sprawdzić przed umieszczeniem w żądaniu do interfejsu Google API. Po wygaśnięciu tokena aplikacja powtarza cały 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.

Więcej informacji znajdziesz w artykule Korzystanie z protokołu 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 i drukarki.

Sekwencja autoryzacji zaczyna się od wysłania przez aplikację żądania do adresu URL Google na potrzeby kodu autoryzacji. Odpowiedź zawiera kilka parametrów, w tym adres URL i kod wyświetlany aplikacji przez użytkownika.

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. Uruchomienie przeglądarki, przejście do określonego adresu URL, zalogowanie się i wpisanie kodu.

Tymczasem aplikacja odpytuje adres URL Google w określonych odstępach czasu. Gdy użytkownik zaakceptuje 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 użycia w przyszłości i używać tokena dostępu 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 Korzystanie z OAuth 2.0 na urządzenia.

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żytkownikach. W takich sytuacjach aplikacja musi potwierdzić swoją tożsamość w interfejsie API, ale użytkownik nie musi wyrazić zgody. I podobnie, w scenariuszach biznesowych Twoja aplikacja może poprosić o przekazany dostęp do niektórych zasobów.

W przypadku tego typu interakcji serwer-serwer potrzebujesz konta usługi, które należy do Twojej aplikacji, a nie do użytkownika końcowego. 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 w niektórych przypadkach wymagana jest zgoda użytkownika).

Dane logowania konta usługi uzyskane z Google API Consoleobejmują wygenerowany unikalny adres e-mail, identyfikator klienta oraz co najmniej jedną parę kluczy 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 wysyła żądanie tokena do serwera autoryzacji Google OAuth 2.0, który zwraca token dostępu. Aplikacja używa tokena do uzyskania dostępu do interfejsu API Google. Gdy token wygaśnie, aplikacja powtórzy cały proces.

Aplikacja serwera używa tokena JWT do żądania tokena z serwera autoryzacji Google, a następnie używa tego tokena do wywoływania punktu końcowego interfejsu API Google. Nie jest powiązany ż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
Odśwież tokeny: 512 bajtów

Tokeny dostępu zwracane przez interfejs Security Token Service API Google Cloud mają strukturę podobną do tokenów dostępu OAuth 2.0 interfejsu Google API, ale mają inne limity rozmiaru tokenów. Więcej informacji znajdziesz w dokumentacji interfejsu API.

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

Odświeżenie ważności tokena

Musisz napisać kod, aby przewidzieć prawdopodobieństwo, że określony 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 odmówił dostępu do aplikacji.
Token odświeżania nie był używany od 6 miesięcy.
Użytkownik zmienił hasła, a token odświeżania zawiera zakresy Gmaila.
Przekroczono maksymalną liczbę aktywnych tokenów odświeżania na koncie użytkownika.
Jeśli administrator ustawił dostępność którejś z usług w zakresie aplikacji na 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żytkownika zewnętrznego i stanem publikowania „Testowanie” to token odświeżania, który wygasa za 7 dni, chyba że jedyne żądane zakresy OAuth to podzbiór nazw, adresów e-mail i profil użytkowników (za pomocą zakresów userinfo.email, userinfo.profile, openid lub ich odpowiedników w OpenID Connect).

Obecnie obowiązuje limit 100 tokenów odświeżania na konto Google przypadający 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.

Istnieje też większy limit łącznej liczby tokenów odświeżania na koncie użytkownika lub koncie usługi u wszystkich klientów. Większość zwykłych użytkowników nie przekroczy tego limitu, ale konto dewelopera użyte do przetestowania implementacji może je mieć.

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

Stosowanie zasad kontroli sesji w organizacjach korzystających z 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 (nazywanego też interfejsem wiersza poleceń gcloud) oraz każdej aplikacji OAuth innej firmy, która wymaga zakresu Cloud Platform. Jeśli w przypadku użytkownika stosowane są zasady kontroli sesji, po wygaśnięciu czasu trwania sesji wywołania interfejsu API zakończą się błędem, który wystąpiłby w przypadku unieważnienia tokena odświeżenia. Wywołanie nie powiedzie się typem błędu invalid_grant. Pole error_subtype może posłużyć do odróżniania tokena unieważnionego z powodu zasady kontroli sesji (np. "error_subtype": "invalid_rapt"). Czas trwania sesji można ograniczyć do 4 godzin z 1 godziny do 4 godzin.

Podobnie nie wolno używać danych logowania użytkownika do migracji między serwerami ani zachęcać do ich stosowania. Jeśli dane logowania użytkownika są wdrażane na serwerze w przypadku długotrwałych zadań lub operacji, a klient zastosuje do nich zasady kontroli sesji, aplikacja serwera nie zadziała, ponieważ po zakończeniu 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 upraszcza wdrażanie OAuth 2.0. Z czasem dodamy do bibliotek więcej funkcji.