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:
- Biblioteka AppAuth na Androida
- Biblioteka AppAuth na iOS
- OAuth dla aplikacji: przykłady w systemie Windows
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:
- Open the API Library w: Google API Console.
- If prompted, select a project, or create a new one.
- 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.
- Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
- If prompted, enable billing.
- 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.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
- 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
- Wybierz typ aplikacji Android.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, aby zidentyfikować klienta.
- Wpisz nazwę pakietu aplikacji na Androida. Tę wartość definiuje się w
atrybucie
package
elementu<manifest>
w pliku manifestu aplikacji. - 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 sekcjiCertificate fingerprints
danych wyjściowych keytool. Więcej informacji znajdziesz w artykule Uwierzytelnianie klienta w dokumentacji interfejsów API Google na Androida.
- Kliknij Utwórz.
iOS
- Wybierz typ aplikacji na iOS.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, aby zidentyfikować klienta.
- 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.
- (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.
- Otwórz aplikację Apple App Store na urządzeniu z iOS lub iPadOS.
- Wyszukaj swoją aplikację.
- Kliknij przycisk Udostępnij (symbol kwadratowy oraz strzałka w górę).
- Wybierz Kopiuj link.
- Wklej link do edytora tekstu. Identyfikator App Store to ostatnia część adresu URL.
Przykład:
https://apps.apple.com/app/google/id284815942
- (Opcjonalne)
Wpisz identyfikator zespołu. Więcej informacji znajdziesz w sekcji Znajdowanie identyfikatora zespołu w dokumentacji konta dewelopera Apple.
- Kliknij Utwórz.
WYP
- Wybierz typ aplikacji Universal Windows Platform.
- Wpisz nazwę klienta OAuth. Ta nazwa jest wyświetlana w Credentials page projekcie, aby zidentyfikować klienta.
- 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.
- 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.
|
zwykły | Wyzwanie dotyczące kodu ma taką samą wartość jak weryfikator wygenerowany przez kod powyżej.
|
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 Tabela poniżej przedstawia odpowiednią wartość parametru
|
||||||
response_type |
Wymagane
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. Ustaw wartość parametru na |
||||||
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_challenge_method |
Zalecane
Określa metodę kodowania |
||||||
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ę 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ż |
||||||
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 |
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.