Google jest zaangażowany w promowanie równości rasowej dla społeczności czarnych. Zobacz jak.

Korzystanie z protokołu OAuth 2.0 w aplikacjach serwera WWW

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:

  1. Open the API Library w Google API Console.
  2. If prompted, select a project, or create a new one.
  3. 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.
  4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz .
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania> Identyfikator klienta OAuth .
  3. Wybierz typ aplikacji internetowej .
  4. 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 przekierowania http://localhost:8080 adres http://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-oauthlib i google-auth-httplib2 do autoryzacji użytkownika.
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • Struktura aplikacji internetowych Flask Python.
    pip install --upgrade flask
  • requests biblioteki 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:

  1. Twoja aplikacja identyfikuje wymagane uprawnienia.
  2. Twoja aplikacja przekierowuje użytkownika do Google wraz z listą wymaganych uprawnień.
  3. Użytkownik decyduje, czy przyznać uprawnienia do aplikacji.
  4. Twoja aplikacja dowiaduje się, co zdecydował użytkownik.
  5. 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ę setAuthConfig aby załadować dane uwierzytelniające z pliku client_secret.json .

$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 client_id , zostanie wyświetlony błąd redirect_uri_mismatch .

Zwróć uwagę, że schemat http lub https , wielkość liter i końcowy ukośnik („ / ”) muszą być zgodne.

Aby ustawić tę wartość w PHP, wywołaj funkcję setRedirectUri . Zauważ, że musisz określić poprawny identyfikator URI przekierowania dla podanego client_id .

$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ę addScope :

$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 online , co jest wartością domyślną, oraz offline .

Ustaw wartość na offline jeśli aplikacja musi odświeżyć tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisana w dalszej części tego dokumentu. Ta wartość powoduje, że serwer autoryzacji Google zwraca token odświeżania i token dostępu, gdy aplikacja po raz pierwszy wymienia kod autoryzacji na tokeny.

Aby ustawić tę wartość w PHP, wywołaj funkcję setAccessType :

$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ę name=value w komponencie zapytania URL ( ? ) redirect_uri po tym, jak użytkownik wyrazi zgodę lub odmówi dostępu do aplikacji.

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 redirect_uri , użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót pliku cookie lub inną wartość, która przechwytuje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, zapewniając ochronę przed atakami, takimi jak między witrynami zażądać fałszerstwa. Zobacz dokumentację OpenID Connect, aby zapoznać się z przykładem tworzenia i potwierdzania tokenu state .

Aby ustawić tę wartość w PHP, wywołaj funkcję setState :

$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 true a żądanie autoryzacji zostanie udzielone, nowy token dostępu obejmie również wszystkie zakresy, do których użytkownik wcześniej udzielił dostępu do aplikacji. Przykłady można znaleźć w sekcji dotyczącej autoryzacji przyrostowej .

Aby ustawić tę wartość w PHP, wywołaj funkcję setIncludeGrantedScopes :

$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 sub , który jest odpowiednikiem identyfikatora Google użytkownika.

Aby ustawić tę wartość w PHP, wywołaj funkcję setLoginHint :

$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ę setApprovalPrompt :

$client->setApprovalPrompt('consent');

Możliwe wartości to:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można go określać z innymi wartościami.
consent Poproś użytkownika o zgodę.
select_account Poproś użytkownika o wybranie konta.

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ą from_client_secrets_file sposób pobrać identyfikator klienta z pliku client_secret.json. (Możesz również użyć metody from_client_config , która przekazuje konfigurację klienta w takiej postaci, w jakiej była pierwotnie zawarta w pliku kluczy klienta, ale nie ma dostępu do samego pliku).

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 client_id , zostanie wyświetlony błąd redirect_uri_mismatch .

Zwróć uwagę, że schemat http lub https , wielkość liter i końcowy ukośnik („ / ”) muszą być zgodne.

Aby ustawić tę wartość w Pythonie, ustaw właściwość redirect_uri obiektu flow :

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 client_id aby określić listę zakresów.

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 online , co jest wartością domyślną, oraz offline .

Ustaw wartość na offline jeśli aplikacja musi odświeżyć tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisana w dalszej części tego dokumentu. Ta wartość powoduje, że serwer autoryzacji Google zwraca token odświeżania i token dostępu, gdy aplikacja po raz pierwszy wymienia kod autoryzacji na tokeny.

W Pythonie ustawić access_type parametr podając access_type jako argumentu słowa kluczowego podczas wywoływania flow.authorization_url metodę:

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ę name=value w komponencie zapytania URL ( ? ) redirect_uri po tym, jak użytkownik wyrazi zgodę lub odmówi dostępu do aplikacji.

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 redirect_uri , użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót pliku cookie lub inną wartość, która przechwytuje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, zapewniając ochronę przed atakami, takimi jak między witrynami zażądać fałszerstwa. Zobacz dokumentację OpenID Connect, aby zapoznać się z przykładem tworzenia i potwierdzania tokenu state .

W Pythonie ustaw parametr state , określając state jako argument słowa kluczowego podczas wywoływania metody flow.authorization_url :

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 true a żądanie autoryzacji zostanie przyznane, nowy token dostępu obejmie również wszystkie zakresy, do których użytkownik wcześniej udzielił dostępu do aplikacji. Przykłady można znaleźć w sekcji dotyczącej autoryzacji przyrostowej .

W Pythonie ustaw parametr include_granted_scopes , określając include_granted_scopes jako argument słowa kluczowego podczas wywoływania metody flow.authorization_url :

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 sub , który jest odpowiednikiem identyfikatora Google użytkownika.

W Pythonie ustaw parametr login_hint , określając login_hint jako argument słowa kluczowego podczas wywoływania metody flow.authorization_url :

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 prompt , określając prompt jako argument słowa kluczowego podczas wywoływania metody flow.authorization_url :

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

Możliwe wartości to:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można go określać z innymi wartościami.
consent Poproś użytkownika o zgodę.
select_account Poproś użytkownika o wybranie konta.

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 client_id , zostanie wyświetlony błąd redirect_uri_mismatch .

Zwróć uwagę, że schemat http lub https , wielkość liter i końcowy ukośnik („ / ”) muszą być zgodne.

response_type wymagany

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

Ustaw wartość parametru na code dla aplikacji serwera WWW.

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 online , co jest wartością domyślną, oraz offline .

Ustaw wartość na offline jeśli aplikacja musi odświeżyć tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisana w dalszej części tego dokumentu. Ta wartość powoduje, że serwer autoryzacji Google zwraca token odświeżania i token dostępu, gdy aplikacja po raz pierwszy wymienia kod autoryzacji na tokeny.

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ę name=value w komponencie zapytania URL ( ? ) redirect_uri po tym, jak użytkownik wyrazi zgodę lub odmówi dostępu do aplikacji.

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 redirect_uri , użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelnienia. Jeśli wygenerujesz losowy ciąg lub zakodujesz skrót pliku cookie lub inną wartość, która przechwytuje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, zapewniając ochronę przed atakami, takimi jak między witrynami zażądać fałszerstwa. Zobacz dokumentację OpenID Connect, aby zapoznać się z przykładem tworzenia i potwierdzania tokenu state .

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 true a żądanie autoryzacji zostanie udzielone, nowy token dostępu obejmie również wszystkie zakresy, do których użytkownik wcześniej udzielił dostępu do aplikacji. Przykłady można znaleźć w sekcji dotyczącej autoryzacji przyrostowej .

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 sub , który jest odpowiednikiem identyfikatora Google użytkownika.

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:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można go określać z innymi wartościami.
consent Poproś użytkownika o zgodę.
select_account Poproś użytkownika o wybranie konta.

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

  1. Wygeneruj adres URL, aby zażądać dostępu z serwera Google OAuth 2.0:
    $auth_url = $client->createAuthUrl();
  2. 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

  1. Wygeneruj adres URL, aby zażądać dostępu z serwera Google OAuth 2.0:
    auth_uri = auth_client.authorization_uri.to_s
  2. 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:

  1. If you need to apply an access token to a new Google_Client object—for example, if you stored the access token in a user session—use the setAccessToken method:
    $client->setAccessToken($access_token);
  2. Build a service object for the API that you want to call. You build a service object by providing an authorized Google_Client object to the constructor for the API you want to call. For example, to call the Drive API:
    $drive = new Google_Service_Drive($client);
  3. 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.

  1. Build a service object for the API that you want to call. You build a service object by calling the googleapiclient.discovery library's build method 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)
  2. 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:

  1. 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
  2. Set the credentials on the service:
    drive.authorization = auth_client
  3. 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:

  1. In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add http://localhost:8080 .
  2. Create a new directory and change to it. For example:
    mkdir ~/php-oauth2-example
    cd ~/php-oauth2-example
  3. Install the Google API Client Library for PHP using Composer :
    composer require google/apiclient:^2.0
  4. Create the files index.php and oauth2callback.php with the content below.
  5. 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
end

HTTP/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
  • Host TLDs ( Top Level Domains ) must belong to the public suffix list .
  • Host domains cannot be “googleusercontent.com” .
  • URIs cannot contain URL shortener domains (eg 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 “/..” or “\..” or their URL encoding.

    Query

    Redirect URIs cannot contain open redirects .

    Characters URIs cannot contain certain characters including:
    • Wildcard characters ( '*' )
    • Non-printable ASCII characters
    • Invalid percent encodings (any percent encoding that does not follow URL-encoding form of a percent sign followed by two hexadecimal digits)
    • Null characters (an encoded NULL character, eg, %00 , %C0%80 )

    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 scope values 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_type HTTP query parameter to offline when 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.