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

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Ten dokument wyjaśnia, w jaki sposób aplikacje serwera WWW 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 jednoczesnym zachowaniu nazw użytkowników, haseł i innych informacji. Aplikacja może na przykład używać protokołu OAuth 2.0 w celu uzyskania zgody od użytkowników na przechowywanie plików na ich Dyskach Google.

Protokół OAuth 2.0 jest przeznaczony konkretnie do autoryzacji użytkowników. Jest ona przeznaczona dla aplikacji, które mogą przechowywać informacje poufne i utrzymywać ich stan. Prawidłowo autoryzowana aplikacja serwera WWW może uzyskać dostęp do interfejsu API, gdy użytkownik wejdzie w interakcję z aplikacją lub gdy ją opuści.

Aplikacje serwera WWW często używają też kont usługi do autoryzowania żądań do interfejsu API, zwłaszcza w przypadku wywoływania interfejsów API Cloud, by uzyskać dostęp do danych związanych z projektem, a nie do poszczególnych danych użytkownika. Aplikacje serwera WWW mogą używać kont usługi w połączeniu z autoryzacją użytkowników.

Biblioteki klienta

Przykłady wersji zależnej od języka na tej stronie wykorzystują biblioteki interfejsu API Google do uwierzytelniania OAuth 2.0. Aby uruchomić przykładowy kod, musisz najpierw zainstalować bibliotekę klienta w swoim języku.

Gdy używasz biblioteki klienta interfejsu API Google do obsługi protokołu OAuth 2.0, biblioteka klienta wykonuje wiele działań, które w innej sytuacji wymagałyby obsługi aplikacji. Określa na przykład, kiedy aplikacja może używać lub odświeżać zapisane tokeny dostępu, a także kiedy aplikacja musi uzyskać zgodę. Biblioteka klienta generuje też poprawne przekierowania i pomaga zaimplementować moduły przekierowania, które wymieniają kody autoryzacji dla tokenów dostępu.

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

Wymagania wstępne

Włączanie interfejsów API w projekcie

Każda aplikacja, która wywołuje interfejsy API Google, musi włączyć te interfejsy API 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 wyszukiwarki, aby go znaleźć, lub kliknij Wyświetl wszystkie 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 logowania

Każda aplikacja korzystająca z protokołu OAuth 2.0, która uzyskuje dostęp do interfejsów API Google, musi mieć dane logowania umożliwiające identyfikację aplikacji na serwerze OAuth 2.0 Google. Aby utworzyć dane logowania do projektu, wykonaj opisane poniżej czynności. Twoje aplikacje będą mogły używać danych logowania do dostępu do interfejsów API włączonych w tym projekcie.

  1. Go to the Credentials page.
  2. Kliknij Utwórz dane logowania i identyfikator klienta OAuth.
  3. Wybierz typ aplikacji Aplikacja internetowa.
  4. Wypełnij formularz i kliknij Utwórz. Aplikacje, które używają języków i platform takich jak PHP, Java, Python, Ruby i .NET, muszą określić autoryzowane identyfikatory URI przekierowań. 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 testowania możesz określić identyfikatory URI odwołujące się do komputera lokalnego, np. http://localhost:8080. Pamiętaj, że wszystkie przykłady w tym dokumencie korzystają z http://localhost:8080 jako identyfikatora URI przekierowania.

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

Po utworzeniu danych logowania pobierz plik client_secret.json z katalogu API Console. bezpiecznie przechowywać plik w lokalizacji, do której dostęp ma tylko Twoja aplikacja;

Zakresy dostępu

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, a jednocześnie umożliwienie użytkownikom kontrolowania poziomu dostępu przyznanego aplikacji. Dlatego może występować odwrotna zależność między liczbą żądanych zakresów a prawdopodobieństwem uzyskania zgody użytkownika.

Przed rozpoczęciem autoryzacji OAuth 2.0 zalecamy określenie zakresów, do których aplikacja będzie potrzebować dostępu.

Zalecamy również, aby aplikacja prosiła o dostęp do zakresów autoryzacji przy użyciu przyrostowego procesu autoryzacji, w którym aplikacja prosi o dostęp do danych użytkownika w kontekście. Ta sprawdzona metoda pozwala użytkownikom lepiej zrozumieć, dlaczego Twoja aplikacja potrzebuje dostępu, o który prosi.

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

Wymagania dla poszczególnych języków

Aby uruchomić przykładowy kod w tym dokumencie, musisz mieć konto Google, dostęp do internetu i przeglądarkę. Jeśli używasz jednej z bibliotek klienta interfejsu API, zapoznaj się też z wymaganiami dotyczącymi wybranego języka poniżej.

PHP

Aby uruchomić przykładowy kod PHP w tym dokumencie, musisz mieć:

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

  • Biblioteka klienta Google APIs for PHP:

    composer require google/apiclient:^2.10

Python

Aby uruchomić przykładowy kod w Pythonie w tym dokumencie, musisz mieć:

  • Python 2.6 lub nowszy
  • Narzędzie do zarządzania pakietami pip.
  • Biblioteka klienta Google API dla Pythona: 
    pip install --upgrade google-api-python-client
  • google-auth, google-auth-oauthlib i google-auth-httplib2 do uwierzytelniania użytkowników. 
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • Platforma aplikacji internetowej Flask Python. 
    pip install --upgrade flask
  • Biblioteka HTTP requests. 
    pip install --upgrade requests

Ruby

Aby uruchomić przykładowy kod Ruby w tym dokumencie, musisz mieć:

  • Ruby 2.2.2 lub nowsza

  • 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ć w tym dokumencie przykładowy kod Node.js, potrzebujesz:

  • LTS konserwacji, aktywna LTS lub bieżąca wersja Node.js.

  • Klient Node.js interfejsów API Google:

    npm install googleapis

HTTP/REST

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

Uzyskiwanie tokenów dostępu OAuth 2.0

Kroki opisane poniżej pokazują, jak aplikacja współdziała z serwerem OAuth 2.0 w celu uzyskania zgody na żądanie interfejsu API w imieniu użytkownika. Aplikacja musi mieć tę zgodę, aby móc wykonać żądanie interfejsu Google API, które wymaga autoryzacji użytkownika.

Poniższa lista zawiera krótkie podsumowanie tych czynności:

  1. Aplikacja określa wymagane uprawnienia.
  2. Aplikacja przekierowuje użytkownika do Google wraz z listą wymaganych uprawnień.
  3. To użytkownik decyduje, czy przyznać aplikacji uprawnienia.
  4. Aplikacja sprawdza, co wybrał użytkownik.
  5. Jeśli użytkownik przyznał wymagane 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 prośby o autoryzację. To żądanie określa parametry identyfikujące aplikację i określa uprawnienia, jakie użytkownik będzie musiał przyznać aplikacji.

  • Jeśli do uwierzytelniania i autoryzacji OAuth 2.0 używasz biblioteki klienta Google, możesz utworzyć i skonfigurować obiekt, który określa te parametry.
  • Jeśli wywołasz bezpośrednio punkt końcowy Google OAuth 2.0, wygenerujesz URL i ustawisz parametry dla tego adresu.

Na poniższych kartach określono obsługiwane parametry autoryzacji dla serwerów WWW. Przykładowe języki pokazują, jak za pomocą biblioteki klienta lub biblioteki autoryzacji skonfigurować obiekt, który ustawia te parametry.

PHP

Fragment kodu poniżej tworzy obiekt Google\Client(), który określa parametry w żądaniu autoryzacji.

Ten obiekt identyfikuje aplikację na podstawie informacji z pliku client_secret.json. Więcej informacji o tym pliku znajdziesz w artykule na temat tworzenia danych logowania. Obiekt identyfikuje też zakresy, do których aplikacja prosi o dostęp, oraz URL do punktu uwierzytelniania aplikacji, który obsługuje odpowiedź z serwera OAuth 2.0 Google. Na koniec kod ustawia opcjonalne parametry access_type i include_granted_scopes.

Na przykład ten kod prosi o dostęp 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 te informacje:

Parametry
client_id Wymagany

Identyfikator klienta Twojej aplikacji. Ta wartość jest podana w API Console Credentials page.

W PHP wywołaj funkcję setAuthConfig, aby wczytać dane logowania autoryzacji 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 zakończeniu procesu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego przez Ciebie w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego atrybutu client_id, wystąpi błąd redirect_uri_mismatch.

Pamiętaj, że wszystkie ciągi (http i https) oraz ukośniki na końcu ('/') muszą być ze sobą zgodne.

Aby ustawić tę wartość w 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 zakresów określających zasoby, do których aplikacja może uzyskiwać dostęp w imieniu użytkownika. Te wartości określają ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, a jednocześnie umożliwienie użytkownikom kontrolowania poziomu dostępu przyznanego 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 PHP, wywołaj funkcję addScope:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

Zalecamy, aby w miarę możliwości aplikacja prosiła o dostęp do zakresów autoryzacji. Prosząc o dostęp do danych użytkownika w kontekście, korzystając z autoryzacji przyrostowej, ułatwiasz użytkownikom zrozumienie, dlaczego Twoja aplikacja potrzebuje dostępu.
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 parametrów to online (czyli wartość domyślna) i offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisanych później w tym dokumencie. Ta wartość instruuje serwer autoryzacji Google, aby zwracał token odświeżania oraz token dostępu po pierwszym uruchomieniu kodu autoryzacji dla tokenów.

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

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

Określa dowolną wartość ciągu tekstowego, której aplikacja używa do utrzymania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na dostęp do aplikacji lub ją odrzuci, serwer zwraca dokładną wartość, którą wysyłasz w postaci pary 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 odpowiedniego zasobu w aplikacji, wysyłanie jednorazowych żądań lub łagodzenie sfałszowanych żądań z innych witryn. Odgadniesz wartość redirect_uri, więc użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli generujesz losowy ciąg znaków lub kodujesz hasz pliku cookie albo inną wartość, która rejestruje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami typu sfałszowanie żądania z innej witryny. Przykład tworzenia i potwierdzenia tokena state znajdziesz w dokumentacji OpenID Connect.

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

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

Umożliwia aplikacjom korzystanie z 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 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 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, aby podać serwerowi uwierzytelniania Google. Serwer wykorzystuje wskazówkę, aby uprościć proces logowania, wypełniając pole e-maila w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

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

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

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

Lista rozdzielonych spacjami (z rozróżnianiem wielkości liter) próśb o podanie informacji użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko po pierwszym uruchomieniu dostępu do Twojego projektu. Więcej informacji znajdziesz w artykule Wysyłanie prośby 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 określać innych wartości.
consent Pytaj użytkownika o zgodę na wykorzystanie danych.
select_account Pytaj użytkownika o wybór konta.

Python

Poniższy fragment kodu wykorzystuje moduł google-auth-oauthlib.flow do skompilowania żądania autoryzacji.

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

Na przykład ten kod prosi o dostęp 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 te informacje:

Parametry
client_id Wymagany

Identyfikator klienta Twojej aplikacji. Ta wartość jest podana w API Console Credentials 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 początkowo była widoczna w pliku obiektów tajnych klienta, 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 zakończeniu procesu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego przez Ciebie w API Console Credentials page. Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego atrybutu client_id, wystąpi błąd redirect_uri_mismatch.

Pamiętaj, że wszystkie ciągi (http i https) oraz ukośniki na końcu ('/') muszą być ze sobą zgodne.

Aby ustawić tę wartość w języku Python, 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 uzyskiwać dostęp w imieniu użytkownika. Te wartości określają ekran zgody, który Google wyświetla użytkownikowi.

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, a jednocześnie umożliwienie użytkownikom kontrolowania poziomu dostępu przyznanego 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, co w przypadku 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 prosiła o dostęp 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 Twoja aplikacja potrzebuje dostępu.
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 parametrów to online (czyli wartość domyślna) i offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisanych później w tym dokumencie. Ta wartość instruuje serwer autoryzacji Google, aby zwracał token odświeżania oraz token dostępu po pierwszym uruchomieniu kodu autoryzacji dla tokenów.

W Pythonie ustaw parametr access_type, podają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 utrzymania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na dostęp do aplikacji lub ją odrzuci, serwer zwraca dokładną wartość, którą wysyłasz w postaci pary 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 odpowiedniego zasobu w aplikacji, wysyłanie jednorazowych żądań lub łagodzenie sfałszowanych żądań z innych witryn. Odgadniesz wartość redirect_uri, więc użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli generujesz losowy ciąg znaków lub kodujesz hasz pliku cookie albo inną wartość, która rejestruje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami typu sfałszowanie żądania z innej witryny. Przykład tworzenia i potwierdzenia tokena state znajdziesz w dokumentacji OpenID Connect.

W Pythonie ustaw parametr state, podają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 korzystanie z 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 będzie obejmować wszystkie zakresy, do których użytkownik wcześniej przyznał dostęp aplikacji. Przykłady znajdziesz w sekcji Autoryzacja przyrostowa.

W Pythonie ustaw parametr include_granted_scopes, podają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, aby podać serwerowi uwierzytelniania Google. Serwer wykorzystuje wskazówkę, aby uprościć proces logowania, wypełniając pole e-maila w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

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

W Pythonie ustaw parametr login_hint, podają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 (z rozróżnianiem wielkości liter) próśb o podanie informacji użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko po pierwszym uruchomieniu dostępu do Twojego projektu. Więcej informacji znajdziesz w artykule Wysyłanie prośby o ponowną zgodę.

W Pythonie ustaw parametr prompt, podają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 określać innych wartości.
consent Pytaj użytkownika o zgodę na wykorzystanie danych.
select_account Pytaj użytkownika o wybór konta.

Ruby

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

Na przykład ten kod prosi o dostęp 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
  }
)

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

Fragment kodu poniżej tworzy obiekt google.auth.OAuth2, który określa parametry w żądaniu autoryzacji.

Ten obiekt używa informacji z pliku client_secret.json do identyfikowania Twojej aplikacji. Aby poprosić użytkownika o uprawnienia do pobrania tokena dostępu, przekierowujesz go 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 znajduje się w lokalizacji 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 te parametry ciągu zapytania w przypadku aplikacji internetowych:

Parametry
client_id Wymagany

Identyfikator klienta Twojej aplikacji. Ta wartość jest podana w API Console Credentials page.
redirect_uri Wymagany

Określa, gdzie serwer interfejsu API przekierowuje użytkownika po zakończeniu procesu autoryzacji. Wartość musi dokładnie odpowiadać jednemu z autoryzowanych identyfikatorów URI przekierowania dla klienta OAuth 2.0 skonfigurowanego przez Ciebie w API Console Credentials page . Jeśli ta wartość nie pasuje do autoryzowanego identyfikatora URI przekierowania dla podanego atrybutu client_id, wystąpi błąd redirect_uri_mismatch.

Pamiętaj, że wszystkie ciągi (http i https) oraz ukośniki na końcu ('/') muszą być ze sobą 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

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

Zakresy umożliwiają aplikacji żądanie tylko dostępu do potrzebnych zasobów, a jednocześnie umożliwienie użytkownikom kontrolowania poziomu dostępu przyznanego 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 prosiła o dostęp 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 Twoja aplikacja potrzebuje dostępu.
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 parametrów to online (czyli wartość domyślna) i offline.

Ustaw wartość offline, jeśli aplikacja musi odświeżać tokeny dostępu, gdy użytkownik nie jest obecny w przeglądarce. Jest to metoda odświeżania tokenów dostępu opisanych później w tym dokumencie. Ta wartość instruuje serwer autoryzacji Google, aby zwracał 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 utrzymania stanu między żądaniem autoryzacji a odpowiedzią serwera autoryzacji. Gdy użytkownik wyrazi zgodę na dostęp do aplikacji lub ją odrzuci, serwer zwraca dokładną wartość, którą wysyłasz w postaci pary 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 odpowiedniego zasobu w aplikacji, wysyłanie jednorazowych żądań lub łagodzenie sfałszowanych żądań z innych witryn. Odgadniesz wartość redirect_uri, więc użycie wartości state może zwiększyć pewność, że połączenie przychodzące jest wynikiem żądania uwierzytelniania. Jeśli generujesz losowy ciąg znaków lub kodujesz hasz pliku cookie albo inną wartość, która rejestruje stan klienta, możesz zweryfikować odpowiedź, aby dodatkowo upewnić się, że żądanie i odpowiedź pochodzą z tej samej przeglądarki. Zapewnia to ochronę przed atakami typu sfałszowanie żądania z innej witryny. Przykład tworzenia i potwierdzenia tokena state znajdziesz w dokumentacji OpenID Connect.
include_granted_scopes Opcjonalnie

Umożliwia aplikacjom korzystanie z 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 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, aby podać serwerowi uwierzytelniania Google. Serwer wykorzystuje wskazówkę, aby uprościć proces logowania, wypełniając pole e-maila w formularzu logowania lub wybierając odpowiednią sesję wielokrotnego logowania.

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

Lista rozdzielonych spacjami (z rozróżnianiem wielkości liter) próśb o podanie informacji użytkownikowi. Jeśli nie określisz tego parametru, użytkownik zobaczy prośbę tylko po pierwszym uruchomieniu dostępu do Twojego projektu. Więcej informacji znajdziesz w artykule Wysyłanie prośby o ponowną zgodę.

Możliwe wartości to:

none Nie wyświetlaj żadnych ekranów uwierzytelniania ani zgody. Nie można określać innych wartości.
consent Pytaj użytkownika o zgodę na wykorzystanie danych.
select_account Pytaj użytkownika o wybór konta.

Krok 2. Przekieruj na serwer OAuth 2.0 Google

Aby rozpocząć uwierzytelnianie i autoryzację, przekieruj użytkownika do serwera OAuth 2.0. Zwykle dzieje się tak, gdy aplikacja najpierw musi uzyskać dostęp do danych użytkownika. W przypadku autoryzacji przyrostowej ten krok występuje też wtedy, gdy aplikacja musi najpierw uzyskać dostęp do dodatkowych zasobów, do których nie ma jeszcze uprawnień.

PHP

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

Python

Ten przykład pokazuje, jak przekierować użytkownika do adresu URL autoryzacji przy użyciu platformy aplikacji internetowej Flask:

return flask.redirect(authorization_url)

Ruby

  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 1generateAuthUrl, 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 do niego.

Serwer OAuth 2.0 firmy Google uwierzytelnia użytkownika i uzyskuje od użytkownika zgodę na dostęp aplikacji do żądanych zakresów. Odpowiedź jest wysyłana z powrotem do aplikacji z użyciem określonego przez Ciebie adresu URL przekierowania.

Krok 3. Google prosi użytkownika o zgodę

W tym kroku użytkownik decyduje, czy przyznać aplikacji żądany dostęp. Na tym etapie Google wyświetla okno zgody z nazwą aplikacji i usługami interfejsu API Google, których dotyczy prośba o przyznanie dostępu, korzystając z danych uwierzytelniających użytkownika i podsumowania zakresów dostępu. Użytkownik może wyrazić zgodę na przyznanie dostępu do co najmniej 1 zakresu wymaganego przez aplikację lub odrzucić prośbę.

Na tym etapie aplikacja nie musi nic robić, ponieważ czeka na odpowiedź serwera OAuth 2.0 Google. Odpowiedź została wyjaśniona w następnym kroku.

Błędy

Żądania wysyłane do punktów końcowych autoryzacji OAuth 2.0 mogą wyświetlać komunikaty o błędach wyświetlane użytkownikom, a nie spodziewane 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ć co najmniej 1 zakresu wymaganego przez zasady Google Workspace administratora. Więcej informacji o tym, jak administrator może ograniczyć dostęp do wszystkich zakresów lub zakresów wrażliwych i zakresów z ograniczeniami, znajdziesz w artykule pomocy dla administratorów Google Workspace dotyczącym kontroli dostępu do danych z innych aplikacji przez Google Workspace.

disallowed_useragent

Punkt końcowy autoryzacji jest wyświetlany w umieszczonym kliencie użytkownika niezgodnym z zasadami OAuth 2.0.

Android

Deweloperzy Androida mogą zobaczyć ten komunikat o błędzie podczas otwierania żądań autoryzacji w android.webkit.WebView. Zamiast tego deweloperzy powinni korzystać z bibliotek Androida, takich jak Logowanie przez Google na Androida czy Podstawy aplikacji na Androida.

Ten błąd może wystąpić, gdy aplikacja na Androida otwiera ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przechodzi do punktu końcowego autoryzacji OAuth 2.0 z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który obejmuje zarówno moduły Linków aplikacji na Androida, jak i domyślną aplikację przeglądarki. Obsługiwaną jest też biblioteka Niestandardowe karty.

iOS

Programy na iOS i macOS mogą napotkać ten błąd podczas otwierania żądań autoryzacji w WKWebView. Zamiast tego powinni oni korzystać z bibliotek iOS, takich jak Logowanie przez Google na iOS lub OpenID Foundation's AppAuth for iOS.

Ten błąd może wystąpić, gdy aplikacja na iOS lub macOS otwiera ogólny link internetowy w umieszczonym kliencie użytkownika, a użytkownik przechodzi do punktu końcowego autoryzacji OAuth 2.0 z Twojej witryny. Deweloperzy powinni zezwolić na otwieranie ogólnych linków w domyślnym module obsługi linków systemu operacyjnego, który zawiera zarówno moduły uniwersalnych linków, jak i domyślną aplikację przeglądarki. Biblioteka SFSafariViewController też jest 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) w artykule „Konfigurowanie ekranu zgody OAuth” artykułu pomocy.

redirect_uri_mismatch

Parametr 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 żądanie dostępu do aplikacji, używając adresu URL podanego w żądaniu.

Jeśli użytkownik zatwierdzi prośbę o dostęp, odpowiedź będzie zawierać kod autoryzacji. Jeśli użytkownik nie zatwierdzi prośby, w odpowiedzi zostanie wyświetlony komunikat o błędzie. Ciąg zapytania lub komunikat o błędzie zwracany do serwera WWW, jak widać poniżej:

Odpowiedź o błędzie:

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

Aby przetestować ten proces, kliknij ten przykładowy URL, który umożliwia dostęp tylko do odczytu do 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 uwierzytelniania OAuth 2.0 przekierujemy Cię na stronę http://localhost/oauth2callback, która prawdopodobnie zwróci błąd 404 NOT FOUND, chyba że Twój komputer lokalny wyświetla plik pod tym adresem. Następny krok zawiera więcej szczegółów dotyczących informacji zwracanych w identyfikatorze URI, gdy użytkownik zostaje przekierowany z powrotem do aplikacji.

Krok 5. Zmień kod autoryzacji Exchange na potrzeby tokenów odświeżania i dostępu

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

PHP

Aby wymienić kod autoryzacji dla tokena dostępu, użyj metody authenticate:

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

Token dostępu możesz pobrać za pomocą metody getAccessToken:

$access_token = $client->getAccessToken();

Python

Na stronie wywołania zwrotnego użyj biblioteki google-auth, aby zweryfikować odpowiedź serwera autoryzacji. 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 dla tokena dostępu, użyj metody fetch_access_token!:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

Aby wymienić kod autoryzacji dla tokena dostępu, użyj metody getToken:

const url = require('url');

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

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

HTTP/REST

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

Pola
client_id Identyfikator klienta uzyskany z: API Console Credentials page.
client_secret Tajny klucz klienta uzyskany z: API Console Credentials page.
code Kod autoryzacji zwrócony z 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 w sekcji API ConsoleCredentials page dla danego client_id.

Przykładowy fragment żądania:

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 krótkoterminowy dostępu i token odświeżania. Token odświeżania jest zwracany tylko wtedy, gdy aplikacja ustawia parametr access_type na offline w pierwszym żądaniu autoryzacji serwera Google.

Odpowiedź zawiera te pola:

Pola
access_token Token wysyłany przez aplikację do autoryzacji żądania do interfejsu API Google.
expires_in Pozostały okres dostępu w sekundach.
refresh_token Token, którego możesz użyć do uzyskania nowego tokena dostępu. Tokeny odświeżania będą ważne do chwili unieważnienia dostępu przez użytkownika. To pole jest widoczne w tej odpowiedzi tylko wtedy, gdy w żądaniu wysłanym do serwera Google ustawiono parametr access_type na wartość offline.
scope Zakresy dostępu przydzielone przez access_token jako listę ciągów rozdzielanych spacjami (wielkość liter ma znaczenie).
token_type Typ zwróconego tokena. W tej chwili wartość w tym polu jest zawsze ustawiona na Bearer.

Przykładowy fragment odpowiedzi:

{
  "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

Użyj tokena dostępu, aby wywoływać interfejsy API Google, wykonując 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ć. Możesz utworzyć obiekt usługi, podając konstruktor autoryzowany Google\Client dla konstruktora interfejsu API, który chcesz wywoływać. Aby na przykład wywołać interfejs Drive API: 
    $drive = new Google\Service\Drive($client);
  3. wysyłać żądania do usługi API za pomocą interfejsu podanego 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, aplikacja będzie mogła go użyć do autoryzowania żą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 użyć tego obiektu do wykonywania autoryzowanych żądań do interfejsu API.

  1. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać. Obiekt usługi tworzysz przez wywołanie metody build biblioteki googleapiclient.discovery z nazwą i wersją interfejsu API oraz danymi logowania użytkownika: Na przykład do wywoływania wersji 2 interfejsu Drive API: 
    from googleapiclient.discovery import build

drive = build('drive', 'v2', credentials=credentials)
  2. wysyłać żądania do usługi API za pomocą interfejsu podanego 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

Za pomocą obiektu auth_client możesz wywoływać interfejsy API Google, 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: 
    drive = Google::Apis::DriveV2::DriveService.new
  2. Ustaw dane logowania w usłudze: 
    drive.authorization = auth_client
  3. wysyłać żądania do usługi API za pomocą interfejsu podanego przez obiekt usługi, Aby na przykład wyświetlić listę plików na Dysku Google uwierzytelnionego użytkownika: 
    files = drive.list_files

Autoryzacja można też przekazać w zależności od metody, 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 używać tego tokena do autoryzowania żądań do interfejsu API w imieniu danego konta użytkownika lub konta usługi. Utwórz obiekt usługi dla interfejsu API, który chcesz wywołać.

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

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

HTTP/REST

Gdy aplikacja otrzyma token dostępu, możesz go używać do wywoływania interfejsu API Google w imieniu danego konta użytkownika, jeśli zakresy dostępu wymagane przez ten interfejs API zostały przyznane. Aby to zrobić, dołącz do żądania do interfejsu API token dostępu, podając parametr zapytania access_token lub wartość nagłówka Authorization HTTP Bearer. W miarę możliwości preferowany jest nagłówek HTTP, ponieważ ciągi zapytania są zazwyczaj widoczne w dziennikach serwera. W większości przypadków biblioteki klienta możesz skonfigurować w wywołaniach interfejsów API Google (np. podczas wywoływania interfejsu Drive Files API).

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

Przykłady użycia HTTP GET

Wywołanie punktu końcowego drive.files (interfejs Drive Files API) z użyciem nagłówka HTTP Authorization: Bearer może wyglądać tak: 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 w przypadku uwierzytelnionego użytkownika za pomocą 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, który korzysta z opcji nagłówka HTTP (zalecane):

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

Możesz też użyć opcji parametru ciągu zapytania:

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

Pełny przykład

Poniższy przykład zawiera listę plików w formacie JSON na Dysku Google użytkownika po uwierzytelnieniu i uzyskaniu przez aplikację zgody na dostęp do metadanych użytkownika.

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 przejdź do niego. Przykład: 
    mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
  3. Zainstaluj bibliotekę klienta interfejsu API Google dla języka PHP za pomocą narzędzia Composer: 
    composer require google/apiclient:^2.10
  4. Utwórz pliki index.php i oauth2callback.php z zawartością widoczną poniżej.
  5. Uruchom przykład z serwerem WWW skonfigurowanym do obsługi języka PHP. Jeśli używasz PHP w wersji 5.6 lub nowszej, możesz uż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 używamy platformy Flask. Uruchamia aplikację internetową w http://localhost:8080, która umożliwia przetestowanie przepływu OAuth 2.0. Jeśli otworzysz ten adres URL, zobaczysz 4 linki:

  • Przetestuj żądanie do interfejsu API: ten link prowadzi do strony, która próbuje wykonać przykładowe żądanie do interfejsu API. W razie potrzeby rozpoczyna proces autoryzacji. Jeśli operacja się uda, na stronie wyświetli się odpowiedź interfejsu API.
  • Bezpośrednie testowanie 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 przyznane aplikacji przez użytkownika.
  • Wyczyść dane logowania do sesji Flask: ten link czyści dane uwierzytelniające, które są przechowywane w sesji Flask. Dzięki temu zobaczysz, co się stanie, jeśli użytkownik, który przyznał uprawnienia aplikacji, będzie próbował wykonać żądanie API w nowej sesji. Pozwala też wyświetlić odpowiedź interfejsu API otrzymaną, jeśli użytkownik unieważnił uprawnienia przyznane aplikacji, a aplikacja nadal próbowała autoryzować żądanie przy użyciu tokena unieważnionego dostępu.
# -*- coding: utf-8 -*-

import os
import flask
import requests

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

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

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

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


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


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

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

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

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

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

  return flask.jsonify(**files)


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

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

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

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

  return flask.redirect(authorization_url)


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

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

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

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

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


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

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

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

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


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


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

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


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

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

Ruby

W tym przykładzie używamy platformy Sinatra.

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

enable :sessions
set :session_secret, 'setme'

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

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

Node.js

Aby uruchomić ten przykład:

  1. W polu API Consoledodaj adres URL maszyny lokalnej do listy przekierowań. Na przykład dodaj http://localhost.
  2. Sprawdź, czy masz zainstalowany system LTS, aktywny LTS lub bieżącą wersję Node.js.
  3. Utwórz nowy katalog i przejdź do niego. 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 z podaną niżej treścią.
  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

W tym przykładzie w języku Python wykorzystano platformę Flask i bibliotekę Requests, aby pokazać przepływ użytkowników związany z protokołem OAuth 2.0. Dla tego procesu zalecamy używanie biblioteki klienta Google API dla Pythona. Przykład na karcie Pythona wykorzystuje bibliotekę 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 przekierowania

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

Reguły weryfikacji
Schemat

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

Hosty nie mogą być nieprzetworzonymi adresami IP. Adresy IP hosta lokalnego są wykluczone z tej reguły.
Domena
  • Domeny najwyższego poziomu (domeny najwyższego poziomu) muszą należeć do listy domen publicznych.
  • Domeny hosta nie mogą być “googleusercontent.com”.
  • Identyfikatory URI przekierowań nie mogą zawierać domen skracających adresy URL (np. goo.gl), chyba że aplikacja jest właścicielem domeny. Jeśli aplikacja, która jest skrócona, zdecyduje się przekierowywać do tej domeny, identyfikator URI przekierowania musi zawierać ścieżkę “/google-callback/” lub kończyć się ciągiem “/google-callback”.
    		•
    Informacje o użytkowniku

    Identyfikatory URI przekierowań nie mogą zawierać podskładnika użytkownika.
    Ścieżka

    Identyfikatory URI przekierowań nie mogą zawierać omijania ścieżki (znanej też jako śledzenie katalogu), która jest reprezentowana 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, w tym:
    • Symbole wieloznaczne ('*')
    • Znaki ASCII niedrukowalne
    • nieprawidłowe kodowanie procentowe (każdy procent kodowania niezgodny z kodem procentowym adresu URL po którym następuje 2 cyfry szesnastkowe)
    • Brak znaków (zakodowanego znaku NULL, np. %00, %C0%80)

    Autoryzacja przyrostowa

    W protokole OAuth 2.0 aplikacja prosi o autoryzację dostępu do zasobów zidentyfikowanych przez zakresy. Uznaje się, że najlepszym sposobem jest wysłanie prośby o autoryzację zasobów w odpowiednim momencie. Aby można było zastosować tę praktykę, serwer autoryzacji Google&.com obsługuje autoryzację przyrostową. Ta funkcja umożliwia żądanie zakresów, gdy jest to konieczne. Jeśli użytkownik przyzna uprawnienia dla nowego zakresu, zwróci kod autoryzacji, który można wymienić na token zawierający wszystkie zakresy przyznane przez użytkownika w projekcie.

    Na przykład aplikacja, która umożliwia użytkownikom próbkowanie utworów muzycznych i tworzenie miksów, może wymagać bardzo małej liczby zasobów. Zapisanie gotowej składanki wymaga jednak dostępu do Dysku Google. Większość osób uznałaby, że byłoby to naturalne w sytuacji, gdy prośba o dostęp do Dysku Google pojawiła się w chwili, gdy aplikacja jej potrzebowała.

    W takim przypadku aplikacja może poprosić o zakresy openid i profile, aby wykonać podstawowe logowanie, a następnie poprosić o zakres https://www.googleapis.com/auth/drive.file w chwili pierwszego żądania zapisania kombinacji.

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

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

    • Tokenu można użyć do uzyskania dostępu do zasobów powiązanych z dowolnym z zakresów wdrożonych w nowej, połączonej autoryzacji.
    • Jeśli używasz tokenu odświeżania dla 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 przez użytkownika do projektu API, nawet jeśli prośba została przyznana przez różnych klientów. Jeśli na przykład użytkownik przyznał dostęp do jednego zakresu za pomocą klienta na komputerze, a potem kolejnych uprawnień do tej samej aplikacji za pomocą klienta mobilnego, łączna autoryzacja będzie obejmować oba zakresy.
    • Jeśli unieważnisz token reprezentujący autoryzację autoryzacyjną, dostęp do wszystkich zakresów tej autoryzacji w imieniu powiązanego użytkownika zostanie unieważniony.

    Przykładowe kody w określonym języku na etapie Krok 1. Ustaw parametry autoryzacji i przykładowy adres URL przekierowania HTTP/REST na kroku 2 (przekierowanie do serwera Google OAuth 2.0) korzystają z autoryzacji przyrostowej. Przykładowy kod poniżej pokazuje kod, który musisz dodać, aby 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 zawiera wcześniej przyznane zakresy. Bardzo możliwe, że atrybut include_granted_scopes nie będzie jedynym ustawionym przez Ciebie słowem kluczowym, tak jak 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 danych logowania dla powiązanego żądania interfejsu API. Jeśli prośba o dostęp offline do zakresów powiązanych z tokenem została wysłana, możesz odświeżyć token dostępu bez pytania użytkownika o zgodę (w tym także wtedy, gdy nie ma go w sieci).

    • Jeśli używasz biblioteki klienta interfejsu API Google, obiekt klienta odświeża token dostępu zależnie od konfiguracji tego obiektu na potrzeby dostępu offline.
    • Jeśli nie korzystasz z biblioteki klienta, podczas przekierowania użytkownika na serwer OAuth 2.0 Google ustaw parametr zapytania HTTP access_type na offline. W takim przypadku serwer autoryzacyjny Google zwraca token odświeżania podczas wymieniania kodu autoryzacji na token dostępu. Jeśli token dostępu wygaśnie (lub w dowolnym innym momencie), możesz użyć nowego odświeżenia, aby uzyskać nowy token dostępu.

    Prośba o dostęp offline jest wymagana przez każdą aplikację, która nie ma dostępu do interfejsu API Google. Na przykład aplikacja, która wykonuje usługi kopii zapasowej lub wykonuje działania w określonych 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 po stronie serwera, zainstalowane aplikacje i urządzenia uzyskują tokeny odświeżania podczas autoryzacji. Tokeny odświeżania nie są zwykle używane w aplikacjach internetowych po stronie klienta (JavaScript).

    PHP

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

    $client->setAccessType("offline");

    Po przyznaniu użytkownikowi dostępu offline do żądanych zakresów możesz nadal korzystać z klienta API w celu uzyskania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu odpowiednio do potrzeb.

    Python

    W Pythonie ustaw argument słowa kluczowego access_type na offline, aby umożliwić odświeżenie tokena dostępu bez konieczności pytania użytkownika o pozwolenie. Jest bardzo możliwe, że access_type nie będzie jedynym ustawionym argumentem słowa kluczowego, jak w poniższym przykładzie.

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

    Po przyznaniu użytkownikowi dostępu offline do żądanych zakresów możesz nadal korzystać z klienta API w celu uzyskania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu odpowiednio do potrzeb.

    Ruby

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

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

    Po przyznaniu użytkownikowi dostępu offline do żądanych zakresów możesz nadal korzystać z klienta API w celu uzyskania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu odpowiednio do potrzeb.

    Node.js

    Jeśli aplikacja potrzebuje dostępu offline do interfejsu API Google, 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
});

    Po przyznaniu użytkownikowi dostępu offline do żądanych zakresów możesz nadal korzystać z klienta API w celu uzyskania dostępu do interfejsów API Google w imieniu użytkownika, gdy jest on offline. Obiekt klienta odświeży token dostępu odpowiednio do potrzeb.

    Tokeny dostępu wygasają. Ta biblioteka automatycznie użyje tokena odświeżania, aby uzyskać nowy token dostępu, który wkrótce straci ważność. Prostym sposobem, aby zawsze przechowywać najnowsze tokeny, jest użycie zdarzenia tokenów:

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

    Zdarzenie to jest rejestrowane tylko w pierwszej autoryzacji, więc przy wywołaniu metody generateAuthUrl musisz ustawić access_type na offline, aby otrzymać token odświeżania. Jeśli aplikacja ma już wymagane uprawnienia bez ustawiania odpowiednich ograniczeń dotyczących otrzymywania tokena odświeżania, musisz ponownie autoryzować aplikację, aby otrzymać nowy token odświeżania.

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

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

    Gdy klient otrzyma token odświeżania, tokeny dostępu zostaną uzyskane i odświeżone automatycznie podczas następnego wywołania interfejsu API.

    HTTP/REST

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

    Pola
    client_id Identyfikator klienta uzyskany z: API Console.
    client_secret Tajny klucz klienta uzyskany z klucza 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.

    Przykładowy fragment żądania:

    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

    O ile użytkownik nie unieważnił dostępu przyznanego aplikacji, serwer tokenów zwraca obiekt JSON zawierający nowy token dostępu. Przykładowy fragment odpowiedzi:

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

    Istnieją ograniczenia związane z liczbą tokenów odświeżania, z których jeden będzie połączony z każdym klientem. Zapisz tokeny odświeżania w długoterminowym miejscu i używaj ich, dopóki pozostaną ważne. Jeśli aplikacja zażąda zbyt wielu tokenów odświeżania, mogą przekroczyć te limity. W takim przypadku starsze tokeny odświeżania przestaną działać.

    Unieważnianie tokena

    W niektórych przypadkach użytkownik może chcieć anulować dostęp aplikacji. Użytkownik może anulować dostęp, otwierając Ustawienia konta. Więcej informacji znajdziesz w artykule Usuwanie dostępu witryn lub aplikacji do stron zewnętrznych.

    Aplikacja może również automatycznie anulować przyznany jej dostęp. Automatyczne unieważnienie jest ważne wtedy, gdy użytkownik anuluje subskrypcję, usunie aplikację lub zmienią się zasoby interfejsu API wymagane przez aplikację. Innymi słowy, część procesu usuwania może obejmować żądanie do interfejsu API służące do zapewnienia, że uprawnienia przyznane aplikacji wcześniej zostaną usunięte.

    PHP

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

    $client->revokeToken();

    Python

    Aby automatycznie unieważnić token, wyślij do https://oauth2.googleapis.com/revoke żądanie, które zawiera 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 dostępu jest przypisany do odpowiedniego tokena odświeżania, zostanie on też unieważniony.

    Jeśli odwołanie zostało przetworzone, kod stanu odpowiedzi to 200. W przypadku warunków błędu zwracany jest kod stanu 400 wraz z kodem błędu.

    Node.js

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

    const https = require('https');

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

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

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

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

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

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

    Jeśli odwołanie zostało przetworzone, kod stanu odpowiedzi to 200. W przypadku warunków błędu zwracany jest kod stanu 400 wraz z kodem błędu.

    HTTP/REST

    Aby automatycznie unieważnić token, aplikacja wysyła żądanie do https://oauth2.googleapis.com/revoke i umieszcza 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 dostępu jest przypisany do odpowiedniego tokena odświeżania, zostanie on też unieważniony.

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