OAuth 2.0 dla aplikacji mobilnych i komputerowych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
uwaga: Podsumowanie zawiera opis przepływów OAuth 2.0 obsługiwanych przez Google. Dzięki temu możesz sprawdzić, czy proces aplikacji został wybrany poprawnie.

Ten dokument wyjaśnia, w jaki sposób aplikacje zainstalowane na urządzeniach, takich jak telefony, tablety i komputery, korzystają z punktów końcowych Google OAuth 2.0 do autoryzowania dostępu do interfejsów API Google.

Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy zachowaniu ich nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład używać protokołu OAuth 2.0, aby uzyskiwać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.

Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach i zakłada się, że nie mogą one być tajne. Może korzystać z interfejsów API Google, gdy użytkownik jest zalogowany w aplikacji lub gdy działa w tle.

Ten proces autoryzacji jest podobny do tego używanego w aplikacjach serwerów WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otwierać przeglądarkę systemową i udostępniać lokalny identyfikator URI przekierowania, aby obsługiwać odpowiedzi z serwera autoryzacji Google.

Alternatywy

W przypadku aplikacji mobilnych możesz skorzystać z Logowania przez Google na Androida lub iOS. Biblioteki klienta logowania Google obsługują uwierzytelnianie i autoryzację użytkowników, dlatego ich implementacja może być prostsza niż opisane poniżej.

W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mają ograniczone możliwości wprowadzania tekstu (na przykład telewizory, konsole do gier, kamery i drukarki), zapoznaj się z artykułem Protokół OAuth 2.0 na telewizory i urządzenia lub Logowanie się na telewizorach i urządzeniach z ograniczonym dostępem.

Biblioteki i przykłady

Zalecamy skorzystanie z tych bibliotek i przykładów, które ułatwią Ci wdrożenie protokołu OAuth 2.0 opisanego w tym dokumencie:

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć je w API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Na liście API Library znajdują się wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, użyj funkcji wyszukiwania, aby go znaleźć, lub kliknij Wyświetl wszystko w rodzinie usług, do której należy.
  4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych uwierzytelniających

Każda aplikacja, która uzyskuje dostęp do interfejsów API Google przy użyciu OAuth 2.0, musi mieć dane uwierzytelniające, które identyfikują aplikację z serwerem OAuth 2.0 Google. Poniżej wyjaśniamy, jak utworzyć dane logowania do projektu. Dzięki temu aplikacje będą mogły korzystać z danych logowania, aby uzyskać dostęp do interfejsów API włączonych w tym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania > identyfikator klienta OAuth.
  3. W poniższych sekcjach znajdziesz typy klientów i metody przekierowań, które obsługuje serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nazwij klienta OAuth i ustaw pozostałe pola formularza.

Niestandardowy schemat URI (Android, iOS, UWP)

W przypadku aplikacji na Androida i aplikacji na iOS oraz aplikacji Universal Windows Platform (UWP) zalecany jest niestandardowy schemat URI.

Android
  1. Wybierz typ aplikacji Android.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w projekcie Credentials page , aby zidentyfikować klienta.
  3. Wpisz nazwę pakietu aplikacji na Androida. Tę wartość definiuje się w atrybucie package elementu <manifest> w pliku manifestu aplikacji.
  4. Wpisz odcisk cyfrowy certyfikatu podpisywania SHA-1 dystrybucji aplikacji.
    • Jeśli Twoja aplikacja korzysta z podpisywania aplikacji przez Google Play, skopiuj odcisk cyfrowy SHA-1 ze strony podpisywania aplikacji w Konsoli Play.
    • Jeśli zarządzasz własnym magazynem kluczy i kluczami podpisywania, użyj narzędzia keytool dołączonego do Javy, aby wydrukować informacje o certyfikatach w formacie czytelnym dla człowieka. Skopiuj wartość SHA1 z sekcji Certificate fingerprints danych wyjściowych keytool. Więcej informacji znajdziesz w artykule Uwierzytelnianie klienta w dokumentacji interfejsów API Google na Androida.
  5. Kliknij Utwórz.
iOS
  1. Wybierz typ aplikacji iOS.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w projekcie Credentials page , aby zidentyfikować klienta.
  3. Wpisz identyfikator pakietu swojej aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobów listy z informacjami o aplikacji (info.plist). Ta wartość jest najczęściej wyświetlana w panelu Ogólne lub panelu Podpisywanie i możliwości edytora projektu Xcode. Identyfikator pakietu jest też wyświetlany w sekcji „Informacje ogólne” na stronie „Informacje o aplikacji” w witrynie Apple App Store Connect.
  4. (Opcjonalnie)

    Jeśli Twoja aplikacja została opublikowana w App Store, wpisz jej identyfikator. Identyfikator sklepu to ciąg liczbowy zawarty w każdym adresie URL sklepu Apple App Store.

    1. Otwórz aplikację Apple App Store na urządzeniu z iOS lub iPadOS.
    2. Wyszukaj swoją aplikację.
    3. Kliknij przycisk Udostępnij (kwadratowy i strzałka w górę).
    4. Kliknij Skopiuj link.
    5. Wklej link w edytorze tekstu. Identyfikator App Store jest ostatnią częścią adresu URL.

      Przykład: https://apps.apple.com/app/google/id284815942

  5. (Opcjonalnie)

    Wpisz swój identyfikator zespołu. Więcej informacji znajdziesz w opisie swojego identyfikatora zespołu w dokumentacji konta Apple Developer.

  6. Kliknij Utwórz.
UWP.
  1. Wybierz typ aplikacji Universal Windows Platform.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w projekcie Credentials page , aby zidentyfikować klienta.
  3. Wpisz 12-znakowy identyfikator aplikacji ze sklepu Microsoft Store. Tę wartość możesz znaleźć w Centrum Partnerów Microsoft na stronie Tożsamość aplikacji w sekcji Zarządzanie aplikacjami.
  4. Kliknij Utwórz.

W przypadku aplikacji UWP schemat URI nie może przekraczać 39 znaków.

Adres IP sprzężenia zwrotnego (macOS, Linux, komputer z systemem Windows)

Aby otrzymać kod autoryzacji przy użyciu tego adresu URL, Twoja aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, choć nie wszystkie. Jeśli jednak platforma ją obsługuje, jest to zalecany sposób uzyskiwania kodu autoryzacji.

Gdy aplikacja otrzyma odpowiedź autoryzacyjną, powinna odpowiedzieć, wyświetlając stronę HTML z informacją o zamknięciu przeglądarki i powracającym działaniu aplikacji.

Zalecane zastosowanie Aplikacje na macOS, Linux i Windows (ale nie na uniwersalne platformy Windows)
Wartości formularzy Ustaw typ aplikacji na Aplikacja komputerowa.

Ręczne kopiowanie i wklejanie

Określ zakresy dostępu

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego może występować zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Zanim zaczniesz wdrażać autoryzację OAuth 2.0, zalecamy wskazanie zakresów, do których aplikacja będzie potrzebować dostępu.

Dokument Zakresy OAuth 2.0 interfejsu API zawiera pełną listę zakresów, których możesz używać do korzystania z interfejsów API Google.

Uzyskiwanie tokenów dostępu do protokołu OAuth 2.0

Poniższe kroki przedstawiają sposób interakcji Twojej aplikacji z serwerem OAuth 2.0 Google w celu uzyskania zgody od użytkownika na wysłanie żądania interfejsu API w jego imieniu. Aplikacja musi uzyskać tę zgodę, zanim będzie mogła wysłać żądanie interfejsu API Google, które wymaga autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikatora kodu i test zabezpieczający

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć przepływ zainstalowanej aplikacji. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodu, którego przekształcona wartość o nazwie "code_challenge" jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.

Utwórz weryfikatora kodów

code_verifier to ciąg kryptograficzny o bardzo entropicznym charakterze, który zawiera niezastrzeżone znaki [A–Z] / [a–z] / [0–9] / "-" / "." / "_" / "~" o długości nieprzekraczającej 43 znaków.

Weryfikator kodu powinien mieć wystarczającą entropię, by można było go odgadnąć.

Utwórz wyzwanie z kodem

Obsługiwane są 2 metody tworzenia testu zabezpieczającego kod.

Metody generowania testów zabezpieczających kod
S256 (zalecane) Test zabezpieczający polega na zakodowaniu SHA256 skrótu SHA256 weryfikatora kodu za pomocą Base64URL (bez dopełnienia).
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
zwykły Test zabezpieczający jest taki sam jak wartość wygenerowana powyżej.
code_challenge = code_verifier

Krok 2. Wyślij żądanie do serwera OAuth 2.0 Google

Aby uzyskać autoryzację użytkownika, wyślij żądanie do serwera autoryzacji Google na adres https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy obsługuje wyszukiwanie aktywnej sesji, uwierzytelnia użytkownika i uzyskuje zgodę użytkownika. Punkt końcowy jest dostępny tylko przez SSL i odrzuca połączenia HTTP (bez SSL).

Serwer autoryzacji obsługuje te parametry ciągu zapytania w przypadku zainstalowanych aplikacji:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.

redirect_uri Wymagany

Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Dostępnych jest kilka opcji przekierowania dla skonfigurowanych aplikacji. Musisz skonfigurować dane logowania, korzystając z określonej metody przekierowania.

Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI, wystąpi błąd redirect_uri_mismatch.

W tabeli poniżej znajdziesz odpowiednią wartość parametru redirect_uri dla każdej metody:

Wartości redirect_uri
Niestandardowy schemat URI com.example.app:redirect_uri_path

lub

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app to odwrotne zapisy DNS domeny, nad którą masz kontrolę. Schemat niestandardowy musi zawierać kropkę, aby był prawidłowy.
  • com.googleusercontent.apps.123 to odwrotny zapis DNS klienta.
  • redirect_uri_path to opcjonalny komponent ścieżki, taki jak /oauth2redirect. Pamiętaj, że ścieżka powinna zaczynać się od 1 ukośnika, który różni się od zwykłych adresów URL HTTP.
Adres IP sprzężenia zwrotnego http://127.0.0.1:port lub http://[::1]:port

Wyślij do platformy zapytanie o odpowiedni adres IP pętli i uruchom odbiornik HTTP na losowym dostępnym porcie. Zastąp port numerem portu, na którym aplikacja nasłuchuje.

Pamiętaj, że w aplikacjach mobilnych obsługa przekierowań adresów IP w pętli jest WYCOFANA.

response_type Wymagany

Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji.

Ustaw wartość parametru code na zainstalowane aplikacje.

scope Wymagany

Lista rozdzielonych spacjami, które identyfikują zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

code_challenge Zalecane

Określa zakodowany element code_verifier, który będzie używany jako test po stronie serwera podczas wymiany kodu autoryzacji. Więcej informacji znajdziesz w sekcji Tworzenie wyzwania dotyczącego kodu powyżej.

code_challenge_method Zalecane

Określa sposób kodowania code_verifier, który będzie używany podczas wymiany kodu autoryzacji. Tego parametru należy używać z parametrem code_challenge opisanym powyżej. Jeśli w żądaniu nie ma wartości code_challenge, wartość właściwości code_challenge_method jest ustawiona na plain. Jedyne obsługiwane wartości dla tego parametru to S256 lub plain.

state Zalecane

Określa dowolną wartość ciągu tekstowego, której aplikacja używa do obsługi stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na żądanie dostępu lub odmówi jego dostępu, serwer zwraca dokładną wartość, którą wyślesz jako parę name=value w identyfikatorze fragmentu adresu URL (#) w redirect_uri.

Możesz używać tego parametru do różnych celów, takich jak kierowanie użytkownika do właściwego zasobu w aplikacji, wysyłanie jednorazowych żądań czy fałszowanie żądań pochodzących z różnych witryn. Ponieważ można zgadnąć redirect_uri, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli wygenerujesz losowy ciąg znaków lub zaszyfrujesz hasz plików cookie bądź inną wartość, która będzie przechwytywać stan klienta, możesz sprawdzić odpowiedź, aby zyskać pewność, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, co zapewnia ochronę przed atakami takimi jak fałszowanie żądań w różnych witrynach. Przykład tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.

login_hint Opcjonalnie

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru do przekazania wskazówki do serwera uwierzytelniania Google. Serwer korzysta z podpowiedzi, aby uprościć przepływ logowania, wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

Ustaw wartość parametru na adres e-mail lub identyfikator sub, który jest odpowiednikiem identyfikatora Google użytkownika.

Przykładowe adresy URL autoryzacji

Na kartach poniżej znajdziesz przykładowe adresy URL autoryzacji do różnych opcji identyfikatorów URI przekierowania.

Adresy URL są identyczne, z wyjątkiem wartości parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id oraz opcjonalny parametr state. Każdy URL zawiera podziały wierszy i spacje, które zwiększają czytelność.

Niestandardowy schemat URI

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

Adres IP sprzężenia zwrotnego

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Krok 3. Google prosi użytkownika o zgodę

W tym kroku użytkownik decyduje, czy przyznać aplikacji wymagany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usługami interfejsu API Google, w ramach których prosi o dostęp z użyciem danych uwierzytelniających użytkownika i podsumowaniem zakresów dostępu, które należy przyznać. Użytkownik może następnie udzielić dostępu do co najmniej jednego zakresu, o który prosi Twoja aplikacja, lub odrzucić prośbę.

Twoja aplikacja na tym etapie nie musi nic robić, bo czeka na odpowiedź serwera OAuth 2.0 Google. Jest to informacja o tym, czy przyznano dostęp. Odpowiedź opisano w następnym kroku.

Błędy

Żądania wysyłane do punktu końcowego autoryzacji OAuth 2.0 przez Google mogą wyświetlać komunikaty o błędach wyświetlane użytkownikom, a nie oczekiwane przepływy uwierzytelniania i autoryzacji. Poniżej znajdziesz typowe kody błędów i sugerowane rozwiązania.

admin_policy_enforced

Konto Google nie może autoryzować jednego lub większej liczby zakresów, o które prosił administrator Google Workspace. Przeczytaj artykuł pomocy dla administratorów Google Workspace i określ, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace. W ten sposób dowiesz się, w jaki sposób administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami, dopóki dostęp do identyfikatora klienta OAuth nie zostanie przyznany wprost.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika niedozwolonym przez zasady OAuth 2.0.

Android

Deweloperzy aplikacji na Androida mogą napotkać ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Deweloperzy powinni zamiast tego korzystać z bibliotek Androida, takich jak Logowanie przez Google na Androida czy Fundacja OpenIDAppAuth for Android.

Deweloperzy mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w umieszczonym kliencie użytkownika i przechodzi do punktu końcowego autoryzacji OAuth 2.0 z Twojej witryny. Deweloperzy powinni zezwolić na ogólne linki w domyślnym module obsługi linków systemu operacyjnego, który zawiera zarówno moduły obsługi aplikacji na Androida, jak i domyślną aplikację przeglądarki. Biblioteka Niestandardowe karty Androida też jest obsługiwana.

iOS

Deweloperzy iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView. Deweloperzy powinni zamiast tego korzystać z bibliotek iOS, takich jak Logowanie przez Google na iOS czy AppAuth for iOS (Podstawy Fundacji).

Deweloper może napotkać ten błąd, gdy w aplikacji na iOS lub macOS otworzy się ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przejdzie do Twojej witryny przez punkt końcowy autoryzacji OAuth 2.0. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi systemu operacyjnego, który obejmuje zarówno moduły uniwersalnych linków, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController jest też obsługiwana.

org_internal

Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji User type (Typ użytkownika) artykułu pomocy o konfigurowaniu OAuth na potrzeby uzyskiwania zgody.

redirect_uri_mismatch

redirect_uri przekazany w żądaniu autoryzacji nie pasuje do autoryzowanego identyfikatora URI przekierowania dla identyfikatora klienta OAuth. Sprawdź autoryzowane identyfikatory URI przekierowania w Google API Console Credentials page.

Przekazane redirect_uri mogą być nieprawidłowe dla tego typu klienta.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób otrzymywania odpowiedzi przez autoryzację zależy od schematu identyfikatora URI przekierowania, z którego korzysta. Niezależnie od schematu odpowiedź będzie zawierać kod autoryzacji (code) lub błąd (error). Na przykład error=access_denied wskazuje, że użytkownik odrzucił żądanie.

Jeśli użytkownik przyznał aplikacji dostęp, możesz wymienić kod autoryzacji dla tokena dostępu i tokena odświeżania zgodnie z opisem w następnym kroku.

Krok 5. Wymień kod autoryzacji wymiany tokenów odświeżania i dostępu

Aby wymienić kod autoryzacji w tokenie dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw te parametry:

Pola
client_id Identyfikator klienta uzyskany z API Console Credentials page.
client_secret Obiekt tajny klienta uzyskany z API ConsoleCredentials page.
code Kod autoryzacji zwrócony z początkowego żądania.
code_verifier Weryfikator kodu utworzony w kroku 1.
grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 to pole musi mieć wartość authorization_code.
redirect_uri Jeden z identyfikatorów URI przekierowania wymienionych w projekcie API ConsoleCredentials page dla danego zasobu client_id.

Ten fragment kodu zawiera przykładowe żądanie:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

W odpowiedzi na to żądanie Google zwraca obiekt JSON zawierający token dostępu na krótki czas i token odświeżania.

Odpowiedź zawiera następujące pola:

Pola
access_token Token wysyłany przez aplikację, aby autoryzować żądanie do interfejsu API Google.
expires_in Pozostały czas życia tokena dostępu (w sekundach).
id_token Uwaga: ta właściwość jest zwracana tylko wtedy, gdy żądanie zawiera zakres tożsamości, taki jak openid, profile lub email. Wartość to token sieciowy JSON (JWT) zawierający cyfrowo podpisane informacje o tożsamości użytkownika.
refresh_token Token, za pomocą którego możesz uzyskać nowy token dostępu. Tokeny odświeżania są ważne, dopóki użytkownik ich nie unieważni. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji.
scope Zakresy dostępu przyznane przez zasadę access_token wyrażoną jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter.
token_type Typ zwracanego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer.

Poniższy fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Wywołanie interfejsów API Google

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, umieść token dostępu w żądaniu do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka Authorization nagłówka Bearer. W miarę możliwości zalecamy użycie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować, aby wywoływać wywołania interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).

Możesz wypróbować wszystkie interfejsy API Google i wyświetlić ich zakresy w Play OAuth 2.0 Playground.

Przykłady użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika z wykorzystaniem parametru ciągu zapytania access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykłady zapytań z operatorem curl

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z użyciem opcji nagłówka HTTP (co jest zalecane):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Możesz też skorzystać z parametru ciągu zapytania:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Odświeżanie tokena dostępu

Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowe poświadczenia powiązanego żądania interfejsu API. Jeśli chcesz uzyskać dostęp offline do zakresów powiązanych z tokenem, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (w tym, gdy nie ma użytkownika).

Aby odświeżyć token dostępu, aplikacja wysyła żądanie HTTPS POST do serwera autoryzacji Google (https://oauth2.googleapis.com/token) zawierającego te parametry:

Pola
client_id Identyfikator klienta uzyskany z API Console.
client_secret Obiekt tajny klienta uzyskany z API Console. client_secret nie ma zastosowania do żądań od klientów zarejestrowanych jako aplikacje na Androida, iOS lub Chrome.
grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 to pole musi mieć wartość refresh_token.
refresh_token Token odświeżania zwrócony z wymiany kodu autoryzacji.

Ten fragment kodu zawiera przykładowe żądanie:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Dopóki użytkownik nie anuluje dostępu aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Ten fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Pamiętaj, że obowiązuje limit liczby tokenów odświeżania, które mogą zostać zrealizowane: jeden limit na kombinację klienta i użytkownika i jeden na użytkownika we wszystkich klientach. Zapisz tokeny odświeżania w długoterminowym miejscu i używaj ich, dopóki będą ważne. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, może to spowodować przekroczenie tych limitów. W takim przypadku starsze tokeny odświeżania przestaną działać.

Unieważnianie tokena

W niektórych przypadkach użytkownik może unieważnić dostęp aplikacji. Użytkownik może cofnąć dostęp w ustawieniach konta. Więcej informacji znajdziesz w sekcji pomocy dotyczącej usuwania dostępu do witryn i aplikacji z witryn i aplikacji innych firm, które mają dostęp do Twojego konta.

Możliwe jest też unieważnienie przez aplikację przyznanego dostępu. Automatyczne unieważnienie jest ważne, jeśli użytkownik anuluje subskrypcję, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację znacznie się zmieniły. Oznacza to, że część procesu usuwania może obejmować żądanie interfejsu API, które zapewnia usunięcie wcześniej przyznanych uprawnień aplikacji.

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia go jako parametr:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma przypisany token odświeżania, też zostanie on unieważniony.

Jeśli odwołanie zostało pomyślnie przetworzone, kod stanu HTTP odpowiedzi będzie wynosił 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Więcej informacji

Protokół OAuth 2.0 dla aplikacji natywnych IETF wykorzystuje wiele sprawdzonych metod opisanych tutaj.