Ten dokument wyjaśnia, w jaki sposób aplikacje internetowe wykorzystują biblioteki klienta interfejsu API Google lub punkty końcowe Google OAuth 2.0 do implementacji autoryzacji OAuth 2.0 na potrzeby 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.
Procedura OAuth 2.0 jest przeznaczona specjalnie do autoryzacji użytkowników. Jest ona przeznaczona do aplikacji, które mogą przechowywać poufne informacje i utrzymać stan. Prawidłowo autoryzowana aplikacja serwera WWW może uzyskać dostęp do interfejsu API, gdy użytkownik wejdzie w interakcję z aplikacją lub gdy ją opuści.
Aplikacje serwera WWW często korzystają też z kont usługi do autoryzowania żądań do interfejsu API, zwłaszcza podczas wywoływania interfejsów Cloud API w celu uzyskania dostępu do danych projektu, a nie danych użytkownika. Aplikacje serwera WWW mogą używać kont usługi w połączeniu z autoryzacją użytkowników.
Biblioteki klienta
Przykłady wersji językowych tej strony wykorzystują biblioteki klienta interfejsu API Google do implementacji autoryzacji OAuth 2.0. Aby uruchomić przykładowy kod, musisz najpierw zainstalować bibliotekę klienta w swoim języku.
Gdy do obsługi procesu protokołu OAuth 2.0 używasz biblioteki klienta interfejsu API Google API, biblioteka ta obsługuje wiele działań, które w pozostałych przypadkach byłyby obsługiwane przez aplikację. Określa ona na przykład, kiedy aplikacja może używać lub odświeżać zapisane tokeny dostępu, a także kiedy aplikacja musi ponownie uzyskać zgodę. Biblioteka klienta generuje też prawidłowe przekierowania i pomaga zaimplementować moduły obsługi przekierowań, które wymieniają kody autoryzacji tokenów dostępu.
Biblioteki klienta Google API dla aplikacji po stronie serwera są dostępne w tych językach:
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.
- Wybierz typ aplikacji Aplikacja internetowa.
- Wypełnij formularz i kliknij Utwórz. Aplikacje, które używają języków i platform takich jak PHP, Java, Python, Ruby czy .NET, muszą określić autoryzowane identyfikatory URI przekierowania. Identyfikatory URI przekierowania to punkty końcowe, do których serwer OAuth 2.0 może wysyłać odpowiedzi. Te punkty końcowe muszą być zgodne z regułami weryfikacji Google.
Podczas testowania możesz określać identyfikatory URI, które odnoszą się do komputera lokalnego, np.
http://localhost:8080
. Pamiętaj, że we wszystkich przykładach w tym dokumencie jako identyfikator URI przekierowania używany jesthttp://localhost:8080
.Zalecamy zaprojektowanie punktów końcowych uwierzytelniania aplikacji, aby nie ujawniała ona kodów autoryzacji innym zasobom na stronie.
Po utworzeniu danych logowania pobierz plik client_secret.json z API Console. Bezpiecznie przechowuj plik w lokalizacji, do której dostęp ma tylko Twoja aplikacja.
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.
Zalecamy również, aby aplikacja prosiła o dostęp do zakresów autoryzacji w ramach dodatkowego procesu autoryzacji, w którym aplikacja prosi o dostęp do danych użytkownika w kontekście. Ta sprawdzona metoda pozwala użytkownikom łatwiej zrozumieć, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi.
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.
Wymagania dla konkretnego języka
Aby uruchomić przykładowy kod w tym dokumencie, musisz mieć konto Google, dostęp do internetu i przeglądarkę. Jeśli używasz jednej z bibliotek klienta interfejsu API, zapoznaj się też z wymaganiami dotyczącymi języka poniżej.
PHP
Aby uruchomić w tym dokumencie przykładowy kod PHP, musisz mieć:
- PHP w wersji 5.6 lub nowszej z zainstalowanym interfejsem wiersza poleceń i rozszerzeniem JSON.
- Narzędzie do zarządzania zależnościami Composer.
-
Biblioteka klienta interfejsów API Google dla PHP:
composer require google/apiclient:^2.10
Python
Aby uruchomić w tym dokumencie przykładowy kod w Pythonie, musisz mieć:
- Python w wersji 2.6 lub nowszej
- Narzędzie do zarządzania pakietami pip.
- Biblioteka klienta interfejsów API Google dla języka Python:
pip install --upgrade google-api-python-client
google-auth
,google-auth-oauthlib
igoogle-auth-httplib2
do autoryzacji użytkowników.pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
- Platforma aplikacji internetowej Flask Python.
pip install --upgrade flask
- Biblioteka HTTP
requests
.pip install --upgrade requests
Ruby
Aby uruchomić w tym dokumencie przykładowy kod Ruby, musisz mieć:
- Ruby w wersji 2.2.2 lub nowszej
-
Biblioteka klienta interfejsów API Google dla języka Ruby:
gem install google-api-client
-
Platforma aplikacji internetowej Sinatra Ruby
gem install sinatra
Node.js
Aby uruchomić w tym dokumencie przykładowy kod Node.js, musisz mieć:
- LTS konserwacji, aktywny LTS lub obecna wersja Node.js.
-
Klient Google Node.js Google API:
npm install googleapis
HTTP/REST
Nie musisz instalować żadnych bibliotek, aby bezpośrednio wywoływać punkty końcowe OAuth 2.0.
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.
Oto krótka lista czynności, które możesz wykonać:
- Aplikacja określa wymagane uprawnienia.
- Aplikacja przekierowuje użytkownika do Google wraz z listą wymaganych uprawnień.
- Użytkownik decyduje, czy przyznać uprawnienia aplikacji.
- Aplikacja sprawdza, co wybrał użytkownik.
- Jeśli użytkownik przyznał wymagane uprawnienia, aplikacja pobiera tokeny niezbędne do wysyłania żądań do interfejsu API w imieniu użytkownika.
Krok 1. Ustaw parametry autoryzacji
Pierwszym krokiem jest utworzenie żądania autoryzacji. To żądanie ustawia parametry identyfikujące aplikację i definiuje uprawnienia, które użytkownik będzie musiał przyznać aplikacji.
- Jeśli używasz biblioteki klienta Google do uwierzytelniania i autoryzacji OAuth 2.0, musisz utworzyć i skonfigurować obiekt definiujący te parametry.
- Jeśli bezpośrednio wywołasz punkt końcowy Google OAuth 2.0, wygenerujesz adres URL i ustawisz parametry tego adresu URL.
Na poniższych kartach zdefiniowano obsługiwane parametry autoryzacji dla serwerów WWW. Przykłady w różnych językach pokazują też, jak za pomocą biblioteki klienta lub biblioteki autoryzacji skonfigurować obiekt, który ustawia te parametry.
PHP
Fragment kodu poniżej tworzy obiekt Google\Client()
, który określa parametry w żądaniu autoryzacji.
Ten obiekt identyfikuje aplikację na podstawie informacji z pliku client_secret.json. Więcej informacji o tym pliku znajdziesz w artykule Tworzenie danych logowania. Obiekt identyfikuje też zakresy, do których aplikacja chce uzyskać dostęp, a także URL do punktu końcowego uwierzytelniania aplikacji, który będzie przetwarzać odpowiedź z serwera OAuth 2.0 Google. Na koniec kod ustawia opcjonalne parametry access_type
i include_granted_scopes
.
Na przykład ten kod żąda dostępu w trybie offline do Dysku Google tylko do odczytu:
$client = new Google\Client(); $client->setAuthConfig('client_secret.json'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); // offline access will give you both an access and refresh token so that // your app can refresh the access token without user interaction. $client->setAccessType('offline'); // Using "consent" ensures that your application always receives a refresh token. // If you are not using offline access, you can omit this. $client->setApprovalPrompt('consent'); $client->setIncludeGrantedScopes(true); // incremental auth
Żądanie zawiera te informacje:
Parametry | |||||||
---|---|---|---|---|---|---|---|
client_id |
Wymagane
Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. W pliku PHP wywołaj funkcję $client = new Google\Client(); $client->setAuthConfig('client_secret.json'); |
||||||
redirect_uri |
Wymagane
Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu procesu autoryzacji. 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 przekierowania dla podanego identyfikatora Pamiętaj, że schemat Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setRedirectUri('https://oauth2.example.com/code'); |
||||||
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. Aby ustawić tę wartość w PHP, wywołaj funkcję $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); Zalecamy, aby w miarę możliwości aplikacja prosiła o dostęp do zakresów autoryzacji w kontekście. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. |
||||||
access_type |
Zalecane
Wskazuje, czy aplikacja może odświeżać tokeny dostępu użytkownika, gdy nie ma go w przeglądarce. Prawidłowe wartości to Ustaw wartość Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setAccessType('offline'); |
||||||
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ż Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setState($sample_passthrough_value); |
||||||
include_granted_scopes |
Opcjonalny
Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setIncludeGrantedScopes(true); |
||||||
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 Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setLoginHint('None'); |
||||||
prompt |
Opcjonalny
Lista rozdzielonych spacjami (z rozróżnianiem wielkości liter) pytań, które mają zostać przedstawione użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy po raz pierwszy poprosi on o dostęp. Więcej informacji znajdziesz w artykule na temat pytania o ponowną zgodę. Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setApprovalPrompt('consent'); Możliwe wartości to:
|
Python
Ten fragment kodu wykorzystuje moduł google-auth-oauthlib.flow
do skompilowania żądania autoryzacji.
Kod tworzy obiekt Flow
, który identyfikuje aplikację na podstawie informacji z pliku client_secret.json pobranego po utworzeniu danych uwierzytelniających. Ten obiekt określa również zakresy, do których aplikacja prosi o dostęp, oraz URL do punktu końcowego uwierzytelniania aplikacji, który przetwarza odpowiedź z serwera OAuth 2.0 Google. Na koniec kod ustawia opcjonalne parametry access_type
i include_granted_scopes
.
Na przykład ten kod żąda dostępu w trybie offline do Dysku Google tylko do odczytu:
import google.oauth2.credentials import google_auth_oauthlib.flow # Use the client_secret.json file to identify the application requesting # authorization. The client ID (from that file) and access scopes are required. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) # Indicate where the API server will redirect the user after the user completes # the authorization flow. The redirect URI is required. The value must exactly # match one of the authorized redirect URIs for the OAuth 2.0 client, which you # configured in the API Console. If this value doesn't match an authorized URI, # you will get a 'redirect_uri_mismatch' error. flow.redirect_uri = 'https://www.example.com/oauth2callback' # Generate URL for request to Google's OAuth 2.0 server. # Use kwargs to set optional request parameters. authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
Żądanie zawiera te informacje:
Parametry | |||||||
---|---|---|---|---|---|---|---|
client_id |
Wymagane
Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. W Pythonie wywołaj metodę flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) |
||||||
redirect_uri |
Wymagane
Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu procesu autoryzacji. 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 przekierowania dla podanego identyfikatora Pamiętaj, że schemat Aby ustawić tę wartość w Pythonie, ustaw właściwość flow.redirect_uri = 'https://oauth2.example.com/code' |
||||||
scope |
Wymagane
Lista zakresów określających zasoby, do których Twoja 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. W Pythonie użyj tej samej metody, której używasz do określenia flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) Zalecamy, aby w miarę możliwości aplikacja prosiła o dostęp do zakresów autoryzacji w kontekście. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. |
||||||
access_type |
Zalecane
Wskazuje, czy aplikacja może odświeżać tokeny dostępu użytkownika, gdy nie ma go w przeglądarce. Prawidłowe wartości to Ustaw wartość W Pythonie ustaw parametr authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
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ż W Pythonie ustaw parametr authorization_url, state = flow.authorization_url( access_type='offline', state=sample_passthrough_value, include_granted_scopes='true') |
||||||
include_granted_scopes |
Opcjonalny
Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na W Pythonie ustaw parametr authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
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 W Pythonie ustaw parametr authorization_url, state = flow.authorization_url( access_type='offline', login_hint='None', include_granted_scopes='true') |
||||||
prompt |
Opcjonalny
Lista rozdzielonych spacjami (z rozróżnianiem wielkości liter) pytań, które mają zostać przedstawione użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy po raz pierwszy poprosi on o dostęp. Więcej informacji znajdziesz w artykule na temat pytania o ponowną zgodę. W Pythonie ustaw parametr authorization_url, state = flow.authorization_url( access_type='offline', prompt='consent', include_granted_scopes='true') Możliwe wartości to:
|
Ruby
Użyj utworzonego pliku client_secrets.json, aby skonfigurować obiekt klienta w swojej aplikacji. Podczas konfigurowania obiektu klienta określasz zakresy, do których aplikacja musi uzyskiwać dostęp, oraz adres URL punktu końcowego uwierzytelniania aplikacji, który będzie przetwarzać odpowiedź z serwera OAuth 2.0.
Na przykład ten kod żąda dostępu w trybie offline do Dysku Google tylko do odczytu:
require 'google/apis/drive_v2' require 'google/api_client/client_secrets' client_secrets = Google::APIClient::ClientSecrets.load auth_client = client_secrets.to_authorization auth_client.update!( :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly', :redirect_uri => 'http://www.example.com/oauth2callback', :additional_parameters => { "access_type" => "offline", # offline access "include_granted_scopes" => "true" # incremental auth } )
Twoja aplikacja używa obiektu klienta do wykonywania operacji OAuth 2.0, takich jak generowanie adresów URL żądań autoryzacji i stosowanie tokenów dostępu do żądań HTTP.
Node.js
Fragment kodu poniżej tworzy obiekt google.auth.OAuth2
, który określa parametry w żądaniu autoryzacji.
Ten obiekt identyfikuje aplikację na podstawie informacji z pliku client_secret.json. Aby uzyskać od użytkownika uprawnienia do pobrania tokena dostępu, zostanie on przekierowany na stronę zgody. Aby utworzyć adres URL strony z prośbą o zgodę na wykorzystanie danych:
const {google} = require('googleapis'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI * from the client_secret.json file. To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
Ważna uwaga – refresh_token
jest zwracany tylko przy pierwszej autoryzacji. Więcej informacji znajdziesz
tutaj.
HTTP/REST
Punkt końcowy OAuth 2.0 Google to https://accounts.google.com/o/oauth2/v2/auth
. Ten punkt końcowy jest dostępny tylko przez HTTPS. Zwykłe połączenia HTTP są odrzucane.
Serwer autoryzacji Google obsługuje następujące parametry ciągu zapytania dla aplikacji serwera WWW:
Parametry | |||||||
---|---|---|---|---|---|---|---|
client_id |
Wymagane
Identyfikator klienta aplikacji. Tę wartość możesz znaleźć w API Console Credentials page. |
||||||
redirect_uri |
Wymagane
Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu procesu autoryzacji. 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 przekierowania dla podanego identyfikatora Pamiętaj, że schemat |
||||||
response_type |
Wymagane
Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. Ustaw wartość parametru |
||||||
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. Zalecamy, aby w miarę możliwości aplikacja prosiła o dostęp do zakresów autoryzacji w kontekście. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. |
||||||
access_type |
Zalecane
Wskazuje, czy aplikacja może odświeżać tokeny dostępu użytkownika, gdy nie ma go w przeglądarce. Prawidłowe wartości to Ustaw wartość |
||||||
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ż |
||||||
include_granted_scopes |
Opcjonalny
Zezwala aplikacjom na używanie przyrostowej autoryzacji do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na |
||||||
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 |
||||||
prompt |
Opcjonalny
Lista rozdzielonych spacjami (z rozróżnianiem wielkości liter) pytań, które mają zostać przedstawione użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy po raz pierwszy poprosi on o dostęp. Więcej informacji znajdziesz w artykule na temat pytania o ponowną zgodę. Możliwe wartości to:
|
Krok 2. Przekieruj na serwer OAuth 2.0 Google
Przekieruj użytkownika na serwer OAuth 2.0 Google, aby rozpocząć proces uwierzytelniania i autoryzacji. Zwykle ma to miejsce, gdy aplikacja musi najpierw uzyskać dostęp do danych użytkownika. W przypadku autoryzacji przyrostowej ten krok występuje też wtedy, gdy aplikacja najpierw potrzebuje dostępu do dodatkowych zasobów, do których nie ma jeszcze uprawnień.
PHP
- Wygeneruj URL, aby poprosić o dostęp z serwera OAuth 2.0 Google:
$auth_url = $client->createAuthUrl();
- Przekieruj użytkownika na adres
$auth_url
:header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
Python
Ten przykład pokazuje, jak przekierować użytkownika do adresu URL autoryzacji przy użyciu platformy aplikacji internetowej Flask:
return flask.redirect(authorization_url)
Ruby
- Wygeneruj URL, aby poprosić o dostęp z serwera OAuth 2.0 Google:
auth_uri = auth_client.authorization_uri.to_s
- Przekieruj użytkownika na adres
auth_uri
.
Node.js
-
Użyj wygenerowanego adresu URL
authorizationUrl
z kroku 1generateAuthUrl
, aby poprosić o dostęp z serwera OAuth 2.0 Google. -
Przekieruj użytkownika na adres
authorizationUrl
.res.writeHead(301, { "Location": authorizationUrl });
HTTP/REST
Sample redirect to Google's authorization server
An example URL is shown below, with line breaks and spaces for readability.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Po utworzeniu adresu URL żądania przekieruj użytkownika do tego adresu.
Serwer OAuth 2.0 Google uwierzytelnia użytkownika i pyta go o zgodę na dostęp do żądanych zakresów. Odpowiedź jest wysyłana z powrotem do aplikacji przy użyciu określonego adresu URL przekierowania.
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_client
Tajny klucz klienta OAuth jest nieprawidłowy. Sprawdź konfigurację klienta OAuth, w tym identyfikator klienta i tajny klucz używany w tym żądaniu.
invalid_grant
Podczas odświeżania tokena dostępu lub przy użyciu autoryzacji przyrostowej mógł on 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.
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
Serwer OAuth 2.0 odpowiada na prośbę o dostęp do aplikacji przy użyciu adresu URL określonego w żądaniu.
Jeśli użytkownik zaakceptuje prośbę o dostęp, odpowiedź będzie zawierać kod autoryzacji. Jeśli użytkownik nie zaakceptuje żądania, odpowiedź będzie zawierać komunikat o błędzie. W ciągu zapytania wyświetla się kod autoryzacji lub komunikat o błędzie zwrócony przez serwer WWW, jak pokazano poniżej:
Odpowiedź błędu:
https://oauth2.example.com/auth?error=access_denied
Odpowiedź na kod autoryzacji:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
Przykładowa odpowiedź serwera OAuth 2.0
Możesz przetestować ten proces, klikając przykładowy URL, który umożliwia dostęp tylko do odczytu do metadanych plików na Dysku Google:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Po zakończeniu procesu OAuth 2.0 przekierujemy Cię na stronę http://localhost/oauth2callback
, co prawdopodobnie spowoduje błąd 404 NOT FOUND
, chyba że Twój komputer lokalny wyświetli plik pod tym adresem. Następny krok zawiera więcej informacji o tym, jakie informacje są podane w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do Twojej aplikacji.
Krok 5. Wymień kod autoryzacji na tokeny odświeżania i dostępu
Po otrzymaniu kodu autoryzacji serwer WWW może wymienić kod autoryzacji na token dostępu.
PHP
Aby wymienić kod autoryzacji dla tokena dostępu, użyj metody authenticate
:
$client->authenticate($_GET['code']);
Token dostępu możesz pobrać za pomocą metody getAccessToken
:
$access_token = $client->getAccessToken();
Python
Na stronie wywołania zwrotnego sprawdź bibliotekę serwera autoryzacji za pomocą biblioteki google-auth
. Następnie użyj metody flow.fetch_token
, aby wymienić kod autoryzacji w tej odpowiedzi na token dostępu:
state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'], state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store the credentials in the session. # ACTION ITEM for developers: # Store user's access and refresh tokens in your data store if # incorporating this code into your real app. credentials = flow.credentials flask.session['credentials'] = { 'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes}
Ruby
Aby wymienić kod autoryzacji dla tokena dostępu, użyj metody fetch_access_token!
:
auth_client.code = auth_code auth_client.fetch_access_token!
Node.js
Aby wymienić kod autoryzacji dla tokena dostępu, użyj metody getToken
:
const url = require('url'); // Receive the callback from Google's OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the OAuth 2.0 server response let q = url.parse(req.url, true).query; // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); }
HTTP/REST
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. |
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=https%3A//oauth2.example.com/code& 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.
Token odświeżania jest zwracany tylko wtedy, gdy Twoja aplikacja ustawia parametr access_type
na wartość offline
w żądaniu wysłanym do serwera autoryzacji Google.
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). |
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.
To pole jest obecne w tej odpowiedzi tylko wtedy, gdy w początkowym żądaniu ustawisz parametr access_type na serwer autoryzacji Google.
|
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" }
Błędy
Podczas wymiany kodu autoryzacji tokena dostępu zamiast oczekiwanej odpowiedzi może zostać wyświetlony następujący błąd. Typowe kody błędów i sugerowane rozwiązania znajdziesz poniżej.
invalid_grant
Podany kod autoryzacji jest nieprawidłowy lub ma nieprawidłowy format. Poproś o nowy kod, restartując proces OAuth, aby ponownie poprosić użytkownika o zgodę.
Wywoływanie interfejsów API Google
PHP
Token dostępu pozwala wywoływać interfejsy API Google, wykonując te czynności:
- Jeśli musisz zastosować token dostępu do nowego obiektu
Google\Client
(na przykład jeśli token dostępu został zapisany w sesji użytkownika), użyj metodysetAccessToken
:$client->setAccessToken($access_token);
- Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Aby utworzyć obiekt usługi, podaj autoryzowany obiekt
Google\Client
konstruktorowi interfejsu API, który chcesz wywołać. Aby na przykład wywołać interfejs Drive API:$drive = new Google\Service\Drive($client);
- Wysyłanie żądań do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi.
Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika:
$files = $drive->files->listFiles(array())->getItems();
Python
Gdy otrzymasz token dostępu, aplikacja może go wykorzystać do autoryzowania żądań do interfejsu API w imieniu danego konta użytkownika lub konta usługi. Użyj danych logowania danego użytkownika, aby utworzyć obiekt usługi dla interfejsu API, który chcesz wywołać, a następnie użyć go do wysyłania autoryzowanych żądań do interfejsu API.
- Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Aby utworzyć obiekt usługi, wywołaj metodę
build
bibliotekigoogleapiclient.discovery
za pomocą nazwy i wersji interfejsu API oraz danych logowania użytkownika: Aby na przykład wywołać wersję 2 interfejsu API Dysku:from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials)
- Wysyłanie żądań do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi.
Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika:
files = drive.files().list().execute()
Ruby
Wykorzystaj obiekt auth_client
, aby wywołać interfejsy API Google, wykonując te czynności:
- Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać.
Aby na przykład wywołać wersję 2 interfejsu API Dysku:
drive = Google::Apis::DriveV2::DriveService.new
- Ustaw dane logowania w usłudze:
drive.authorization = auth_client
- Żądania do usługi API są wysyłane przy użyciu interfejsu udostępnionego przez obiekt usługi.
Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika:
files = drive.list_files
Autoryzację możesz też dostarczać dla poszczególnych metod, podając parametr options
:
files = drive.list_files(options: { authorization: auth_client })
Node.js
Po uzyskaniu tokena dostępu i ustawieniu go na obiekt OAuth2
użyj go do wywoływania interfejsów API Google. Twoja aplikacja może używać tego tokena do autoryzowania żądań do interfejsu API w imieniu danego konta użytkownika lub konta usługi. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać.
const { google } = require('googleapis'); // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } });
HTTP/REST
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
Pełny przykład
W poniższym przykładzie tworzona jest lista plików w formacie JSON na Dysku Google użytkownika po uwierzytelnieniu użytkownika i uzyskaniu przez aplikację zgody na dostęp do metadanych Dysku użytkownika.
PHP
Aby uruchomić ten przykład:
- W polu API Consoledodaj adres URL maszyny lokalnej do listy adresów URL przekierowania. Na przykład dodaj
http://localhost:8080
. - Utwórz nowy katalog i zmień go. Na przykład:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- Zainstaluj bibliotekę klienta Google API dla języka PHP za pomocą Composer:
composer require google/apiclient:^2.10
- Utwórz pliki
index.php
ioauth2callback.php
z poniższą treścią. - Uruchom przykład z serwerem WWW skonfigurowanym do obsługi języka PHP. Jeśli używasz PHP w wersji 5.6 lub nowszej, możesz używać wbudowanego testowego serwera WWW PHP:
php -S localhost:8080 ~/php-oauth2-example
index.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfig('client_secrets.json'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); if (isset($_SESSION['access_token']) && $_SESSION['access_token']) { $client->setAccessToken($_SESSION['access_token']); $drive = new Google\Service\Drive($client); $files = $drive->files->listFiles(array())->getItems(); echo json_encode($files); } else { $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
oauth2callback.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfigFile('client_secrets.json'); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); if (! isset($_GET['code'])) { $auth_url = $client->createAuthUrl(); header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL)); } else { $client->authenticate($_GET['code']); $_SESSION['access_token'] = $client->getAccessToken(); $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
Python
W tym przykładzie używamy platformy Flask. Uruchamia ona aplikację internetową pod adresem http://localhost:8080
, która umożliwia testowanie przepływu OAuth 2.0. Jeśli go otworzysz, zobaczysz 4 linki:
- Przetestuj żądanie do interfejsu API: ten link prowadzi do strony, która próbuje wykonać przykładowe żądanie do interfejsu API. W razie potrzeby rozpocznie proces autoryzacji. Jeśli operacja się powiedzie, na stronie zostanie wyświetlona odpowiedź interfejsu API.
- Przetestuj bezpośrednio proces uwierzytelniania:ten link prowadzi do strony, która próbuje przekierować użytkownika przez proces autoryzacji. Aplikacja prosi o uprawnienia do przesyłania w imieniu użytkownika autoryzowanych żądań do interfejsu API.
- Unieważnij bieżące dane logowania: ten link prowadzi do strony, która unieważnia uprawnienia przyznane aplikacji przez użytkownika.
- Wyczyść dane logowania do sesji Flask: ten link powoduje wyczyszczenie danych uwierzytelniających przechowywanych w sesji Flask. Dzięki temu zobaczysz, co się stanie, jeśli użytkownik, który przyznał już uprawnienia aplikacji, wykona żądanie API w nowej sesji. Pozwala też wyświetlić odpowiedź interfejsu API, która zostałaby odebrana przez użytkownika w sytuacji, gdy użytkownik cofnął jej uprawnienia i aplikacja próbowała autoryzować żądanie z użyciem unieważnionego tokena dostępu.
# -*- coding: utf-8 -*- import os import flask import requests import google.oauth2.credentials import google_auth_oauthlib.flow import googleapiclient.discovery # This variable specifies the name of a file that contains the OAuth 2.0 # information for this application, including its client_id and client_secret. CLIENT_SECRETS_FILE = "client_secret.json" # This OAuth 2.0 access scope allows for full read/write access to the # authenticated user's account and requires requests to use an SSL connection. SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly'] API_SERVICE_NAME = 'drive' API_VERSION = 'v2' app = flask.Flask(__name__) # Note: A secret key is included in the sample so that it works. # If you use this code in your application, replace this with a truly secret # key. See https://flask.palletsprojects.com/quickstart/#sessions. app.secret_key = 'REPLACE ME - this value is here as a placeholder.' @app.route('/') def index(): return print_index_table() @app.route('/test') def test_api_request(): if 'credentials' not in flask.session: return flask.redirect('authorize') # Load credentials from the session. credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) drive = googleapiclient.discovery.build( API_SERVICE_NAME, API_VERSION, credentials=credentials) files = drive.files().list().execute() # Save credentials back to session in case access token was refreshed. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. flask.session['credentials'] = credentials_to_dict(credentials) return flask.jsonify(**files) @app.route('/authorize') def authorize(): # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES) # The URI created here must exactly match one of the authorized redirect URIs # for the OAuth 2.0 client, which you configured in the API Console. If this # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch' # error. flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true') # Store the state so the callback can verify the auth server response. flask.session['state'] = state return flask.redirect(authorization_url) @app.route('/oauth2callback') def oauth2callback(): # Specify the state when creating the flow in the callback so that it can # verified in the authorization server response. state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES, state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) # Use the authorization server's response to fetch the OAuth 2.0 tokens. authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store credentials in the session. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. credentials = flow.credentials flask.session['credentials'] = credentials_to_dict(credentials) return flask.redirect(flask.url_for('test_api_request')) @app.route('/revoke') def revoke(): if 'credentials' not in flask.session: return ('You need to <a href="/authorize">authorize</a> before ' + 'testing the code to revoke credentials.') credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) revoke = requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'}) status_code = getattr(revoke, 'status_code') if status_code == 200: return('Credentials successfully revoked.' + print_index_table()) else: return('An error occurred.' + print_index_table()) @app.route('/clear') def clear_credentials(): if 'credentials' in flask.session: del flask.session['credentials'] return ('Credentials have been cleared.<br><br>' + print_index_table()) def credentials_to_dict(credentials): return {'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes} def print_index_table(): return ('<table>' + '<tr><td><a href="/test">Test an API request</a></td>' + '<td>Submit an API request and see a formatted JSON response. ' + ' Go through the authorization flow if there are no stored ' + ' credentials for the user.</td></tr>' + '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' + '<td>Go directly to the authorization flow. If there are stored ' + ' credentials, you still might not be prompted to reauthorize ' + ' the application.</td></tr>' + '<tr><td><a href="/revoke">Revoke current credentials</a></td>' + '<td>Revoke the access token associated with the current user ' + ' session. After revoking credentials, if you go to the test ' + ' page, you should see an <code>invalid_grant</code> error.' + '</td></tr>' + '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' + '<td>Clear the access token currently stored in the user session. ' + ' After clearing the token, if you <a href="/test">test the ' + ' API request</a> again, you should go back to the auth flow.' + '</td></tr></table>') if __name__ == '__main__': # When running locally, disable OAuthlib's HTTPs verification. # ACTION ITEM for developers: # When running in production *do not* leave this option enabled. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' # Specify a hostname and port that are set as a valid redirect URI # for your API project in the Google API Console. app.run('localhost', 8080, debug=True)
Ruby
W tym przykładzie używamy platformy Sinatra.
require 'google/apis/drive_v2' require 'google/api_client/client_secrets' require 'json' require 'sinatra' enable :sessions set :session_secret, 'setme' get '/' do unless session.has_key?(:credentials) redirect to('/oauth2callback') end client_opts = JSON.parse(session[:credentials]) auth_client = Signet::OAuth2::Client.new(client_opts) drive = Google::Apis::DriveV2::DriveService.new files = drive.list_files(options: { authorization: auth_client }) "<pre>#{JSON.pretty_generate(files.to_h)}</pre>" end get '/oauth2callback' do client_secrets = Google::APIClient::ClientSecrets.load auth_client = client_secrets.to_authorization auth_client.update!( :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly', :redirect_uri => url('/oauth2callback')) if request['code'] == nil auth_uri = auth_client.authorization_uri.to_s redirect to(auth_uri) else auth_client.code = request['code'] auth_client.fetch_access_token! auth_client.client_secret = nil session[:credentials] = auth_client.to_json redirect to('/') end end
Node.js
Aby uruchomić ten przykład:
-
W polu API Consoledodaj adres URL maszyny lokalnej do listy adresów URL przekierowania. Na przykład dodaj
http://localhost
. - Sprawdź, czy masz zainstalowany pakiet LTS konserwacji, aktywny LTS lub bieżącą wersję Node.js.
-
Utwórz nowy katalog i zmień go. Na przykład:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
Utwórz pliki
main.js
z treścią znajdującą się poniżej. -
Uruchom przykład:
node .\main.js
main.js
const http = require('http'); const https = require('https'); const url = require('url'); const { google } = require('googleapis'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI. * To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true }); /* Global variable that stores user credential in this code example. * ACTION ITEM for developers: * Store user's refresh token in your data store if * incorporating this code into your real app. * For more information on handling refresh tokens, * see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens */ let userCredential = null; async function main() { const server = http.createServer(async function (req, res) { // Example on redirecting user to Google's OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google's OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // An error response e.g. error=access_denied console.log('Error:' + q.error); } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); /** Save credential to the global variable in case access token was refreshed. * ACTION ITEM: In a production app, you likely want to save the refresh token * in a secure persistent database instead. */ userCredential = tokens; // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } }); } } // Example on revoking a token if (req.url == '/revoke') { // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end(); } res.end(); }).listen(80); } main().catch(console.error);
HTTP/REST
W tym przykładzie języka Python wykorzystano platformę Flask i bibliotekę Requests, aby zademonstrować przepływ ruchu OAuth 2.0. Do tego celu zalecamy używanie biblioteki klienta interfejsu API Google dla języka Python. W przykładzie na karcie w Pythonie używana jest biblioteka klienta.
import json import flask import requests app = flask.Flask(__name__) CLIENT_ID = '123456789.apps.googleusercontent.com' CLIENT_SECRET = 'abc123' # Read from a file or environmental variable in a real app SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly' REDIRECT_URI = 'http://example.com/oauth2callback' @app.route('/') def index(): if 'credentials' not in flask.session: return flask.redirect(flask.url_for('oauth2callback')) credentials = json.loads(flask.session['credentials']) if credentials['expires_in'] <= 0: return flask.redirect(flask.url_for('oauth2callback')) else: headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])} req_uri = 'https://www.googleapis.com/drive/v2/files' r = requests.get(req_uri, headers=headers) return r.text @app.route('/oauth2callback') def oauth2callback(): if 'code' not in flask.request.args: auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code' '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE) return flask.redirect(auth_uri) else: auth_code = flask.request.args.get('code') data = {'code': auth_code, 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'redirect_uri': REDIRECT_URI, 'grant_type': 'authorization_code'} r = requests.post('https://oauth2.googleapis.com/token', data=data) flask.session['credentials'] = r.text return flask.redirect(flask.url_for('index')) if __name__ == '__main__': import uuid app.secret_key = str(uuid.uuid4()) app.debug = False app.run()
Reguły weryfikacji identyfikatora URI przekierowania
Google stosuje następujące reguły weryfikacji do identyfikatorów URI przekierowania, aby pomóc deweloperom chronić aplikacje. Twoje identyfikatory URI przekierowania muszą być zgodne z tymi regułami. Definicję domeny, hosta, ścieżki, zapytania, schematu i informacji o użytkowniku znajdziesz w RFC 3986, sekcja 3.
Reguły weryfikacji | |
---|---|
Schemat |
Identyfikatory URI przekierowania muszą korzystać ze schematu HTTPS, a nie zwykłego protokołu HTTP. Identyfikatory URI lokalnych hostów (w tym identyfikatory URI adresów IP hostów lokalnych) nie są objęte tą regułą. |
Osoba prowadząca |
Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP lokalnego hosta są wykluczone z tej reguły. |
Domena |
“googleusercontent.com” .goo.gl ), chyba że domena należy do aplikacji. Poza tym jeśli aplikacja, do której należy domena skrócona, zdecyduje się na przekierowanie do tej domeny, to identyfikator URI przekierowania musi zawierać w ścieżce użytkownika “/google-callback/” lub kończyć się ciągiem “/google-callback” . |
Informacje o użytkowniku |
Identyfikatory URI przekierowania nie mogą zawierać składnika useruser. |
Ścieżka |
Identyfikatory URI przekierowań nie mogą zawierać ścieżki przemierzania (nazywanej też przekierowaniem katalogu), która jest reprezentowana przez kod |
Zapytanie |
Identyfikatory URI przekierowania nie mogą zawierać otwartych przekierowań. |
Fragment |
Identyfikatory URI przekierowania nie mogą zawierać komponentu fragmentu. |
Znaki |
Identyfikatory URI przekierowania nie mogą zawierać niektórych znaków, w tym:
|
Autoryzacja przyrostowa
W protokole OAuth 2.0 Twoja aplikacja żąda autoryzacji dostępu do zasobów identyfikowanych przez zakresy. Ubieganie się o upoważnienie do korzystania z zasobów w momencie, gdy go potrzebujesz, jest uważane za najlepszą metodę pracy z wygodą użytkownika. Aby to umożliwić, serwer autoryzacji Google obsługuje autoryzację przyrostową. Ta funkcja umożliwia zgłaszanie żądań zakresów. W przypadku przyznania użytkownikowi uprawnień do nowego zakresu zwraca kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy, które użytkownik przyznał projektowi.
Na przykład aplikacja, która umożliwia próbkowanie utworów muzycznych i tworzenie składanek, może wymagać tylko kilku zasobów w chwili logowania – nic więcej niż nazwy osoby, która się loguje. Zapisanie gotowej składanki wymaga jednak dostępu do Dysku Google. Większość osób uznałaby to za naturalne, gdy pojawiła się prośba o dostęp do Dysku Google w momencie, gdy aplikacja ich potrzebowała.
W takim przypadku podczas logowania aplikacja może poprosić o zakresy podstawowe openid
i profile
, aby przeprowadzić podstawowe logowanie, a potem w trakcie pierwszego żądania przesłać żądanie zakresu https://www.googleapis.com/auth/drive.file
, aby zapisać zestaw.
Aby wdrożyć autoryzację przyrostową, wykonaj normalny przepływ żądania o token dostępu, ale upewnij się, że żądanie autoryzacji zawiera wcześniej przydzielone zakresy. Dzięki temu Twoja aplikacja uniknie konieczności zarządzania wieloma tokenami dostępu.
W przypadku tokena dostępu uzyskanego z przyrostowej autoryzacji obowiązują te reguły:
- Token może służyć do uzyskiwania dostępu do zasobów odpowiadających dowolnemu zakresowi wdrożonemu w nowej, połączonej autoryzacji.
- Gdy użyjesz tokena odświeżania połączonej autoryzacji, aby uzyskać token dostępu, token dostępu reprezentuje połączoną autoryzację i może być używany dla dowolnej wartości
scope
w odpowiedzi. - Łączna autoryzacja obejmuje wszystkie zakresy, które użytkownik przyznał projektowi interfejsu API, nawet jeśli otrzymał prośby od różnych klientów. Jeśli na przykład użytkownik udzielił dostępu do jednego zakresu za pomocą klienta na komputery, a następnie innego klienta do tej samej aplikacji za pomocą klienta mobilnego, łączna autoryzacja będzie obejmować oba zakresy.
- Jeśli unieważnisz token reprezentujący połączoną autoryzację, dostęp do wszystkich zakresów tej autoryzacji w imieniu powiązanego użytkownika zostanie unieważniony jednocześnie.
Przykładowy kod kodu w kroku 1: Ustaw parametry autoryzacji i przykładowy adres URL przekierowania HTTP/REST w kroku 2. Przekieruj na serwer OAuth 2.0 Google używają uwierzytelniania przyrostowego. Przykładowy kod poniżej pokazuje też kod, który musisz dodać, aby korzystać z uwierzytelniania przyrostowego.
PHP
$client->setIncludeGrantedScopes(true);
Python
W Pythonie ustaw argument słowa kluczowego include_granted_scopes
na true
, aby żądanie autoryzacji obejmowało wcześniej przyznane zakresy. Bardzo możliwe, że include_granted_scopes
nie będzie wyłącznym argumentem słowa kluczowego, jak pokazano w przykładzie poniżej.
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
Ruby
auth_client.update!( :additional_parameters => {"include_granted_scopes" => "true"} )
Node.js
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
HTTP/REST
GET https://accounts.google.com/o/oauth2/v2/auth? client_id=your_client_id& response_type=code& state=state_parameter_passthrough_value& scope=https%3A//www.googleapis.com/auth/drive.file& redirect_uri=https%3A//oauth2.example.com/code& prompt=consent& include_granted_scopes=true
Odświeżanie tokena dostępu (dostęp offline)
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).
- Jeśli używasz biblioteki klienta interfejsu API Google, obiekt kliencki odświeża token dostępu w miarę potrzeby, o ile skonfigurujesz dostęp do niego w trybie offline.
- Jeśli nie korzystasz z biblioteki klienta, ustaw parametr zapytania
access_type
HTTP naoffline
podczas przekierowania użytkownika na serwer OAuth 2.0 Google. W takim przypadku serwer autoryzacji Google zwraca token odświeżania, gdy wymieniasz kod autoryzacji tokena dostępu. Następnie, jeśli token dostępu wygaśnie (lub w dowolnym innym momencie), możesz użyć tokena odświeżania, aby uzyskać nowy token dostępu.
Prośba o dostęp offline jest wymagana w przypadku każdej aplikacji, która potrzebuje dostępu do interfejsu Google API, gdy nie ma użytkownika. Na przykład aplikacja, która wykonuje usługi kopii zapasowej lub wykonuje działania we wskazanym czasie, musi mieć możliwość odświeżania tokena dostępu, gdy użytkownika nie ma w domu. Domyślny styl dostępu to online
.
Aplikacje internetowe po stronie serwera, zainstalowane aplikacje i urządzenia uzyskują tokeny odświeżania podczas procesu autoryzacji. Tokeny odświeżania nie są zwykle używane w aplikacjach internetowych po stronie klienta (JavaScript).
PHP
Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu API Google, ustaw typ dostępu klienta interfejsu API na offline
:
$client->setAccessType("offline");
Gdy użytkownik przyzna dostęp offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeża token dostępu zgodnie z potrzebami.
Python
W Pythonie ustaw argument słowa kluczowego access_type
na offline
, aby umożliwić odświeżenie tokena dostępu bez konieczności pytania użytkownika o pozwolenie. Jest bardzo możliwe, że access_type
nie będzie wyłącznym argumentem słowa kluczowego, jak pokazano w przykładzie poniżej.
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
Gdy użytkownik przyzna dostęp offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeża token dostępu zgodnie z potrzebami.
Ruby
Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu API Google, ustaw typ dostępu klienta interfejsu API na offline
:
auth_client.update!( :additional_parameters => {"access_type" => "offline"} )
Gdy użytkownik przyzna dostęp offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeża token dostępu zgodnie z potrzebami.
Node.js
Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu API Google, ustaw typ dostępu klienta interfejsu API na offline
:
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
Gdy użytkownik przyzna dostęp offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeża token dostępu zgodnie z potrzebami.
Tokeny dostępu wygasają. Ta biblioteka automatycznie użyje tokena odświeżania w celu uzyskania nowego tokena dostępu, jeśli zbliża się data wygaśnięcia. Prostym sposobem na to, aby zawsze przechowywać najnowsze tokeny, jest użycie zdarzenia tokenów:
oauth2Client.on('tokens', (tokens) => { if (tokens.refresh_token) { // store the refresh_token in your secure persistent database console.log(tokens.refresh_token); } console.log(tokens.access_token); });
Zdarzenie dotyczące tokenów jest możliwe tylko w ramach pierwszej autoryzacji. Aby otrzymać token odświeżania, w access_type
musisz ustawić wartość offline
na wywołania metody generateAuthUrl
. Jeśli aplikacja ma już wymagane uprawnienia bez ograniczeń dotyczących odbierania tokena odświeżania, musisz ponownie autoryzować aplikację, aby otrzymać nowy token odświeżania.
Aby ustawić refresh_token
później, możesz użyć metody setCredentials
:
oauth2Client.setCredentials({ refresh_token: `STORED_REFRESH_TOKEN` });
Gdy klient uzyska token odświeżania, tokeny dostępu zostaną uzyskane i odświeżone automatycznie podczas następnego wywołania interfejsu API.
HTTP/REST
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. |
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.
PHP
Aby automatycznie unieważnić token, wywołaj metodę revokeToken()
:
$client->revokeToken();
Python
Aby automatycznie unieważnić token, wyślij do https://oauth2.googleapis.com/revoke
żądanie zawierające token jako parametr i ustaw nagłówek Content-Type
:
requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'})
Ruby
Aby automatycznie unieważnić token, wyślij żądanie HTTP do punktu końcowego oauth2.revoke
:
uri = URI('https://oauth2.googleapis.com/revoke') response = Net::HTTP.post_form(uri, 'token' => auth_client.access_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 odpowiedzi to 200
. W przypadku warunków błędu zwracany jest kod stanu 400
wraz z kodem błędu.
Node.js
Aby automatycznie unieważnić token, wyślij żądanie HTTPS POST do punktu końcowego /revoke
:
const https = require('https'); // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end();
Parametr tokena może być tokenem dostępu lub tokenem 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 odpowiedzi to 200
. W przypadku warunków błędu zwracany jest kod stanu 400
wraz z kodem błędu.
HTTP/REST
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.