OAuth 2.0 dla aplikacji mobilnych i komputerowych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Przegląd zawiera podsumowanie przepływów OAuth 2.0 obsługiwanych przez Google, co może pomóc Ci w wybraniu odpowiedniego przepływu aplikacji.

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

Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji, a jednocześnie chroni ich nazwy użytkowników, hasła i inne informacje. Aplikacja może na przykład używać protokołu OAuth 2.0 do uzyskiwania od użytkowników uprawnień do przechowywania plików na Dyskach Google.

Zainstalowane aplikacje są rozpowszechniane na poszczególnych urządzeniach i zakładamy, że nie mogą one być tajne. Mają dostęp do interfejsów API Google, gdy użytkownik jest obecny w aplikacji lub gdy działa w tle.

Ten proces autoryzacji jest podobny do procesu aplikacji serwera WWW. Główna różnica polega na tym, że zainstalowane aplikacje muszą otworzyć przeglądarkę systemową i podać lokalny identyfikator URI przekierowania, aby obsługiwać odpowiedzi z serwera autoryzacji Google.

Alternatywy

W przypadku aplikacji mobilnych zalecamy korzystanie z logowania przez Google na Androidzie lub iOS. Biblioteki klienta logowania przez Google obsługują uwierzytelnianie i autoryzację użytkowników. Ich implementacja może być prostsza niż opisanych poniżej protokołu.

W przypadku aplikacji działających na urządzeniach, które nie obsługują przeglądarki systemowej lub mających ograniczone funkcje wejściowe (np. telewizory, konsole do gier, kamery czy drukarki), przeczytaj artykuł OAuth 2.0 dla telewizorów i urządzeń lub Logowanie się na telewizorach i urządzeniach z ograniczonym dostępem.

Biblioteki i próbki

Zalecamy skorzystanie z tych bibliotek i przykładów, które pomogą Ci wdrożyć procedurę OAuth 2.0 opisaną 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 interfejsu API, który chcesz włączyć, nie ma na liście, użyj wyszukiwarki, aby go znaleźć, lub kliknij Wyświetl wszystkie 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 logowania

Każda aplikacja, która używa OAuth 2.0 do korzystania z interfejsów API Google, musi mieć dane uwierzytelniające, które identyfikują ją na serwerze OAuth 2.0 Google. Poniżej znajdziesz instrukcje tworzenia danych logowania w Twoim projekcie. Twoje aplikacje mogą następnie używać danych logowania do uzyskiwania dostępu 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. Sekcje poniżej opisują typy klientów i metody przekierowania obsługiwane przez serwer autoryzacji Google. Wybierz typ klienta zalecany dla Twojej aplikacji, nazwij swojego klienta OAuth i ustaw odpowiednio inne pola w formularzu.

Niestandardowy schemat identyfikatora URI (Android, iOS, UWP)

W przypadku aplikacji na Androida, iOS i uniwersalnych platform systemu Windows (UWP) zalecany jest niestandardowy schemat URI.

Android
  1. Wybierz typ aplikacji Android.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, 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 zawartego w Javie, 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 na iOS.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, aby zidentyfikować klienta.
  3. Wpisz identyfikator pakietu aplikacji. Identyfikator pakietu to wartość klucza CFBundleIdentifier w pliku zasobu z listą właściwości informacji (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 na stronie Apple App Store Connect.
  4. (Opcjonalne)

    Wpisz identyfikator App Store swojej aplikacji, jeśli została ona opublikowana w sklepie App Store firmy Apple. Identyfikator sklepu to ciąg tekstowy, który jest częścią każdego adresu URL w 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 (symbol kwadratowy oraz strzałka w górę).
    4. Wybierz Kopiuj link.
    5. Wklej link do edytora tekstu. Identyfikator App Store to ostatnia część adresu URL.

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

  5. (Opcjonalne)

    Wpisz identyfikator zespołu. Więcej informacji znajdziesz w sekcji Znajdowanie identyfikatora zespołu w dokumentacji konta dewelopera Apple.

  6. Kliknij Utwórz.
WYP
  1. Wybierz typ aplikacji Universal Windows Platform.
  2. Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, 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 niestandardowy schemat identyfikatora 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, aplikacja musi nasłuchiwać na lokalnym serwerze WWW. Jest to możliwe na wielu platformach, ale nie na wszystkich. Jeśli jednak jest ona obsługiwana przez Twoją platformę, jest to zalecany sposób uzyskania kodu autoryzacji.

Gdy aplikacja otrzyma odpowiedź autoryzacyjną, powinna zareagować prawidłowo, wyświetlając stronę HTML z instrukcjami dotyczącymi zamknięcia przeglądarki i powrotu do aplikacji.

Zalecane użycie Aplikacje na macOS, Linux i Windows (ale nie 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 dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, który przyznają aplikacji. W związku z tym może wystąpić odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

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

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

Uzyskiwanie tokenów dostępu OAuth 2.0

Poniżej znajdziesz opis interakcji Twojej aplikacji z serwerem OAuth 2.0 Google w celu uzyskania zgody użytkownika na przesłanie żądania do interfejsu API w jego imieniu. Aplikacja musi mieć tę zgodę, zanim będzie mogła wykonać żądanie interfejsu API Google, które wymaga autoryzacji użytkownika.

Krok 1. Wygeneruj weryfikatora kodu i wyzwanie

Google obsługuje protokół Proof Key for Code Exchange (PKCE), aby zwiększyć bezpieczeństwo zainstalowanej aplikacji. Dla każdego żądania autoryzacji tworzony jest unikalny weryfikator kodów, a jego wartość przekształcona o nazwie „code_challenge” jest wysyłana do serwera autoryzacji w celu uzyskania kodu autoryzacji.

Tworzenie weryfikatora kodu

code_verifier to entropijny ciąg kryptograficzny składający się z losowych znaków [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", o minimalnej długości 43 znaków i maksymalnie 128 znaków.

Weryfikator kodu powinien mieć wystarczająco dużo entropii, aby nie mógł odgadnąć wartości.

Tworzenie testu zabezpieczającego kod

Obsługiwane są 2 metody tworzenia kodu zabezpieczającego.

Metody generowania testów zabezpieczających kod
S256 (zalecane) Wyzwanie kodu to hasz SHA256 zakodowany w formacie Base64URL (bez dopełnienia), który jest weryfikatorem kodu.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
zwykły Wyzwanie dotyczące kodu ma taką samą wartość jak weryfikator wygenerowany przez kod 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 w 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 Wymagane

Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page.

redirect_uri Wymagane

Określa, w jaki sposób serwer autoryzacji Google wysyła odpowiedź do Twojej aplikacji. Istnieje kilka opcji przekierowania dostępnych dla zainstalowanych aplikacji. Musisz skonfigurować dane logowania do konkretnej metody przekierowania.

Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania klienta OAuth 2.0, który został skonfigurowany w API Console Credentials pageklienta. Jeśli ta wartość nie będzie zgodna z autoryzowanym identyfikatorem URI, wyświetli się błąd redirect_uri_mismatch.

Tabela poniżej przedstawia odpowiednią wartość parametru redirect_uri dla każdej metody:

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

lub to

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ł ważny.
  • com.googleusercontent.apps.123 to odwrotny zapis DNS identyfikatora klienta.
  • redirect_uri_path to opcjonalny komponent ścieżki, np. /oauth2redirect. Pamiętaj, że ścieżka powinna zaczynać się od pojedynczego ukośnika, który różni się od pozostał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 sprzężenia zwrotnego i uruchom odbiornik HTTP na losowym dostępnym porcie. Zastąp port prawdziwym numerem portu nasłuchiwanego przez aplikację.

Opcja przekierowania adresu IP typu sprzężenia zwrotnego w aplikacjach mobilnych jest WYCOFANA.

response_type Wymagane

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

Ustaw wartość parametru na code dla zainstalowanych aplikacji.

scope Wymagane

Lista rozdzielonych spacjami zakresów określających zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Wartości te informują ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, jednocześnie umożliwiając użytkownikom kontrolę nad poziomem dostępu, który przyznają aplikacji. Występuje więc odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

code_challenge Zalecane

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

code_challenge_method Zalecane

Określa metodę kodowania code_verifier, która będzie używana podczas wymiany kodu autoryzacji. Tego parametru należy używać z parametrem code_challenge opisanym powyżej. Jeśli w żądaniu zawierającym właściwość code_challenge nie ma wartości właściwości code_challenge_method, jej domyślna wartość to plain. Jedyne obsługiwane wartości tego parametru to S256 lub plain.

state Zalecane

Określa wartość ciągu, której aplikacja używa do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na dostęp do aplikacji lub ją odrzuci, serwer zwraca dokładną wartość, którą wysyłasz jako parę name=value w identyfikatorze fragmentu adresu URL (#) 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 wartości jednorazowych lub fałszowanie żądań pochodzących z innych witryn. Ponieważ redirect_uri można odgadnąć, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli generujesz losowy ciąg znaków lub kodujesz hasz pliku cookie albo inną wartość, która rejestruje stan klienta, możesz zweryfikować odpowiedź, aby mieć pewność, że żądanie i odpowiedź pochodzi z tej samej przeglądarki. Zapewni to ochronę przed atakami takimi jak sfałszowanie żądań z innej witryny. Przykład tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.

login_hint Opcjonalny

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, by przekazać wskazówkę do serwera uwierzytelniania Google. Serwer używa podpowiedzi, aby uprościć proces 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

Poniższe karty pokazują przykładowe adresy URL autoryzacji dla różnych opcji identyfikatora URI przekierowania.

Adresy URL są identyczne z wartością parametru redirect_uri. Adresy URL zawierają też wymagane parametry response_type i client_id, a także opcjonalny parametr state. Każdy URL zawiera podziały wierszy i spacje, aby zwiększyć ich czytelność.

Niestandardowy schemat URI

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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 wymagane uprawnienia dostępu. Na tym etapie Google wyświetla okno z prośbą o zgodę na wykorzystanie danych zawierające nazwę aplikacji i usług interfejsu API Google, do których prosi się o dostęp, podając dane logowania użytkownika, a także podsumowanie zakresów dostępu. Użytkownik może następnie udzielić dostępu do co najmniej 1 zakresu zgłoszonego przez aplikację lub odrzucić prośbę.

Twoja aplikacja nie musi nic robić na tym etapie, ponieważ czeka na odpowiedź serwera OAuth 2.0 Google, a następnie wskazuje, czy przyznano dostęp. Tę odpowiedź wyjaśniamy w następnym kroku.

Błędy

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

admin_policy_enforced

Z powodu zasad określonych przez administratora Google Workspace konto Google nie może autoryzować co najmniej 1 zakresu, o który prosisz. Zapoznaj się z artykułem pomocy dla administratorów Google Workspace. Sprawdź, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace, aby dowiedzieć się więcej o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczonym dostępem do czasu wyraźnego przyznania dostępu klientowi OAuth.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika, który nie jest zgodny z zasadami Google dotyczącymi protokołu OAuth 2.0.

Android

Deweloperzy Androida mogą zobaczyć ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Natomiast deweloperzy powinni korzystać z bibliotek Androida, takich jak Logowanie przez Google na Androida czy AppAuth na Androida w usłudze OpenID Foundation.

Ten błąd może wystąpić, gdy aplikacja na Androida otworzy ogólny link internetowy we wbudowanym kliencie użytkownika i przejdzie do punktu końcowego autoryzacji OAuth 2.0 w Twojej witrynie. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków w systemie operacyjnym, który obejmuje zarówno moduły obsługi linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka kart niestandardowych na Androida.

iOS

Deweloperzy aplikacji na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w aplikacji WKWebView. Natomiast deweloperzy powinni korzystać z bibliotek iOS, takich jak Logowanie przez Google na iOS i AppAuth for iOS w ramach OpenID OpenID.

Ten błąd może wystąpić, gdy aplikacja na iOS lub macOS otworzy ogólny link internetowy w umieszczonym kliencie użytkownika i użytkownik przejdzie do punktu końcowego autoryzacji OAuth 2.0 w Twojej witrynie. Deweloperzy powinni zezwalać na otwieranie linków ogólnych w domyślnym module obsługi linków w systemie operacyjnym, który obejmuje zarówno moduły obsługi linków uniwersalnych, jak i domyślną aplikację przeglądarki. Obsługiwana jest też biblioteka SFSafariViewController.

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 Typ użytkownika w artykule pomocy Ustawianie ekranu zgody OAuth.

invalid_grant

Jeśli używasz narzędzia do weryfikowania i testowania kodu, parametr code_callenge jest nieprawidłowy lub go nie ma. Sprawdź, czy parametr code_challenge jest ustawiony poprawnie.

Podczas odświeżania tokena dostępu token mógł wygasnąć lub został unieważniony. Ponownie uwierzytelnij użytkownika i poproś go o zgodę na uzyskanie nowych tokenów. Jeśli ten błąd będzie się powtarzał, sprawdź, czy aplikacja została prawidłowo skonfigurowana oraz czy w żądaniu znajdują się poprawne tokeny i parametry. W przeciwnym razie konto użytkownika mogło zostać usunięte lub wyłączone.

redirect_uri_mismatch

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

Wartość podana w polu redirect_uri może być nieprawidłowa dla tego typu klienta.

Parametr redirect_uri może odnosić się do procesu pozapasmowego OAuth, który został wycofany i nie jest już obsługiwany. Aby zaktualizować integrację, zapoznaj się z przewodnikiem po migracji.

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Sposób, w jaki aplikacja otrzymuje odpowiedź autoryzacyjną, zależy od wykorzystywanego schematu identyfikatora URI przekierowania. 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 Twojej 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 na tokeny odświeżania i dostępu

Aby wymienić kod autoryzacji tokena 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 Tajny klucz klienta uzyskany z API Console Credentials page.
code Kod autoryzacji zwrócony z pierwszego żądania.
code_verifier Weryfikator kodu utworzony w kroku 1.
grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 wartość tego pola musi być ustawiona na authorization_code.
redirect_uri Jeden z identyfikatorów URI przekierowania wymienionych w projekcie w sekcji API Console Credentials page dla wybranego zasobu client_id.

Ten fragment 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 przez krótki czas i token odświeżania.

Odpowiedź zawiera następujące pola:

Pola
access_token Token, który wysyłasz przez aplikację, aby autoryzować żądanie do interfejsu API Google.
expires_in Pozostały okres dostępu do 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ścią jest token sieciowy JSON (JWT) zawierający cyfrowo podpisane informacje o tożsamości użytkownika.
refresh_token Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania są ważne do momentu anulowania dostępu użytkownika. Pamiętaj, że tokeny odświeżania są zawsze zwracane w przypadku zainstalowanych aplikacji.
scope Zakresy dostępu przyznawane przez access_token mają postać listy ciągów znaków rozdzielanych spacjami, w których jest rozróżniana wielkość liter.
token_type Typ zwróconego tokena. W tej chwili wartość tego pola jest zawsze ustawiona na Bearer.

Ten 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ływanie interfejsów API Google

Gdy aplikacja otrzyma token dostępu, możesz go używać do wywoływania interfejsu Google API w imieniu danego konta użytkownika, jeśli zakresy dostępu wymagane przez ten interfejs API zostały przyznane. W tym celu umieść w żądaniu żądanie do interfejsu API token dostępu, podając w zapytaniu parametr access_token lub wartość nagłówka HTTP Authorization Bearer. W miarę możliwości zalecamy używanie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków możesz użyć biblioteki klienta do skonfigurowania wywołań interfejsów API Google (np. podczas wywoływania interfejsu Drive Files API).

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

Przykłady HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) przy użyciu nagłówka 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 uwierzytelnionego użytkownika używającego 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 użycia opcji nagłówka HTTP (zalecane):

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

Możesz też użyć opcji 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 dane logowania dla powiązanego żądania interfejsu API. Jeśli prośba o dostęp offline do zakresów powiązanych z tokenem została wysłana, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (także wtedy, gdy go nie ma).

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

Pola
client_id Identyfikator klienta uzyskany od: API Console.
client_secret Tajny klucz klienta uzyskany z API Console. client_secret nie ma zastosowania w przypadku żądań od klientów zarejestrowanych jako aplikacje na Androida, iOS lub Chrome.
grant_type Zgodnie z definicją podaną 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 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 unieważni dostępu przyznanego aplikacji, serwer tokenów zwróci 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"
}

Istnieją limity liczby tokenów odświeżania: jeden limit dla każdej kombinacji klienta i użytkownika i jeden dla każdego klienta. Tokeny odświeżania należy zapisywać w pamięci długoterminowej i używać ich tak długo, jak długo są ważne. Jeśli aplikacja poprosi o zbyt wiele tokenów odświeżania, może dojść do 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 odwołać dostęp do aplikacji. Użytkownik może cofnąć dostęp, korzystając z ustawień konta. Więcej informacji znajdziesz w sekcji Usuwanie dostępu witryn lub aplikacji do stron i aplikacji innych firm z dostępem do Twojego konta.

Aplikacja może też automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne wtedy, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zmienią się zasoby interfejsu API wymagane przez aplikację. Inaczej mówiąc, część procesu usuwania może obejmować żądanie do interfejsu API, aby zapewnić uprawnienia przyznane wcześniej aplikacji.

Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i zawiera token 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 odpowiedni token odświeżania, zostanie on też unieważniony.

Jeśli odwołanie zostało przetworzone, kod stanu HTTP odpowiedzi będzie miał wartość 200. W przypadku warunków błędu zwracany jest kod stanu HTTP 400 wraz z kodem błędu.

Więcej informacji

Sprawdzone metody IETF (OAuth 2.0 for Native Apps) uwzględniają wiele sprawdzonych metod opisanych tutaj.