Używanie protokołu OAuth 2.0 na potrzeby aplikacji serwera WWW

Ten dokument wyjaśnia, w jaki sposób aplikacje internetowe korzystają z bibliotek klienta interfejsu API Google lub punktów końcowych Google OAuth 2.0 do wdrażania autoryzacji OAuth 2.0 do korzystania z interfejsów API Google.

Protokół OAuth 2.0 umożliwia użytkownikom udostępnianie określonych danych aplikacji przy zachowaniu ich nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład używać protokołu OAuth 2.0, aby uzyskiwać od użytkowników uprawnienia do przechowywania plików na ich Dyskach Google.

Przepływ OAuth 2.0 jest przeznaczony specjalnie do uwierzytelniania użytkowników. Jest ona przeznaczona dla aplikacji, które mogą przechowywać informacje poufne i utrzymywać stan. Prawidłowo autoryzowana aplikacja serwera WWW może uzyskać dostęp do interfejsu API, gdy użytkownik korzysta z aplikacji lub po jej opuszczeniu.

Aplikacje serwera WWW często korzystają też z kont usługi do autoryzowania żądań API, zwłaszcza wtedy, gdy wywołują interfejsy API Cloud, by uzyskać dostęp do danych związanych z projektem, a nie danych konkretnego użytkownika. Aplikacje serwera WWW mogą używać kont usługi w połączeniu z uwierzytelnianiem użytkownika.

Biblioteki klienta

W przykładach językowych na tej stronie zaimplementowano autoryzację OAuth 2.0 za pomocą bibliotek klienta interfejsu API Google. Aby uruchomić próbki kodu, musisz najpierw zainstalować bibliotekę klienta dla swojego języka.

Gdy korzystasz z przepływu OAuth 2.0 z biblioteki klienta interfejsu API Google API, biblioteka klienta obsługuje wiele działań, które w innym przypadku musiałyby działać samodzielnie. Na przykład określa, kiedy aplikacja może używać lub odświeżać zapisane tokeny dostępu, a także kiedy aplikacja musi ponownie uzyskać zgodę. Biblioteka klienta generuje też prawidłowe przekierowania i pomaga zaimplementować moduły obsługi przekierowań, które wymieniają kody autoryzacji na tokeny dostępu.

Biblioteki klienta Google API dla aplikacji po stronie serwera są dostępne w tych językach:

Wymagania wstępne

Włącz interfejsy API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć je w API Console.

Aby włączyć interfejs API w projekcie:

  1. Open the API Library w: Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Na liście API Library znajdują się wszystkie dostępne interfejsy API pogrupowane według rodziny usług i popularności. Jeśli interfejs API, który chcesz włączyć, nie jest widoczny na liście, użyj funkcji wyszukiwania, aby go znaleźć, lub kliknij Wyświetl wszystko w rodzinie usług, do której należy.
  4. Wybierz interfejs API, który chcesz włączyć, a następnie kliknij przycisk Włącz.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Tworzenie danych uwierzytelniających

Każda aplikacja, która uzyskuje dostęp do interfejsów API Google przy użyciu OAuth 2.0, musi mieć dane uwierzytelniające, które identyfikują aplikację z serwerem OAuth 2.0 Google. Poniżej wyjaśniamy, jak utworzyć dane logowania do projektu. Dzięki temu aplikacje będą mogły korzystać z danych logowania, aby uzyskać dostęp do interfejsów API włączonych w tym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania > identyfikator klienta OAuth.
  3. Wybierz typ aplikacji Aplikacja internetowa.
  4. Wypełnij formularz i kliknij Utwórz. Aplikacje korzystające z języków i platform, takich jak PHP, Java, Python, Ruby i .NET, muszą określić autoryzowane identyfikatory URI przekierowania. Identyfikatory URI przekierowań to punkty końcowe, do których serwer OAuth 2.0 może wysyłać odpowiedzi. Te punkty końcowe muszą być zgodne z regułami weryfikacji Google.

    Podczas testów możesz określić identyfikatory URI odwołujące się do komputera lokalnego, np. http://localhost:8080. Pamiętaj, że we wszystkich przykładach w tym dokumencie jako identyfikator URI przekierowania stosowany jest atrybut http://localhost:8080.

    Zalecamy zaprojektowanie punktów końcowych uwierzytelniania aplikacji w taki sposób, aby aplikacja nie ujawniała kodów autoryzacji innym zasobom na stronie.

Po utworzeniu danych logowania pobierz plik client_secret.json z API Console. Bezpiecznie zapisuj plik w lokalizacji, do której ma dostęp tylko Twoja aplikacja.

Określ zakresy dostępu

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego może występować zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

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

Zalecamy też, aby aplikacja prosiła o dostęp do zakresów autoryzacji w ramach procesu przyrostowej autoryzacji, w której aplikacja prosi o dostęp do danych użytkownika w kontekście. Dzięki temu użytkownicy mogą łatwiej zrozumieć, dlaczego aplikacja potrzebuje dostępu.

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

Wymagania dla poszczególnych języków

Aby uruchomić dowolny przykładowy kod z tego dokumentu, musisz mieć konto Google, dostęp do internetu i przeglądarkę. Jeśli używasz jednej z bibliotek klienta interfejsu API, zapoznaj się z wymaganiami w danym języku poniżej.

PHP

Aby uruchomić próbki kodu PHP w tym dokumencie, musisz mieć:

  • PHP 5.4 lub nowszy z zainstalowanym interfejsem wiersza poleceń i rozszerzeniem JSON.
  • Narzędzie do zarządzania zależnościami Composer.

  • Biblioteka klienta interfejsów API Google dla PHP:

    php composer.phar require google/apiclient:^2.0

Python

Aby uruchomić próbki kodu w języku Python w tym dokumencie, potrzebujesz:

  • Python 2.6 lub nowszy
  • Narzędzie do zarządzania pakietami pip.
  • Biblioteka klienta interfejsów API Google dla Pythona: 
    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
  • Platforma aplikacji internetowej Flask Python. 
    pip install --upgrade flask
  • Biblioteka HTTP requests. 
    pip install --upgrade requests

Ruby

Aby uruchomić próbki kodu Ruby w tym dokumencie, potrzebujesz:

  • Ruby 2.2.2 lub nowsza wersja

  • Biblioteka klienta interfejsów API Google dla języka Ruby:

    gem install google-api-client

  • Platforma aplikacji internetowych Sinatra Ruby.

    gem install sinatra

Node.js

Aby uruchomić próbki kodu Node.js w tym dokumencie, musisz mieć:

  • LTS aktywnej, LTS lub bieżącej wersji Node.js.

  • Klient Node.js interfejsu API Google:

    npm install googleapis

HTTP/REST

Nie musisz instalować żadnych bibliotek, aby bezpośrednio wywoływać punkty końcowe OAuth 2.0.

Uzyskiwanie tokenów dostępu do protokołu OAuth 2.0

Poniższe kroki przedstawiają sposób interakcji Twojej aplikacji z serwerem OAuth 2.0 Google w celu uzyskania zgody od użytkownika na wysłanie żądania interfejsu API w jego imieniu. Aplikacja musi uzyskać tę zgodę, zanim będzie mogła wysłać żądanie interfejsu API Google, które wymaga autoryzacji użytkownika.

Poniższa lista zawiera podsumowanie tych czynności:

  1. Aplikacja identyfikuje wymagane uprawnienia.
  2. Aplikacja przekierowuje użytkownika do Google wraz z listą wymaganych uprawnień.
  3. To użytkownik decyduje, czy przyznać uprawnienia aplikacji.
  4. Aplikacja podejmie decyzję o decyzji użytkownika.
  5. Jeśli użytkownik przyznał odpowiednie uprawnienia, aplikacja pobiera tokeny niezbędne do wykonywania żądań do interfejsu API w imieniu użytkownika.

Krok 1. Ustaw parametry autoryzacji

Pierwszym krokiem jest utworzenie żądania autoryzacji. To żądanie ustawia parametry identyfikujące aplikację i określa uprawnienia, jakie użytkownik będzie musiał przyznać aplikacji.

  • Jeśli używasz biblioteki klienta Google do uwierzytelniania i autoryzacji OAuth 2.0, musisz utworzyć i skonfigurować obiekt definiujący te parametry.
  • Jeśli bezpośrednio wywołasz punkt końcowy Google OAuth 2.0, wygenerujesz adres URL i ustawisz parametry w tym adresie URL.

Na poniższych kartach określono obsługiwane parametry autoryzacji aplikacji serwera WWW. Przykłady dotyczące języków pokazują też, jak za pomocą biblioteki klienta lub biblioteki autoryzacji skonfigurować obiekt ustawiający te parametry.

PHP

Poniższy fragment kodu tworzy obiekt Google_Client(), który określa parametry w żądaniu autoryzacji.

Ten obiekt identyfikuje aplikację na podstawie informacji z pliku client_secret.json. Więcej informacji o tym pliku znajdziesz w artykule Tworzenie danych uwierzytelniających. Obiekt określa też zakresy, do których aplikacja prosi o dostęp, oraz adres URL punktu końcowego uwierzytelniania Twojej aplikacji, który będzie przetwarzać odpowiedź z serwera OAuth 2.0 Google. Na koniec kod ustawia opcjonalne parametry access_type i include_granted_scopes.

Na przykład ten kod żąda dostępu do Dysku Google użytkownika tylko do odczytu bez połączenia z internetem: 

$client = new Google_Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google_Service_Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt("consent");
$client->setIncludeGrantedScopes(true);   // incremental auth

Żądanie zawiera te informacje:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.

W języku PHP wywołaj funkcję setAuthConfig, aby wczytać dane uwierzytelniające z pliku client_secret.json.

$client = new Google_Client();
$client->setAuthConfig('client_secret.json');
redirect_uri Wymagany

Określa, gdzie serwer interfejsu API przekierowuje użytkownika po ukończeniu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials pageklienta. Jeśli ta wartość nie będzie zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego kodu client_id, wystąpi błąd redirect_uri_mismatch.

Schemat http, https i ukośnik na końcu ('/') muszą się zgadzać.

Aby ustawić tę wartość w języku PHP, wywołaj funkcję setRedirectUri. Pamiętaj, że musisz podać prawidłowy identyfikator URI przekierowania dla podanego client_id.

$client->setRedirectUri('https://oauth2.example.com/code');
scope Wymagany

Lista rozdzielonych spacjami, które identyfikują zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Aby ustawić tę wartość w języku PHP, wywołaj funkcję addScope:

$client->addScope(Google_Service_Drive::DRIVE_METADATA_READONLY);

Zalecamy, aby w miarę możliwości aplikacja żądała dostępu do zakresów autoryzacji. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego aplikacja potrzebuje dostępu, o który prosi.
access_type Zalecane

Wskazuje, czy aplikacja może odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Prawidłowe wartości to online, czyli wartość domyślna, oraz offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. To jest metoda odświeżania tokenów dostępu opisanych w dalszej części tego dokumentu. Ta wartość instruuje serwer autoryzacji Google, że ma zwrócić token odświeżania oraz token dostępu po pierwszym uruchomieniu kodu autoryzacji dla tokenów.

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

$client->setAccessType('offline');
state Zalecane

Określa dowolną wartość ciągu tekstowego, której aplikacja używa do obsługi stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na żądanie dostępu lub odmówi jego dostępu, serwer zwróci dokładną wartość, którą wyślesz jako parę name=value w komponencie zapytania URL (?) redirect_uri.

Możesz używać tego parametru do różnych celów, takich jak kierowanie użytkownika do właściwego zasobu w aplikacji, wysyłanie jednorazowych żądań czy fałszowanie żądań pochodzących z różnych witryn. Ponieważ można zgadnąć redirect_uri, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli wygenerujesz losowy ciąg znaków lub zaszyfrujesz hasz plików cookie bądź inną wartość, która będzie przechwytywać stan klienta, możesz sprawdzić odpowiedź, aby zyskać pewność, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, co zapewnia ochronę przed atakami takimi jak fałszowanie żądań w różnych witrynach. Przykład tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.

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

$client->setState($sample_passthrough_value);
include_granted_scopes Opcjonalnie

Umożliwia aplikacjom używanie autoryzacji przyrostowej do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na true i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp aplikacji. Przykłady znajdziesz w sekcji Autoryzacja przyrostowa.

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

$client->setIncludeGrantedScopes(true);
login_hint Opcjonalnie

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru do przekazania wskazówki do serwera uwierzytelniania Google. Serwer korzysta z podpowiedzi, aby uprościć przepływ logowania, wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

Ustaw wartość parametru na adres e-mail lub identyfikator sub, który jest odpowiednikiem identyfikatora Google użytkownika.

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

$client->setLoginHint('None');
prompt Opcjonalnie

Lista rozdzielonych spacjami wielkości liter z pytaniami, które przedstawiają użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy pierwszy raz poprosi on o dostęp do Twojego projektu. Więcej informacji znajdziesz w artykule Ponowne wyświetlanie prośby o zgodę na wykorzystanie danych.

Aby ustawić tę wartość w języku PHP, wywołaj funkcję setApprovalPrompt:

$client->setApprovalPrompt('consent');

Możliwe wartości to:

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

Python

Ten fragment kodu wykorzystuje moduł google-auth-oauthlib.flow do tworzenia żądania autoryzacji.

Kod tworzy obiekt Flow, który identyfikuje aplikację na podstawie informacji z pliku client_secret.json pobranego po utworzeniu danych uwierzytelniających. Ten obiekt identyfikuje również zakresy, do których aplikacja prosi o dostęp, oraz URL do punktu końcowego uwierzytelniania aplikacji, który będzie przetwarzać odpowiedź z serwera OAuth 2.0 Google. Na koniec kod ustawia opcjonalne parametry access_type i include_granted_scopes.

Na przykład ten kod żąda dostępu do Dysku Google użytkownika tylko do odczytu bez połączenia z internetem: 

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Żądanie zawiera te informacje:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.

W Pythonie wywołaj metodę from_client_secrets_file, aby pobrać identyfikator klienta z pliku client_secret.json. Możesz też użyć metody from_client_config, która przekazuje konfigurację klienta w takiej postaci, w jakiej pojawiła się w pliku tajnych klientów, ale nie miała dostępu do tego 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 interfejsu API przekierowuje użytkownika po ukończeniu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials pageklienta. Jeśli ta wartość nie będzie zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego kodu client_id, wystąpi błąd redirect_uri_mismatch.

Schemat http, https i ukośnik na końcu ('/') muszą się zgadzać.

Aby ustawić tę wartość w języku Python, ustaw właściwość flow w obiekcie redirect_uri:

flow.redirect_uri = 'https://oauth2.example.com/code'
scope Wymagany

Lista zakresów identyfikujących zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

W Pythonie użyj tej samej metody, której używasz do określenia client_id, by 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 w miarę możliwości aplikacja żądała dostępu do zakresów autoryzacji. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego aplikacja potrzebuje dostępu, o który prosi.
access_type Zalecane

Wskazuje, czy aplikacja może odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Prawidłowe wartości to online, czyli wartość domyślna, oraz offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. To jest metoda odświeżania tokenów dostępu opisanych w dalszej części tego dokumentu. Ta wartość instruuje serwer autoryzacji Google, że ma zwrócić token odświeżania oraz token dostępu po pierwszym uruchomieniu kodu autoryzacji dla tokenów.

W języku Python ustaw parametr access_type, określając access_type 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')
state Zalecane

Określa dowolną wartość ciągu tekstowego, której aplikacja używa do obsługi stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na żądanie dostępu lub odmówi jego dostępu, serwer zwróci dokładną wartość, którą wyślesz jako parę name=value w komponencie zapytania URL (?) redirect_uri.

Możesz używać tego parametru do różnych celów, takich jak kierowanie użytkownika do właściwego zasobu w aplikacji, wysyłanie jednorazowych żądań czy fałszowanie żądań pochodzących z różnych witryn. Ponieważ można zgadnąć redirect_uri, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli wygenerujesz losowy ciąg znaków lub zaszyfrujesz hasz plików cookie bądź inną wartość, która będzie przechwytywać stan klienta, możesz sprawdzić odpowiedź, aby zyskać pewność, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, co zapewnia ochronę przed atakami takimi jak fałszowanie żądań w różnych witrynach. Przykład tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.

W języku Python 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 Opcjonalnie

Umożliwia aplikacjom używanie autoryzacji przyrostowej do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na true i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp aplikacji. Przykłady znajdziesz w sekcji Autoryzacja przyrostowa.

W języku Python 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 Opcjonalnie

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru do przekazania wskazówki do serwera uwierzytelniania Google. Serwer korzysta z podpowiedzi, aby uprościć przepływ logowania, wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

Ustaw wartość parametru na adres e-mail lub identyfikator sub, który jest odpowiednikiem identyfikatora Google użytkownika.

W języku Python 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 Opcjonalnie

Lista rozdzielonych spacjami wielkości liter z pytaniami, które przedstawiają użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy pierwszy raz poprosi on o dostęp do Twojego projektu. Więcej informacji znajdziesz w artykule Ponowne wyświetlanie prośby o zgodę na wykorzystanie danych.

W języku Python 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 uzyskiwania zgody. Nie można go określać razem z innymi wartościami.
consent Pytaj użytkownika o zgodę.
select_account Wyświetlaj użytkownikowi prośbę o wybranie konta.

Ruby

Użyj utworzonego przez siebie pliku client_secrets.json, aby skonfigurować obiekt klienta w swojej aplikacji. Podczas konfigurowania obiektu klienckiego określasz zakresy, do których aplikacja musi uzyskiwać dostęp, oraz URL do punktu uwierzytelniania aplikacji, który będzie przetwarzać odpowiedź z serwera OAuth 2.0.

Na przykład ten kod żąda dostępu do Dysku Google użytkownika tylko do odczytu bez połączenia z internetem: 

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
  }
)

Aplikacja wykorzystuje obiekt kliencki do wykonywania operacji OAuth 2.0, takich jak generowanie adresów URL żądań autoryzacji i stosowanie tokenów dostępu do żądań HTTP.

Node.js

Poniższy fragment kodu tworzy obiekt google.auth.OAuth2, który określa parametry w żądaniu autoryzacji.

Ten obiekt identyfikuje aplikację na podstawie informacji z pliku client_secret.json. Aby poprosić użytkownika o pobranie tokena dostępu, zostanie przekierowany na stronę zgody. Aby utworzyć adres URL strony z prośbą o zgodę na wykorzystanie danych:

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Ważna uwaga – refresh_token jest zwracany tylko przy pierwszej autoryzacji. Więcej informacji znajdziesz tutaj.

HTTP/REST

Punkt końcowy OAuth 2.0 Google to https://accounts.google.com/o/oauth2/v2/auth. Ten punkt końcowy jest dostępny tylko przez HTTPS. Zwykłe połączenia HTTP są odrzucane.

Serwer autoryzacji Google obsługuje następujące parametry ciągu zapytania dla aplikacji serwera WWW:

Parametry
client_id Wymagany

Identyfikator klienta aplikacji. Tę wartość znajdziesz w API ConsoleCredentials page.
redirect_uri Wymagany

Określa, gdzie serwer interfejsu API przekierowuje użytkownika po ukończeniu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego w API ConsoleCredentials pageklienta. Jeśli ta wartość nie będzie zgodna z autoryzowanym identyfikatorem URI przekierowania dla podanego kodu client_id, wystąpi błąd redirect_uri_mismatch.

Schemat http, https i ukośnik na końcu ('/') muszą się zgadzać.
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

Lista rozdzielonych spacjami, które identyfikują zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości informują ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko tych zasobów, których potrzebują, a także umożliwienie użytkownikom kontrolowania poziomu dostępu przyznawanego aplikacji. Dlatego występuje odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Zalecamy, aby w miarę możliwości aplikacja żądała dostępu do zakresów autoryzacji. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego aplikacja potrzebuje dostępu, o który prosi.
access_type Zalecane

Wskazuje, czy aplikacja może odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Prawidłowe wartości to online, czyli wartość domyślna, oraz offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. To jest metoda odświeżania tokenów dostępu opisanych w dalszej części tego dokumentu. Ta wartość instruuje serwer autoryzacji Google, że ma zwrócić token odświeżania oraz token dostępu po pierwszym uruchomieniu kodu autoryzacji dla tokenów.
state Zalecane

Określa dowolną wartość ciągu tekstowego, której aplikacja używa do obsługi stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na żądanie dostępu lub odmówi jego dostępu, serwer zwróci dokładną wartość, którą wyślesz jako parę name=value w komponencie zapytania URL (?) redirect_uri.

Możesz używać tego parametru do różnych celów, takich jak kierowanie użytkownika do właściwego zasobu w aplikacji, wysyłanie jednorazowych żądań czy fałszowanie żądań pochodzących z różnych witryn. Ponieważ można zgadnąć redirect_uri, użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli wygenerujesz losowy ciąg znaków lub zaszyfrujesz hasz plików cookie bądź inną wartość, która będzie przechwytywać stan klienta, możesz sprawdzić odpowiedź, aby zyskać pewność, że żądanie i odpowiedź pochodzą z tej samej przeglądarki, co zapewnia ochronę przed atakami takimi jak fałszowanie żądań w różnych witrynach. Przykład tworzenia i potwierdzania tokena state znajdziesz w dokumentacji OpenID Connect.
include_granted_scopes Opcjonalnie

Umożliwia aplikacjom używanie autoryzacji przyrostowej do żądania dostępu do dodatkowych zakresów w kontekście. Jeśli ustawisz wartość tego parametru na true i żądanie autoryzacji zostanie przyznane, nowy token dostępu będzie obejmować wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp aplikacji. Przykłady znajdziesz w sekcji Autoryzacja przyrostowa.
login_hint Opcjonalnie

Jeśli aplikacja wie, który użytkownik próbuje się uwierzytelnić, może użyć tego parametru do przekazania wskazówki do serwera uwierzytelniania Google. Serwer korzysta z podpowiedzi, aby uprościć przepływ logowania, wypełniając pole adresu e-mail w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

Ustaw wartość parametru na adres e-mail lub identyfikator sub, który jest odpowiednikiem identyfikatora Google użytkownika.
prompt Opcjonalnie

Lista rozdzielonych spacjami wielkości liter z pytaniami, które przedstawiają użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko wtedy, gdy pierwszy raz poprosi on o dostęp do Twojego projektu. Więcej informacji znajdziesz w artykule Ponowne wyświetlanie prośby o zgodę na wykorzystanie danych.

Możliwe wartości to:

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

Krok 2. Przekieruj na serwer OAuth 2.0 Google

Przekieruj użytkownika na serwer OAuth 2.0 Google, aby zainicjować proces uwierzytelniania i autoryzacji. Zwykle ma to miejsce, gdy aplikacja musi najpierw uzyskać dostęp do danych użytkownika. W przypadku autoryzacji przyrostowej ten krok występuje również wtedy, gdy aplikacja potrzebuje dostępu do dodatkowych zasobów, do których nie ma jeszcze dostępu.

PHP

  1. Wygeneruj URL, aby poprosić o dostęp z serwera OAuth 2.0 Google: 
    $auth_url = $client->createAuthUrl();
  2. Przekieruj użytkownika do domeny $auth_url: 
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

Ten przykład pokazuje, jak przekierować użytkownika na adres URL autoryzacji za pomocą platformy aplikacji internetowej Flask:

return flask.redirect(authorization_url)

Ruby

  1. Wygeneruj URL, aby poprosić o dostęp z serwera OAuth 2.0 Google: 
    auth_uri = auth_client.authorization_uri.to_s
  2. Przekieruj użytkownika do strony auth_uri.

Node.js

  1. Użyj wygenerowanego adresu URL authorizationUrl z kroku 1 generateAuthUrl, aby poprosić o dostęp z serwera OAuth 2.0 Google.
  2. Przekieruj użytkownika do strony authorizationUrl. 
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Po utworzeniu adresu URL żądania przekieruj użytkownika na niego.

Serwer OAuth 2.0 Google uwierzytelni użytkownika i uzyska zgodę użytkownika na dostęp aplikacji do żądanych zakresów. Odpowiedź jest wysyłana do Twojej aplikacji z użyciem określonego przekierowania.

Krok 3. Google prosi użytkownika o zgodę

W tym kroku użytkownik decyduje, czy przyznać aplikacji wymagany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usługami interfejsu API Google, w ramach których prosi o dostęp z użyciem danych uwierzytelniających użytkownika i podsumowaniem zakresów dostępu, które należy przyznać. Użytkownik może następnie udzielić dostępu do co najmniej jednego zakresu, o który prosi Twoja aplikacja, lub odrzucić prośbę.

Twoja aplikacja na tym etapie nie musi nic robić, bo czeka na odpowiedź serwera OAuth 2.0 Google. Jest to informacja o tym, czy przyznano dostęp. Odpowiedź opisano w następnym kroku.

Błędy

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

admin_policy_enforced

Konto Google nie może autoryzować jednego lub większej liczby zakresów, o które prosił administrator Google Workspace. Przeczytaj artykuł pomocy dla administratorów Google Workspace i określ, które aplikacje innych firm i aplikacje wewnętrzne mają dostęp do danych Google Workspace. W ten sposób dowiesz się, w jaki sposób administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami, dopóki dostęp do identyfikatora klienta OAuth nie zostanie przyznany wprost.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika niedozwolonym przez zasady OAuth 2.0.

Android

Deweloperzy aplikacji na Androida mogą napotkać ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Deweloperzy powinni zamiast tego korzystać z bibliotek Androida, takich jak Logowanie przez Google na Androida czy Fundacja OpenIDAppAuth for Android.

Deweloperzy mogą napotkać ten błąd, gdy aplikacja na Androida otwiera ogólny link internetowy w umieszczonym kliencie użytkownika i przechodzi do punktu końcowego autoryzacji OAuth 2.0 z Twojej witryny. Deweloperzy powinni zezwolić na ogólne linki w domyślnym module obsługi linków systemu operacyjnego, który zawiera zarówno moduły obsługi aplikacji na Androida, jak i domyślną aplikację przeglądarki. Biblioteka Niestandardowe karty Androida też jest obsługiwana.

iOS

Deweloperzy iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView. Deweloperzy powinni zamiast tego korzystać z bibliotek iOS, takich jak Logowanie przez Google na iOS czy AppAuth for iOS (Podstawy Fundacji).

Deweloper może napotkać ten błąd, gdy w aplikacji na iOS lub macOS otworzy się ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przejdzie do Twojej witryny przez punkt końcowy autoryzacji OAuth 2.0. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi systemu operacyjnego, który obejmuje zarówno moduły uniwersalnych linków, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController jest też obsługiwana.
org_internal

Identyfikator klienta OAuth w żądaniu jest częścią projektu ograniczającego dostęp do kont Google w określonej organizacji Google Cloud. Więcej informacji o tej opcji konfiguracji znajdziesz w sekcji User type (Typ użytkownika) artykułu pomocy o konfigurowaniu OAuth na potrzeby uzyskiwania zgody.

redirect_uri_mismatch

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

Krok 4. Przetwórz odpowiedź serwera OAuth 2.0

Serwer OAuth 2.0 odpowiada na prośbę o dostęp do aplikacji przy użyciu adresu URL określonego w żądaniu.

Jeśli użytkownik zatwierdzi prośbę o dostęp, odpowiedź będzie zawierać kod autoryzacji. Jeśli użytkownik nie zatwierdzi żądania, odpowiedź będzie zawierać komunikat o błędzie. Ciąg zapytania lub kod błędu zwracany do serwera WWW jest widoczny w ciągu zapytania:

Odpowiedź błędu:

https://oauth2.example.com/auth?error=access_denied

Odpowiedź dotycząca kodu autoryzacji:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Przykładowa odpowiedź serwera OAuth 2.0

Możesz go przetestować, klikając ten przykładowy adres URL, który prosi o dostęp tylko do odczytu do wyświetlania metadanych plików na Dysku Google: 

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Po zakończeniu procesu OAuth 2.0 nastąpi przekierowanie na stronę http://localhost/oauth2callback, co prawdopodobnie spowoduje błąd 404 NOT FOUND, chyba że Twój komputer lokalny prześle plik pod tym adresem. Następny krok zawiera więcej informacji o identyfikatorach zwracanych w identyfikatorze URI, gdy użytkownik jest przekierowywany z powrotem do aplikacji.

Krok 5. Wymień kod autoryzacji wymiany tokenów odświeżania i dostępu

Gdy serwer WWW otrzyma kod autoryzacji, może wymienić go na token dostępu.

PHP

Aby wymienić kod autoryzacji w tokenie dostępu, użyj metody authenticate:

$client->authenticate($_GET['code']);

Token dostępu możesz pobrać, korzystając z metody getAccessToken:

$access_token = $client->getAccessToken();

Python

Na stronie wywołania zwrotnego sprawdź bibliotekę serwera autoryzacji za pomocą biblioteki google-auth. Następnie użyj metody flow.fetch_token, aby wymienić kod autoryzacji w odpowiedzi na token dostępu:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

Aby wymienić kod autoryzacji w tokenie dostępu, użyj metody fetch_access_token!:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

Aby wymienić kod autoryzacji w tokenie dostępu, użyj metody getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

Aby wymienić kod autoryzacji w tokenie dostępu, wywołaj punkt końcowy https://oauth2.googleapis.com/token i ustaw te parametry:

Pola
client_id Identyfikator klienta uzyskany z API Console Credentials page.
client_secret Obiekt tajny klienta uzyskany z API ConsoleCredentials page.
code Kod autoryzacji zwrócony z początkowego żądania.
grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 to pole musi mieć wartość authorization_code.
redirect_uri Jeden z identyfikatorów URI przekierowania wymienionych w projekcie API ConsoleCredentials page dla danego zasobu client_id.

Ten fragment kodu zawiera przykładowe żądanie:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

W odpowiedzi na to żądanie Google zwraca obiekt JSON zawierający token dostępu na krótki czas i token odświeżania. Zwróć uwagę, że token odświeżania jest zwracany tylko wtedy, gdy aplikacja ustawi parametr access_type na offline w pierwotnym żądaniu serwera autoryzacji Google&.

Odpowiedź zawiera następujące pola:

Pola
access_token Token wysyłany przez aplikację, aby autoryzować żądanie do interfejsu API Google.
expires_in Pozostały czas życia tokena 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 ich nie unieważni. To pole jest dostępne w tej odpowiedzi tylko wtedy, gdy w pierwotnym żądaniu ustawisz parametr access_type na offline dla serwera autoryzacji Google.
scope Zakresy dostępu przyznane przez zasadę access_token wyrażoną jako lista ciągów rozdzielanych spacjami, z uwzględnieniem wielkości liter.
token_type Typ zwracanego tokena. Obecnie wartość tego pola jest zawsze ustawiona na Bearer.

Poniższy fragment kodu zawiera przykładową odpowiedź:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Wywołanie interfejsów API Google

PHP

Aby wywołać tokeny interfejsu API Google, wykonaj te czynności:

  1. Jeśli chcesz zastosować token dostępu do nowego obiektu Google_Client (na przykład, jeśli token dostępu został zapisany w sesji użytkownika), użyj metody setAccessToken: 
    $client->setAccessToken($access_token);
  2. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Obiekt usługi tworzysz przez podanie konstruktora autoryzowanego obiektu Google_Client dla konstruktora interfejsu API, który chcesz wywołać. Aby na przykład wywołać interfejs Drive API: 
    $drive = new Google_Service_Drive($client);
  3. Przesyłaj żądania do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi. Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika: 
    $files = $drive->files->listFiles(array())->getItems();

Python

Gdy uzyskasz token dostępu, Twoja aplikacja może go użyć do autoryzacji żądań do interfejsu API w imieniu danego konta użytkownika lub konta usługi. Użyj danych uwierzytelniających użytkownika, aby utworzyć obiekt usługi dla interfejsu API, który chcesz wywoływać, a następnie za jego pomocą wykonywać autoryzowane żądania do interfejsu API.

  1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Aby utworzyć obiekt usługi, wywołaj metodę build biblioteki googleapiclient.discovery oraz nazwę i wersję interfejsu API oraz dane logowania użytkownika: Aby np. wywołać wersję 2 interfejsu Drive API, wykonaj te czynności: 
    from googleapiclient.discovery import build

drive = build('drive', 'v2', credentials=credentials)
  2. Przesyłaj żądania do usługi API za pomocą interfejsu udostępnionego przez obiekt usługi. Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika: 
    files = drive.files().list().execute()

Ruby

Aby wywołać obiekt API Google, użyj obiektu auth_client, wykonując te czynności:

  1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Aby na przykład wywołać wersję 2 interfejsu Drive API, wykonaj te czynności: 
    drive = Google::Apis::DriveV2::DriveService.new
  2. Ustaw dane logowania w usłudze: 
    drive.authorization = auth_client
  3. Wysyłaj żądania do usługi API za pomocą interfejsu użytkownika udostępnianego przez obiekt usługi. Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika: 
    files = drive.list_files

Autoryzację można też przeprowadzić dla poszczególnych metod, podając parametr options:

files = drive.list_files(options: { authorization: auth_client })

Node.js

Po uzyskaniu tokena dostępu i ustawieniu go na obiekt OAuth2 użyj go do wywoływania interfejsów API Google. Aplikacja może go użyć do autoryzacji żądań do interfejsu API w imieniu danego konta użytkownika lub konta usługi. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

Gdy aplikacja uzyska token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli przyznano zakresy dostępu wymagane przez interfejs API. Aby to zrobić, umieść token dostępu w żądaniu do interfejsu API, podając parametr zapytania access_token lub wartość nagłówka Authorization nagłówka Bearer. W miarę możliwości zalecamy użycie nagłówka HTTP, ponieważ ciągi zapytania są zwykle widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować, aby wywoływać wywołania interfejsów API Google (na przykład podczas wywoływania interfejsu Drive Files API).

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

Przykłady użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejsu Drive Files API) z nagłówkiem HTTP Authorization: Bearer może wyglądać tak: Pamiętaj, że musisz określić własny token dostępu:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Oto wywołanie tego samego interfejsu API dla uwierzytelnionego użytkownika z wykorzystaniem parametru ciągu zapytania access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Przykłady zapytań z operatorem curl

Te polecenia możesz przetestować za pomocą aplikacji wiersza poleceń curl. Oto przykład z użyciem opcji nagłówka HTTP (co jest zalecane):

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

Możesz też skorzystać z parametru ciągu zapytania:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Pełny przykład

W poniższym przykładzie wydrukowana jest lista plików z Dysku Google użytkownika w formacie JSON po uwierzytelnieniu przez użytkownika i uzyskaniu przez aplikację zgody na dostęp do metadanych użytkownika na Dysku.

PHP

Aby uruchomić ten przykład:

  1. W polu API Consoledodaj adres URL maszyny lokalnej do listy przekierowań. Na przykład dodaj http://localhost:8080.
  2. Utwórz nowy katalog i zmień go. Na przykład: 
    mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
  3. Zainstaluj bibliotekę klienta interfejsu API Google dla języka PHP za pomocą Composer: 
    composer require google/apiclient:^2.0
  4. Utwórz pliki index.php i oauth2callback.php z poniższą treścią.
  5. Uruchom przykład z serwerem WWW skonfigurowanym do obsługi języka PHP. Jeśli używasz PHP w wersji 5.4 lub nowszej, możesz użyć wbudowanego testowego serwera WWW PHP: 
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google_Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google_Service_Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google_Service_Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google_Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google_Service_Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

W tym przykładzie wykorzystano platformę Flask. Uruchamia ona aplikację internetową pod adresem http://localhost:8080, która umożliwia przetestowanie przepływu OAuth 2.0. Jeśli otworzysz ten URL, zobaczysz cztery linki:

  • Przetestuj żądanie interfejsu API: ten link prowadzi do strony, która próbuje wykonać przykładowe żądanie API. W razie potrzeby rozpocznie się proces autoryzacji. Jeśli operacja się uda, strona wyświetli odpowiedź interfejsu API.
  • Bezpośrednie przetestowanie procesu uwierzytelniania: ten link prowadzi do strony, która próbuje przekierować użytkownika przez proces autoryzacji. Aplikacja prosi o uprawnienia do przesyłania autoryzowanych żądań do interfejsu API w imieniu użytkownika.
  • Unieważnij bieżące dane logowania: ten link prowadzi do strony, która unieważnia uprawnienia, które użytkownik już przyznał aplikacji.
  • Wyczyść dane logowania do sesji Flask: ten link pozwala wyczyścić dane logowania zapisane w sesji Flask. Pozwala to sprawdzić, co się stanie, jeśli użytkownik, który przyznał już uprawnienia aplikacji, próbował wykonać żądanie API w nowej sesji. Umożliwia też sprawdzenie odpowiedzi interfejsu API, która zostałaby uzyskana, gdyby użytkownik unieważnił uprawnienia przyznane aplikacji, a aplikacja nadal próbowała autoryzować żądanie z unieważnionym tokenem dostępu.
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

W tym przykładzie wykorzystano platformę Sinatra.

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

Aby uruchomić ten przykład:

  1. W polu API Consoledodaj adres URL maszyny lokalnej do listy przekierowań. Na przykład dodaj http://localhost.
  2. Sprawdź, czy masz zainstalowany LTS, aktywny LTS lub bieżącą wersję Node.js.
  3. Utwórz nowy katalog i zmień go. Na przykład: 
    mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm: 
    npm install googleapis
  5. Utwórz pliki main.js zawierające poniższą treść.
  6. Uruchom przykład: 
    node .\main.js

main.js,

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

Ten przykład Pythona wykorzystuje platformę Flask i bibliotekę Requests, aby pokazać przepływ OAuth 2.0 w przeglądarce. Dla tego procesu zalecamy używanie biblioteki klienta interfejsu API Google dla Pythona. (przykład z karty Python korzysta z biblioteki klienta).

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Reguły weryfikacji URI URI

Google stosuje poniższe reguły weryfikacji do przekierowań identyfikatorów URI, aby pomóc deweloperom w zabezpieczeniu aplikacji. Identyfikatory URI przekierowań muszą być zgodne z tymi regułami. Definicję domeny, hosta, ścieżki, zapytania, schematu i informacji o użytkowniku znajdziesz w RFC 3986, sekcja 3 poniżej.

Reguły weryfikacji
Schemat

Identyfikatory URI przekierowań muszą używać schematu HTTPS, a nie zwykłego protokołu HTTP. Identyfikatory URI lokalnego (w tym identyfikatory URI adresów lokalnych hostów) są zwolnione z tej reguły.
Osoba prowadząca

Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP lokalnego hosta są zwolnione z tej reguły.
Domena
  • Domeny najwyższego poziomu najwyższego poziomu (domeny najwyższego poziomu) muszą należeć do listy domen publicznych.
  • Domeny hosta nie mogą być typu “googleusercontent.com”.
  • Identyfikatory URI przekierowań nie mogą zawierać domen skracających adresy URL (np. goo.gl), chyba że właścicielem domeny jest aplikacja. Ponadto, jeśli aplikacja będąca właścicielem domeny skróconej wykryje przekierowanie do tej domeny, musi on zawierać ścieżkę “/google-callback/” na końcu lub kończyć się ciągiem “/google-callback”.
    		•
    Informacje o użytkowniku

    Identyfikatory URI przekierowań nie mogą zawierać podkomponentu userinfo.
    Ścieżka

    Identyfikatory URI przekierowań nie mogą zawierać omijania ścieżki (nazywanej też przekierowaniem katalogu), które jest reprezentowane przez kod “/..” lub “\..” lub ich kodowanie URL.
    Zapytanie

    Identyfikatory URI przekierowań nie mogą zawierać otwartych przekierowań.
    Fragment

    Identyfikatory URI przekierowań nie mogą zawierać komponentu fragmentu.
    Znaki Identyfikatory URI przekierowań nie mogą zawierać niektórych znaków, m.in.:
    • Symbole wieloznaczne ('*')
    • Znaki ASCII niedrukowalne
    • Nieprawidłowe kodowanie procentowe (dowolne kodowanie procentowe nie występuje po zakodowaniu adresu URL z użyciem znaku procenta, po którym następuje dwie cyfry szesnastkowe)
    • Brak znaków (zakodowany znak NULL, np. %00, %C0%80)

    Autoryzacja przyrostowa

    W protokole OAuth 2.0 aplikacja prosi o autoryzację dostępu do zasobów identyfikowanych przez zakresy. Prośba o autoryzację zasobów w odpowiednim momencie jest uznawana za najlepszą metodę zwiększania wygody użytkowników. Aby włączyć tę praktykę, serwer autoryzacji Google i obsługuje autoryzację przyrostową. Ta funkcja umożliwia żądanie zakresów w razie potrzeby. Jeśli użytkownik udzieli zgody na nowy zakres, zostanie zwrócony kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy przyznane przez użytkownika projektowi.

    Na przykład aplikacja, która umożliwia pobieranie utworów muzycznych i tworzenie składanek, może nie mieć wielu zasobów poza nazwą logowania. Zapisanie gotowej składanki wymaga jednak dostępu do Dysku Google. Większość ludzi uznałaby, że prośba o dostęp do Dysku Google pojawia się dopiero wtedy, gdy aplikacja faktycznie jej potrzebuje.

    W takim przypadku przy logowaniu aplikacja może poprosić o zakresy openid i profile, aby przeprowadzić logowanie podstawowe, a potem w momencie pierwszego żądania wysłać prośbę o zapisanie zakresu https://www.googleapis.com/auth/drive.file.

    Aby wdrożyć autoryzację przyrostową, musisz wykonać normalny proces żądania tokena dostępu, ale upewnij się, że żądanie autoryzacji obejmuje wcześniej przyznane zakresy. Dzięki temu Twoja aplikacja nie musi zarządzać wieloma tokenami dostępu.

    W przypadku tokena dostępu uzyskanego z przyrostowej autoryzacji obowiązują te reguły:

    • Pozwala on uzyskać dostęp do zasobów odpowiadających dowolnemu zakresowi wdrożonemu w nowej, połączonej autoryzacji.
    • Jeśli używasz tokenu odświeżania połączonej autoryzacji, aby uzyskać token dostępu, token dostępu reprezentuje połączoną autoryzację i może być używany dla dowolnej wartości scope w odpowiedzi.
    • Połączona autoryzacja obejmuje wszystkie zakresy przyznane użytkownikowi przez projekt interfejsu API, nawet jeśli prośby o granty pochodzą od różnych klientów. Jeśli na przykład użytkownik przyznał dostęp do jednego zakresu za pomocą klienta na komputery, a następnie przyznasz innemu zakresowi tę samą aplikację za pomocą klienta mobilnego, łączna autoryzacja będzie obejmować oba zakresy.
    • Jeśli unieważnisz token reprezentujący połączoną autoryzację, dostęp do wszystkich zakresów tej autoryzacji zostanie unieważniony jednocześnie w imieniu powiązanego użytkownika.

    Przykładowe kody językowe w sekcji Krok 1. Ustaw parametry autoryzacji i przykładowy adres URL przekierowania HTTP/REST opisane w sekcji Krok 2. Przekieruj na serwer OAuth 2.0 Google korzystają z uwierzytelniania przyrostowego. Poniżej znajdziesz przykładowy kod, który musisz dodać, by używać autoryzacji przyrostowej.

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

    W Pythonie ustaw argument słowa kluczowego include_granted_scopes na true, aby mieć pewność, że żądanie autoryzacji obejmuje wcześniej przyznane zakresy. Bardzo możliwe, że include_granted_scopes nie będzie ustawionym jedynym argumentem słowa kluczowego, jak widać w przykładzie poniżej.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Ruby

    auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.file&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

    Odświeżanie tokena dostępu (dostęp offline)

    Tokeny dostępu okresowo tracą ważność i stają się nieprawidłowe poświadczenia powiązanego żądania interfejsu API. Jeśli chcesz uzyskać dostęp offline do zakresów powiązanych z tokenem, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (w tym, gdy nie ma użytkownika).

    • Jeśli używasz biblioteki klienta interfejsu API Google, obiekt kliencki odświeża token dostępu według potrzeb, dopóki masz skonfigurowany ten obiekt na potrzeby dostępu offline.
    • Jeśli nie korzystasz z biblioteki klienta, podczas przekierowania użytkownika na serwer OAuth 2.0 Google ustaw parametr HTTP access_type na offline. W takim przypadku serwer autoryzacji Google i zwraca token odświeżania, gdy wymienisz kod autoryzacji na token dostępu. Jeśli token dostępu wygaśnie (lub w dowolnym innym momencie), możesz użyć tokena odświeżania, aby uzyskać nowy.

    Prośba o dostęp offline jest wymagana w przypadku każdej aplikacji, która potrzebuje dostępu do interfejsu Google API, gdy nie ma użytkownika. Na przykład aplikacja, która wykonuje usługi zapasowe lub wykonuje działania we wcześniej ustalonych godzinach, musi mieć możliwość odświeżania tokena dostępu, gdy użytkownik nie jest dostępny. Domyślny styl dostępu to online.

    Aplikacje internetowe, zainstalowane aplikacje i urządzenia po stronie serwera otrzymują tokeny odświeżania podczas procesu autoryzacji. Tokeny odświeżania nie są zwykle używane w aplikacjach internetowych (JavaScript) po stronie klienta.

    PHP

    Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu Google API, ustaw typ dostępu klienta API na offline:

    $client->setAccessType("offline");

    Gdy użytkownik udzieli dostępu offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu zgodnie z potrzebami.

    Python

    W Pythonie ustaw argument słowa kluczowego access_type na offline, aby mieć pewność, że możesz odświeżyć token dostępu bez konieczności ponownego potwierdzania użytkownikowi uprawnień. Bardzo możliwe, że access_type nie będzie ustawionym jedynym argumentem słowa kluczowego, jak widać w przykładzie poniżej.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Gdy użytkownik udzieli dostępu offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu zgodnie z potrzebami.

    Ruby

    Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu Google API, ustaw typ dostępu klienta API na offline:

    auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

    Gdy użytkownik udzieli dostępu offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu zgodnie z potrzebami.

    Node.js

    Jeśli Twoja aplikacja potrzebuje dostępu offline do interfejsu Google API, ustaw typ dostępu klienta API na offline:

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    Gdy użytkownik udzieli dostępu offline do żądanych zakresów, możesz nadal używać klienta API do uzyskiwania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu zgodnie z potrzebami.

    Tokeny dostępu wygasają. Ta biblioteka automatycznie użyje tokena odświeżania, aby uzyskać nowy token dostępu, jeśli niedługo wygaśnie. Aby mieć pewność, że zawsze przechowujesz najnowsze tokeny, użyj zdarzenia tokenów:

    oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

    Zdarzenie związane z tokenem pojawia się tylko w pierwszej autoryzacji. Aby wywołać token odświeżania, musisz ustawić access_type na offline podczas wywoływania metody generateAuthUrl. Jeśli aplikacja otrzymała już wymagane uprawnienia bez ustawiania ograniczeń dotyczących otrzymywania tokena odświeżania, musisz ponownie autoryzować tę aplikację, aby mogła otrzymać nowy token odświeżania.

    Aby ustawić refresh_token później, możesz użyć metody setCredentials: 

    oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

    Gdy klient uzyska token odświeżania, tokeny dostępu zostaną pozyskane i odświeżone automatycznie podczas kolejnego wywołania interfejsu API.

    HTTP/REST

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

    Pola
    client_id Identyfikator klienta uzyskany z API Console.
    client_secret Obiekt tajny klienta uzyskany z API Console.
    grant_type Zgodnie z definicją w specyfikacji OAuth 2.0 to pole musi mieć wartość refresh_token.
    refresh_token Token odświeżania zwrócony z wymiany kodu autoryzacji.

    Ten fragment kodu zawiera przykładowe żądanie:

    POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

    Dopóki użytkownik nie anuluje dostępu aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Ten fragment kodu zawiera przykładową odpowiedź:

    {
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

    Pamiętaj, że obowiązuje limit liczby tokenów odświeżania, które mogą zostać zrealizowane: jeden limit na kombinację klienta i użytkownika i jeden na użytkownika we wszystkich klientach. Zapisz tokeny odświeżania w długoterminowym miejscu i używaj ich, dopóki będą ważne. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, może to spowodować przekroczenie tych limitów. W takim przypadku starsze tokeny odświeżania przestaną działać.

    Unieważnianie tokena

    W niektórych przypadkach użytkownik może unieważnić dostęp aplikacji. Użytkownik może cofnąć dostęp w ustawieniach konta. Więcej informacji znajdziesz w sekcji pomocy dotyczącej usuwania dostępu do witryn i aplikacji z witryn i aplikacji innych firm, które mają dostęp do Twojego konta.

    Możliwe jest też unieważnienie przez aplikację przyznanego dostępu. Automatyczne unieważnienie jest ważne, jeśli użytkownik anuluje subskrypcję, usunie aplikację lub zasoby interfejsu API wymagane przez aplikację znacznie się zmieniły. Oznacza to, że część procesu usuwania może obejmować żądanie interfejsu API, które zapewnia usunięcie wcześniej przyznanych uprawnień aplikacji.

    PHP

    Aby automatycznie unieważnić token, wywołaj metodę revokeToken():

    $client->revokeToken();

    Python

    Aby automatycznie unieważnić token, wyślij żądanie do https://oauth2.googleapis.com/revoke zawierające token jako parametr i ustaw nagłówek Content-Type:

    requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    Aby automatycznie unieważnić token, wyślij żądanie HTTP do punktu końcowego oauth2.revoke:

    uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

    Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma przypisany token odświeżania, zostanie on też unieważniony.

    Jeśli odwołanie zostało pomyślnie przetworzone, kod stanu odpowiedzi będzie wyglądać tak: 200. W przypadku warunków błędu zwracany jest kod stanu 400 wraz z kodem błędu.

    Node.js

    Aby automatycznie unieważnić token, wyślij żądanie HTTPS POST do punktu końcowego /revoke:

    const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

    Parametr tokenu może być tokenem dostępu lub tokenem odświeżania. Jeśli token jest tokenem dostępu i ma przypisany token odświeżania, zostanie on też unieważniony.

    Jeśli odwołanie zostało pomyślnie przetworzone, kod stanu odpowiedzi będzie wyglądać tak: 200. W przypadku warunków błędu zwracany jest kod stanu 400 wraz z kodem błędu.

    HTTP/REST

    Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i uwzględnia go jako parametr:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

    Może to być token dostępu lub token odświeżania. Jeśli token jest tokenem dostępu i ma przypisany token odświeżania, też zostanie on unieważniony.

    Jeśli odwołanie zostało pomyślnie przetworzone, kod stanu HTTP odpowiedzi będzie wynosił 200. W przypadku błędów zwracany jest kod stanu HTTP 400 wraz z kodem błędu.