W tym dokumencie wyjaśniono, w jaki sposób aplikacje serwera internetowego używają bibliotek klienckich interfejsu API Google lub punktów końcowych Google OAuth 2.0 do implementacji autoryzacji OAuth 2.0 w celu uzyskania dostępu do interfejsów API Google.
OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy zachowaniu prywatności ich nazw użytkowników, haseł i innych informacji. Na przykład aplikacja może używać protokołu OAuth 2.0 do uzyskiwania od użytkowników uprawnień do przechowywania plików na ich Dyskach Google.
Ten przepływ OAuth 2.0 jest przeznaczony specjalnie do autoryzacji użytkownika. Jest przeznaczony dla aplikacji, które mogą przechowywać poufne informacje i utrzymywać stan. Prawidłowo autoryzowana aplikacja serwera WWW może uzyskać dostęp do interfejsu API podczas interakcji użytkownika z aplikacją lub po opuszczeniu aplikacji przez użytkownika.
Aplikacje serwera sieci Web często również używają kont usług do autoryzacji żądań API, szczególnie podczas wywoływania Cloud API w celu uzyskania dostępu do danych opartych na projekcie, a nie do danych specyficznych dla użytkownika. Aplikacje serwera WWW mogą używać kont usług w połączeniu z autoryzacją użytkowników.
Biblioteki klienckie
Przykłady specyficzne dla języka na tej stronie wykorzystują biblioteki klienckie interfejsu API Google do implementacji autoryzacji OAuth 2.0. Aby uruchomić przykłady kodu, musisz najpierw zainstalować bibliotekę klienta dla swojego języka.
Gdy używasz biblioteki klienta interfejsu API Google do obsługi przepływu OAuth 2.0 aplikacji, biblioteka klienta wykonuje wiele czynności, które w innym przypadku musiałaby wykonać aplikacja. Na przykład określa, kiedy aplikacja może używać lub odświeżać przechowywane tokeny dostępu, a także kiedy aplikacja musi ponownie uzyskać zgodę. Biblioteka klienta generuje również poprawne adresy URL przekierowań i pomaga we wdrażaniu programów obsługi przekierowań, które wymieniają kody autoryzacji dla tokenów dostępu.
Biblioteki klienckie są dostępne dla następujących języków:
Wymagania wstępne
Włącz interfejsy API dla swojego projektu
Każda aplikacja, która wywołuje interfejsy API Google, musi je włączyć w API Console.
Aby włączyć interfejs API dla swojego projektu:
- Open the API Library w Google API Console.
- If prompted, select a project, or create a new one.
- API Library zawiera listę wszystkich dostępnych interfejsów API pogrupowanych według rodziny produktów i popularności. Jeśli API, które chcesz włączyć, nie jest widoczne na liście, użyj funkcji wyszukiwania, aby go znaleźć, lub kliknij opcję Wyświetl wszystko w rodzinie produktów, 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.
Utwórz dane uwierzytelniające
Każda aplikacja korzystająca z protokołu OAuth 2.0 w celu uzyskania dostępu do interfejsów API Google musi mieć dane uwierzytelniające identyfikujące aplikację na serwerze Google OAuth 2.0. Poniższe kroki wyjaśniają, jak utworzyć poświadczenia dla projektu. Twoje aplikacje mogą następnie używać poświadczeń do uzyskiwania dostępu do interfejsów API, które zostały włączone dla tego projektu.
- Go to the Credentials page.
- Kliknij Utwórz dane logowania> Identyfikator klienta OAuth .
- Wybierz typ aplikacji internetowej .
- Wypełnij formularz i kliknij Utwórz . Aplikacje korzystające z języków i struktur, takich jak PHP, Java, Python, Ruby i .NET, muszą określać 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 .
Na potrzeby testowania możesz określić identyfikatory URI, które odnoszą się do komputera lokalnego, na przykład
http://localhost:8080. Mając to na uwadze, we wszystkich przykładach w tym dokumencie jako adres URI przekierowaniahttp://localhost:8080adreshttp://localhost:8080.Zalecamy zaprojektowanie punktów końcowych uwierzytelniania aplikacji, tak aby aplikacja nie ujawniała kodów autoryzacji innym zasobom na stronie.
Po utworzeniu poświadczeń pobierz plik client_secret.json z API Console. Bezpiecznie przechowuj plik w lokalizacji, do której ma dostęp tylko Twoja aplikacja.
Zidentyfikuj zakresy dostępu
Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, jednocześnie umożliwiając użytkownikom kontrolowanie ilości 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.
Przed rozpoczęciem wdrażania autoryzacji OAuth 2.0 zalecamy określenie zakresów, do których aplikacja będzie potrzebować uprawnień dostępu.
Zalecamy również, aby aplikacja zażądała dostępu do zakresów autoryzacji poprzez przyrostowy proces autoryzacji , w którym aplikacja żąda dostępu do danych użytkownika w kontekście. Ta sprawdzona metoda pomaga użytkownikom łatwiej zrozumieć, dlaczego aplikacja potrzebuje dostępu, o który prosi.
Dokument OAuth 2.0 API Scopes zawiera pełną listę zakresów, których możesz użyć, aby uzyskać dostęp do interfejsów API Google.
Wymagania specyficzne dla języka
Aby uruchomić dowolny przykład kodu w tym dokumencie, będziesz potrzebować konta Google, dostępu do Internetu i przeglądarki internetowej. Jeśli korzystasz z jednej z bibliotek klienta API, zapoznaj się również z poniższymi wymaganiami dotyczącymi języka.
PHP
Aby uruchomić przykłady kodu PHP w tym dokumencie, będziesz potrzebować:
- PHP 5.4 lub nowszy z zainstalowanym interfejsem wiersza poleceń (CLI) i rozszerzeniem JSON.
- Narzędzie do zarządzania zależnościami Composer .
Biblioteka klienta interfejsów API Google dla języka PHP:
php composer.phar require google/apiclient:^2.0
Pyton
Aby uruchomić przykłady kodu Pythona w tym dokumencie, będziesz potrzebować:
- Python 2.6 lub nowszy
- 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-oauthlibigoogle-auth-httplib2do autoryzacji użytkownika.pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
- Struktura aplikacji internetowych Flask Python.
pip install --upgrade flask
-
requestsbiblioteki HTTP.pip install --upgrade requests
Rubin
Aby uruchomić przykłady kodu Ruby w tym dokumencie, będziesz potrzebować:
- Ruby 2.2.2 lub nowszy
Biblioteka klienta interfejsów API Google dla języka Ruby:
gem install google-api-client
Struktura aplikacji internetowych Sinatra Ruby.
gem install sinatra
HTTP / REST
Nie musisz instalować żadnych bibliotek, aby móc bezpośrednio wywoływać punkty końcowe OAuth 2.0.
Uzyskanie tokenów dostępu OAuth 2.0
Poniższe kroki pokazują, jak Twoja aplikacja współdziała z serwerem Google OAuth 2.0 w celu uzyskania zgody użytkownika na wykonanie żądania API w imieniu użytkownika. Twoja aplikacja musi mieć tę zgodę, zanim będzie mogła wykonać żądanie Google API wymagające autoryzacji użytkownika.
Poniższa lista szybko podsumowuje te kroki:
- Twoja aplikacja identyfikuje wymagane uprawnienia.
- Twoja aplikacja przekierowuje użytkownika do Google wraz z listą wymaganych uprawnień.
- Użytkownik decyduje, czy przyznać uprawnienia do aplikacji.
- Twoja aplikacja dowiaduje się, co zdecydował użytkownik.
- Jeśli użytkownik udzielił żądanych uprawnień, aplikacja pobiera tokeny potrzebne do wysyłania żądań interfejsu API w imieniu użytkownika.
Krok 1: Ustaw parametry autoryzacji
Pierwszym krokiem jest utworzenie wniosku o autoryzację. To żądanie ustawia parametry, które identyfikują twoją aplikację i definiują uprawnienia, o które użytkownik zostanie poproszony o nadanie twojej aplikacji.
- Jeśli używasz biblioteki klienta Google do uwierzytelniania i autoryzacji OAuth 2.0, tworzysz i konfigurujesz obiekt, który definiuje te parametry.
- Jeśli wywołasz punkt końcowy Google OAuth 2.0 bezpośrednio, wygenerujesz adres URL i ustawisz parametry tego adresu URL.
Poniższe zakładki określają obsługiwane parametry autoryzacji dla aplikacji serwera WWW. Przykłady specyficzne dla języka pokazują również, jak używać biblioteki klienta lub biblioteki autoryzacji do konfigurowania obiektu, który ustawia te parametry.
PHP
Poniższy fragment kodu tworzy obiekt Google_Client() , który definiuje parametry w żądaniu autoryzacji.
Ten obiekt używa informacji z pliku client_secret.json do identyfikacji aplikacji. (Więcej informacji na temat tego pliku można znaleźć w artykule Tworzenie danych uwierzytelniających ). Obiekt identyfikuje również zakresy, do których aplikacja żąda pozwolenia, oraz adres URL do punktu końcowego uwierzytelniania aplikacji, który będzie obsługiwał odpowiedź z serwera Google OAuth 2.0. Wreszcie, kod ustawia opcjonalne access_type i include_granted_scopes parametry.
Na przykład ten kod żąda dostępu w trybie tylko do odczytu do Dysku Google użytkownika w trybie offline:
$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 następujące informacje:
| Parametry | |||||||
|---|---|---|---|---|---|---|---|
client_id | wymagany Identyfikator klienta dla Twojej aplikacji. Możesz znaleźć tę wartość w API Console Credentials page. W PHP wywołaj funkcję
$client = new Google_Client();
$client->setAuthConfig('client_secret.json'); | ||||||
redirect_uri | wymagany Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu przez użytkownika przepływu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany w pliku API Console Credentials page klienta. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego Zwróć uwagę, że schemat Aby ustawić tę wartość w PHP, wywołaj funkcję
$client->setRedirectUri('https://oauth2.example.com/code'); | ||||||
scope | wymagany Rozdzielana spacjami lista zakresów identyfikująca zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują o ekranie akceptacji, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, jednocześnie umożliwiając użytkownikom kontrolowanie ilości dostępu, który przyznają aplikacji. W związku z tym istnieje 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 aplikacja żądała dostępu do zakresów autoryzacji w kontekście, gdy tylko jest to możliwe. Żądając dostępu do danych użytkownika w kontekście, poprzez autoryzację przyrostową , pomagasz użytkownikom łatwiej zrozumieć, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. | ||||||
access_type | Zalecana Wskazuje, czy aplikacja może odświeżyć tokeny dostępu, gdy użytkownika nie ma w przeglądarce. Prawidłowe wartości parametrów to Ustaw wartość na Aby ustawić tę wartość w PHP, wywołaj funkcję
$client->setAccessType('offline'); | ||||||
state | Zalecana Określa dowolną wartość ciągu używaną przez aplikację do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Serwer zwraca dokładną wartość, którą wysyłasz jako parę Tego parametru można używać do różnych celów, takich jak kierowanie użytkownika do odpowiedniego zasobu w aplikacji, wysyłanie wartości nonces i ograniczanie możliwości fałszowania żądań między lokacjami. Ponieważ można odgadnąć Twoje Aby ustawić tę wartość w PHP, wywołaj funkcję $client->setState($sample_passthrough_value); | ||||||
include_granted_scopes | Opcjonalny Umożliwia aplikacjom 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 Twoja aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby podać wskazówkę serwerowi Google Authentication Server. Serwer korzysta z podpowiedzi, aby uprościć proces logowania, wypełniając wstępnie 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 monitów o wyświetlenie użytkownikowi, oddzielonych spacjami, z rozróżnianiem wielkości liter. Jeśli nie określisz tego parametru, użytkownik zostanie zapytany tylko za pierwszym razem, gdy projekt zażąda dostępu. Aby uzyskać więcej informacji, zobacz Monitowanie o ponowną zgodę . Aby ustawić tę wartość w PHP, wywołaj funkcję
$client->setApprovalPrompt('consent');Możliwe wartości to:
| ||||||
Pyton
Poniższy fragment kodu używa modułu google-auth-oauthlib.flow do tworzenia żądania autoryzacji.
Kod tworzy obiekt Flow , który identyfikuje aplikację przy użyciu informacji z pliku client_secret.json pobranego po utworzeniu poświadczeń autoryzacji . Ten obiekt określa również zakresy, do których aplikacja żąda pozwolenia, oraz adres URL do punktu końcowego uwierzytelniania aplikacji, który będzie obsługiwał odpowiedź z serwera Google OAuth 2.0. Wreszcie, kod ustawia opcjonalne access_type i include_granted_scopes parametry.
Na przykład ten kod żąda dostępu w trybie tylko do odczytu do Dysku Google użytkownika w trybie offline:
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 następujące informacje:
| Parametry | |||||||
|---|---|---|---|---|---|---|---|
client_id | wymagany Identyfikator klienta dla Twojej aplikacji. Możesz znaleźć tę wartość w API Console Credentials page. W Pythonie nazywają
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
'client_secret.json',
scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) | ||||||
redirect_uri | wymagany Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu przez użytkownika przepływu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany w pliku API Console Credentials page klienta. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego Zwróć uwagę, że schemat Aby ustawić tę wartość w Pythonie, ustaw właściwość flow.redirect_uri = 'https://oauth2.example.com/code' | ||||||
scope | wymagany Lista zakresów identyfikujących zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują o ekranie akceptacji, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, jednocześnie umożliwiając użytkownikom kontrolowanie ilości dostępu, który przyznają aplikacji. W związku z tym istnieje 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 ustawienia
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
'client_secret.json',
scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])Zalecamy, aby aplikacja żądała dostępu do zakresów autoryzacji w kontekście, gdy tylko jest to możliwe. Żądając dostępu do danych użytkownika w kontekście, poprzez autoryzację przyrostową , pomagasz użytkownikom łatwiej zrozumieć, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. | ||||||
access_type | Zalecana Wskazuje, czy aplikacja może odświeżyć tokeny dostępu, gdy użytkownika nie ma w przeglądarce. Prawidłowe wartości parametrów to Ustaw wartość na W Pythonie ustawić
authorization_url, state = flow.authorization_url(
access_type='offline',
include_granted_scopes='true') | ||||||
state | Zalecana Określa dowolną wartość ciągu używaną przez aplikację do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Serwer zwraca dokładną wartość, którą wysyłasz jako parę Tego parametru można używać do różnych celów, takich jak kierowanie użytkownika do odpowiedniego zasobu w aplikacji, wysyłanie wartości nonces i ograniczanie możliwości fałszowania żądań między lokacjami. Ponieważ można odgadnąć Twoje 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 Umożliwia aplikacjom 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 Twoja aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby podać wskazówkę serwerowi Google Authentication Server. Serwer korzysta z podpowiedzi, aby uprościć proces logowania, wypełniając wstępnie 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 monitów o przedstawienie użytkownikowi, oddzielonych spacjami, z rozróżnianiem wielkości liter. Jeśli nie określisz tego parametru, użytkownik zostanie zapytany tylko za pierwszym razem, gdy projekt zażąda dostępu. Aby uzyskać więcej informacji, zobacz Monitowanie 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:
| ||||||
Rubin
Użyj utworzonego pliku client_secrets.json, aby skonfigurować obiekt klienta w aplikacji. Podczas konfigurowania obiektu klienta określasz zakresy, do których aplikacja musi uzyskać dostęp, wraz z adresem URL do punktu końcowego uwierzytelniania aplikacji, który będzie obsługiwał odpowiedź z serwera OAuth 2.0.
Na przykład ten kod żąda dostępu w trybie tylko do odczytu do Dysku Google użytkownika w trybie offline:
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.
HTTP / REST
Punkt końcowy Google OAuth 2.0 znajduje się pod 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 | wymagany Identyfikator klienta dla Twojej aplikacji. Możesz znaleźć tę wartość w API Console Credentials page. | ||||||
redirect_uri | wymagany Określa, gdzie serwer API przekierowuje użytkownika po zakończeniu przez użytkownika przepływu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0, który został skonfigurowany w pliku API Console Credentials page klienta. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego Zwróć uwagę, że schemat | ||||||
response_type | wymagany Określa, czy punkt końcowy Google OAuth 2.0 zwraca kod autoryzacji. Ustaw wartość parametru na | ||||||
scope | wymagany Rozdzielana spacjami lista zakresów identyfikująca zasoby, do których aplikacja może uzyskać dostęp w imieniu użytkownika. Te wartości informują o ekranie akceptacji, który Google wyświetla użytkownikowi. Zakresy umożliwiają aplikacji żądanie dostępu tylko do zasobów, których potrzebuje, jednocześnie umożliwiając użytkownikom kontrolowanie ilości dostępu, który przyznają aplikacji. W związku z tym istnieje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika. Zalecamy, aby aplikacja żądała dostępu do zakresów autoryzacji w kontekście, gdy tylko jest to możliwe. Żądając dostępu do danych użytkownika w kontekście, poprzez autoryzację przyrostową , pomagasz użytkownikom łatwiej zrozumieć, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi. | ||||||
access_type | Zalecana Wskazuje, czy aplikacja może odświeżyć tokeny dostępu, gdy użytkownika nie ma w przeglądarce. Prawidłowe wartości parametrów to Ustaw wartość na | ||||||
state | Zalecana Określa dowolną wartość ciągu używaną przez aplikację do utrzymywania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Serwer zwraca dokładną wartość, którą wysyłasz jako parę Tego parametru można używać do różnych celów, takich jak kierowanie użytkownika do odpowiedniego zasobu w aplikacji, wysyłanie wartości nonces i ograniczanie możliwości fałszowania żądań między lokacjami. Ponieważ można odgadnąć Twoje | ||||||
include_granted_scopes | Opcjonalny Umożliwia aplikacjom 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 Twoja aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru, aby podać wskazówkę serwerowi Google Authentication Server. Serwer korzysta z podpowiedzi, aby uprościć proces logowania, wypełniając wstępnie 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 monitów o przedstawienie użytkownikowi, oddzielonych spacjami, z rozróżnianiem wielkości liter. Jeśli nie określisz tego parametru, użytkownik zostanie zapytany tylko za pierwszym razem, gdy projekt zażąda dostępu. Aby uzyskać więcej informacji, zobacz Monitowanie o ponowną zgodę . Możliwe wartości to:
| ||||||
Krok 2: Przekieruj na serwer Google OAuth 2.0
Przekieruj użytkownika na serwer Google OAuth 2.0, aby zainicjować proces uwierzytelniania i autoryzacji. Zwykle dzieje się tak, gdy aplikacja najpierw musi uzyskać dostęp do danych użytkownika. W przypadku autoryzacji przyrostowej ten krok występuje również wtedy, gdy aplikacja najpierw potrzebuje dostępu do dodatkowych zasobów, do których nie ma jeszcze uprawnień dostępu.
PHP
- Wygeneruj adres URL, aby zażądać dostępu z serwera Google OAuth 2.0:
$auth_url = $client->createAuthUrl();
- Przekieruj użytkownika do
$auth_url:header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
Pyton
Ten przykład pokazuje, jak przekierować użytkownika do adresu URL autoryzacji przy użyciu struktury aplikacji internetowej Flask:
return flask.redirect(authorization_url)
Rubin
- Wygeneruj adres URL, aby zażądać dostępu z serwera Google OAuth 2.0:
auth_uri = auth_client.authorization_uri.to_s
- Przekieruj użytkownika do
auth_uri.
HTTP / REST
Przykładowe przekierowanie na serwer autoryzacyjny Google
Przykładowy adres URL jest pokazany poniżej, z podziałami wierszy i spacjami w celu zwiększenia czytelności.
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 niego.
Serwer Google OAuth 2.0 uwierzytelnia użytkownika i uzyskuje zgodę użytkownika na dostęp aplikacji do żądanych zakresów. Odpowiedź jest odsyłana do aplikacji przy użyciu podanego adresu URL przekierowania.
Krok 3: Google prosi użytkownika o zgodę
Na tym etapie użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody, które pokazuje nazwę Twojej aplikacji i usług Google API, do których prosi o pozwolenie, wraz z danymi uwierzytelniającymi użytkownika i podsumowaniem zakresów dostępu, które mają zostać przyznane. Użytkownik może następnie wyrazić zgodę na udzielenie dostępu do jednego lub większej liczby zakresów wymaganych w aplikacji lub odrzucić żądanie.
Twoja aplikacja nie musi nic robić na tym etapie, ponieważ czeka na odpowiedź z serwera Google OAuth 2.0 wskazującą, czy przyznano jakikolwiek dostęp. Ta odpowiedź jest wyjaśniona w następnym kroku.
Krok 4: obsłuż odpowiedź serwera OAuth 2.0
Serwer OAuth 2.0 odpowiada na żądanie dostępu do aplikacji, używając adresu URL określonego w żądaniu.
Jeśli użytkownik zatwierdzi żądanie dostępu, odpowiedź zawiera kod autoryzacji. Jeśli użytkownik nie zatwierdzi żądania, odpowiedź zawiera komunikat o błędzie. Kod autoryzacji lub komunikat o błędzie zwracany do serwera WWW pojawia się w ciągu zapytania, jak pokazano poniżej:
Odpowiedź błędu:
https://oauth2.example.com/auth?error=access_denied
Odpowiedź na kod autoryzacyjny:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
Przykładowa odpowiedź serwera OAuth 2.0
Możesz przetestować ten przepływ, klikając następujący przykładowy adres URL, który żąda dostępu tylko do odczytu w celu wyświetlenia 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 przepływu OAuth 2.0 powinieneś zostać przekierowany do http://localhost/oauth2callback , co prawdopodobnie spowoduje błąd 404 NOT FOUND chyba że Twoja lokalna maszyna obsługuje plik pod tym adresem. Następny krok zawiera więcej szczegółów na temat informacji zwracanych w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do aplikacji.
Krok 5: Wymień kod autoryzacyjny na tokeny odświeżania i dostępu
Po otrzymaniu kodu autoryzacyjnego serwer WWW może zamienić go na token dostępu.
PHP
Aby wymienić kod autoryzacyjny na token dostępu, użyj metody authenticate :
$client->authenticate($_GET['code']);
Możesz pobrać token dostępu za pomocą metody getAccessToken :
$access_token = $client->getAccessToken();
Pyton
Na stronie wywołania zwrotnego użyj biblioteki google-auth aby zweryfikować odpowiedź serwera autoryzacji. Następnie użyj metody flow.fetch_token , aby wymienić kod autoryzacyjny 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}Rubin
Aby wymienić kod autoryzacyjny na token dostępu, użyj fetch_access_token! metoda:
auth_client.code = auth_code auth_client.fetch_access_token!
HTTP / REST
Aby wymienić kod autoryzacyjny na token dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw następujące parametry:
| Pola | |
|---|---|
client_id | Identyfikator klienta uzyskany z API Console Credentials page. |
client_secret | Sekret klienta uzyskany z API Console Credentials page. |
code | Kod autoryzacji zwrócony z pierwotnego żą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 dla Twojego projektu w API Console Credentials page dla podanego client_id . |
Poniższy fragment kodu przedstawia 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
Google odpowiada na to żądanie, zwracając obiekt JSON, który zawiera krótkotrwały token dostępu i token odświeżania. Pamiętaj, że token odświeżania jest zwracany tylko wtedy, gdy aplikacja ustawiła parametr access_type na offline w początkowym żądaniu do serwera autoryzacji Google .
Odpowiedź zawiera następujące pola:
| Pola | |
|---|---|
access_token | Token wysyłany przez Twoją aplikację w celu autoryzacji żądania Google API. |
expires_in | Pozostały okres istnienia tokenu dostępu w sekundach. |
refresh_token | Token, za pomocą którego możesz uzyskać nowy token dostępu. Tokeny odświeżania są ważne, dopóki użytkownik nie cofnie dostępu. Ponownie, to pole jest obecne w tej odpowiedzi tylko wtedy, gdy ustawisz parametr access_type na offline w początkowym żądaniu do serwera autoryzacji Google. |
scope | Zakresy dostępu przyznane przez access_token wyrażone jako lista ciągów rozdzielanych spacjami, z rozróżnianiem wielkości liter. |
token_type | Typ zwróconego tokena. W tej chwili wartość tego pola jest zawsze ustawiona na Bearer . |
The following snippet shows a sample response:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Calling Google APIs
PHP
Use the access token to call Google APIs by completing the following steps:
- If you need to apply an access token to a new
Google_Clientobject—for example, if you stored the access token in a user session—use thesetAccessTokenmethod:$client->setAccessToken($access_token);
- Build a service object for the API that you want to call. You build a service object by providing an authorized
Google_Clientobject to the constructor for the API you want to call. For example, to call the Drive API:$drive = new Google_Service_Drive($client);
- Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:
$files = $drive->files->listFiles(array())->getItems();
Pyton
After obtaining an access token, your application can use that token to authorize API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.
- Build a service object for the API that you want to call. You build a service object by calling the
googleapiclient.discoverylibrary'sbuildmethod with the name and version of the API and the user credentials: For example, to call version 2 of the Drive API:from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials) - Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:
files = drive.files().list().execute()
Ruby
Use the auth_client object to call Google APIs by completing the following steps:
- Build a service object for the API that you want to call. For example, to call version 2 of the Drive API:
drive = Google::Apis::DriveV2::DriveService.new
- Set the credentials on the service:
drive.authorization = auth_client
- Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:
files = drive.list_files
Alternately, authorization can be provided on a per-method basis by supplying the options parameter to a method:
files = drive.list_files(options: { authorization: auth_client })HTTP/REST
After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user account if the scope(s) of access required by the API have been granted. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the Drive Files API ).
You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground .
HTTP GET examples
A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Here is a call to the same API for the authenticated user using the access_token query string parameter:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl examples
You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Or, alternatively, the query string parameter option:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Complete example
The following example prints a JSON-formatted list of files in a user's Google Drive after the user authenticates and gives consent for the application to access the user's Drive metadata.
PHP
To run this example:
- In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add
http://localhost:8080. - Create a new directory and change to it. For example:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- Install the Google API Client Library for PHP using Composer :
composer require google/apiclient:^2.0
- Create the files
index.phpandoauth2callback.phpwith the content below. - Run the example with a web server configured to serve PHP. If you use PHP 5.4 or newer, you can use PHP's built-in test web server:
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));
}Pyton
This example uses the Flask framework. It runs a web application at http://localhost:8080 that lets you test the OAuth 2.0 flow. If you go to that URL, you should see four links:
- Test an API request: This link points to a page that tries to execute a sample API request. If necessary, it starts the authorization flow. If successful, the page displays the API response.
- Test the auth flow directly: This link points to a page that tries to send the user through the authorization flow . The app requests permission to submit authorized API requests on the user's behalf.
- Revoke current credentials: This link points to a page that revokes permissions that the user has already granted to the application.
- Clear Flask session credentials: This link clears authorization credentials that are stored in the Flask session. This lets you see what would happen if a user who had already granted permission to your app tried to execute an API request in a new session. It also lets you see the API response your app would get if a user had revoked permissions granted to your app, and your app still tried to authorize a request with a revoked access token.
# -*- 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
This example uses the Sinatra framework.
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
endHTTP/REST
This Python example uses the Flask framework and the Requests library to demonstrate the OAuth 2.0 web flow. We recommend using the Google API Client Library for Python for this flow. (The example in the Python tab does use the client library.)
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()Redirect URI validation rules
Google applies the following validation rules to redirect URIs in order to help developers keep their applications secure. Your redirect URIs must adhere to these rules. See RFC 3986 section 3 for the definition of domain, host, path, query, scheme and userinfo, mentioned below.
| Validation rules | |
|---|---|
| Scheme | URIs must use the HTTPS scheme, not plain HTTP. |
| Host | Hosts cannot be raw IP addresses. Localhost IP addresses are exempted from this rule. |
| Domain | “googleusercontent.com” .goo.gl ) unless the app owns the domain. Furthermore, if an app that owns a shortener domain chooses to redirect to that domain, that redirect URI must either contain “/google-callback/” in its path or end with “/google-callback” . |
| Userinfo | Redirect URIs cannot contain the userinfo subcomponent. |
| Path | Redirect URIs cannot contain a path traversal (also called directory backtracking), which is represented by an |
| Query | Redirect URIs cannot contain open redirects . |
| Characters | URIs cannot contain certain characters including:
|
Incremental authorization
In the OAuth 2.0 protocol, your app requests authorization to access resources, which are identified by scopes. It is considered a best user-experience practice to request authorization for resources at the time you need them. To enable that practice, Google's authorization server supports incremental authorization. This feature lets you request scopes as they are needed and, if the user grants permission for the new scope, returns an authorization code that may be exchanged for a token containing all scopes the user has granted the project.
For example, an app that lets people sample music tracks and create mixes might need very few resources at sign-in time, perhaps nothing more than the name of the person signing in. However, saving a completed mix would require access to their Google Drive. Most people would find it natural if they only were asked for access to their Google Drive at the time the app actually needed it.
In this case, at sign-in time the app might request the openid and profile scopes to perform basic sign-in, and then later request the https://www.googleapis.com/auth/drive.file scope at the time of the first request to save a mix.
To implement incremental authorization, you complete the normal flow for requesting an access token but make sure that the authorization request includes previously granted scopes. This approach allows your app to avoid having to manage multiple access tokens.
The following rules apply to an access token obtained from an incremental authorization:
- The token can be used to access resources corresponding to any of the scopes rolled into the new, combined authorization.
- When you use the refresh token for the combined authorization to obtain an access token, the access token represents the combined authorization and can be used for any of the
scopevalues included in the response. - The combined authorization includes all scopes that the user granted to the API project even if the grants were requested from different clients. For example, if a user granted access to one scope using an application's desktop client and then granted another scope to the same application via a mobile client, the combined authorization would include both scopes.
- If you revoke a token that represents a combined authorization, access to all of that authorization's scopes on behalf of the associated user are revoked simultaneously.
The language-specific code samples in Step 1: Set authorization parameters and the sample HTTP/REST redirect URL in Step 2: Redirect to Google's OAuth 2.0 server all use incremental authorization. The code samples below also show the code that you need to add to use incremental authorization.
PHP
$client->setIncludeGrantedScopes(true);
Pyton
In Python, set the include_granted_scopes keyword argument to true to ensure that an authorization request includes previously granted scopes. It is very possible that include_granted_scopes will not be the only keyword argument that you set, as shown in the example below.
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"}
)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
Refreshing an access token (offline access)
Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.
- If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
- If you are not using a client library, you need to set the
access_typeHTTP query parameter toofflinewhen redirecting the user to Google's OAuth 2.0 server . In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.
Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online .
Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.
PHP
If your application needs offline access to a Google API, set the API client's access type to offline :
$client->setAccessType("offline");After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.
Pyton
In Python, set the access_type keyword argument to offline to ensure that you will be able to refresh the access token without having to re-prompt the user for permission. It is very possible that access_type will not be the only keyword argument that you set, as shown in the example below.
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')After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.
Ruby
If your application needs offline access to a Google API, set the API client's access type to offline :
auth_client.update!(
:additional_parameters => {"access_type" => "offline"}
)After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.
HTTP/REST
To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters:
| Pola | |
|---|---|
client_id | The client ID obtained from the API Console. |
client_secret | The client secret obtained from the API Console. |
grant_type | As defined in the OAuth 2.0 specification , this field's value must be set to refresh_token . |
refresh_token | The refresh token returned from the authorization code exchange. |
The following snippet shows a sample request:
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
As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
"token_type": "Bearer"
}Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.
Revoking a token
In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.
It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.
PHP
To programmatically revoke a token, call revokeToken() :
$client->revokeToken();
Pyton
To programmatically revoke a token, make a request to https://oauth2.googleapis.com/revoke that includes the token as a parameter and sets the Content-Type header:
requests.post('https://oauth2.googleapis.com/revoke',
params={'token': credentials.token},
headers = {'content-type': 'application/x-www-form-urlencoded'})Ruby
To programmatically revoke a token, make an HTTP request to the oauth2.revoke endpoint:
uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)
The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.
If the revocation is successfully processed, then the status code of the response is 200 . For error conditions, a status code 400 is returned along with an error code.
HTTP/REST
To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.
If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.