Использование OAuth 2.0 для приложений веб-сервера

В этом документе объясняется, как веб-серверные приложения используют клиентские библиотеки Google API или конечные точки Google OAuth 2.0 для реализации авторизации OAuth 2.0 для доступа к API Google.

OAuth 2.0 позволяет пользователям обмениваться определенными данными с приложением, сохраняя при этом конфиденциальность своих имен пользователей, паролей и другой информации. Например, приложение может использовать OAuth 2.0 для получения разрешения от пользователей на хранение файлов в их Google Дисках.

Данный алгоритм OAuth 2.0 предназначен специально для авторизации пользователей. Он разработан для приложений, которые могут хранить конфиденциальную информацию и поддерживать состояние. Правильно авторизованное веб-приложение может получить доступ к API как во время взаимодействия пользователя с приложением, так и после того, как пользователь покинул приложение.

Приложения веб-серверов часто также используют служебные учетные записи для авторизации запросов API, особенно при вызове облачных API для доступа к данным, относящимся к проекту, а не к данным конкретного пользователя. Приложения веб-серверов могут использовать служебные учетные записи в сочетании с авторизацией пользователей.

Примечание: Учитывая риски для безопасности, связанные с правильной реализацией, мы настоятельно рекомендуем использовать библиотеки OAuth 2.0 при взаимодействии с конечными точками Google OAuth 2.0. Использование хорошо отлаженного кода, предоставленного другими разработчиками, является лучшей практикой и поможет защитить вас и ваших пользователей. Для получения дополнительной информации см. раздел «Клиентские библиотеки» .

Клиентские библиотеки

В примерах на этой странице, адаптированных под конкретные языки программирования, используются клиентские библиотеки Google API для реализации авторизации OAuth 2.0. Для запуска примеров кода необходимо предварительно установить клиентскую библиотеку для вашего языка.

При использовании клиентской библиотеки Google API для обработки потока OAuth 2.0 в вашем приложении, библиотека выполняет множество действий, которые в противном случае приложению пришлось бы обрабатывать самостоятельно. Например, она определяет, когда приложение может использовать или обновлять сохраненные токены доступа, а также когда приложению необходимо повторно получить согласие. Клиентская библиотека также генерирует корректные URL-адреса перенаправления и помогает реализовать обработчики перенаправлений, которые обменивают коды авторизации на токены доступа.

Клиентские библиотеки Google API для серверных приложений доступны для следующих языков:

• Go
• Java
• .NET
• Node.js
• Dart
• PHP
• Python
• Ruby

Важно: клиентская библиотека Google API для JavaScript и функция «Вход через Google» предназначены только для обработки OAuth 2.0 в браузере пользователя. Если вы хотите использовать JavaScript на стороне сервера для управления взаимодействием с Google по протоколу OAuth 2.0, рассмотрите возможность использования библиотеки Node.js на вашей серверной платформе.

Предварительные требования

Включите API для вашего проекта

Любое приложение, использующее API Google, должно включить эти API в консоли API.

Чтобы включить API для вашего проекта:

1. Откройте библиотеку API в консоли Google API.
2. При появлении запроса выберите проект или создайте новый.
3. В библиотеке API перечислены все доступные API, сгруппированные по семействам продуктов и популярности. Если нужный вам API отсутствует в списке, воспользуйтесь поиском, чтобы найти его, или нажмите «Показать все» в семействе продуктов, к которому он относится.
4. Выберите API, который хотите включить, затем нажмите кнопку «Включить» .
5. При появлении запроса включите оплату.
6. При появлении запроса ознакомьтесь с условиями использования API и примите их.

Создать учетные данные авторизации

Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные авторизации, идентифицирующие приложение для сервера OAuth 2.0 Google. Следующие шаги описывают, как создать учетные данные для вашего проекта. Затем ваши приложения смогут использовать эти учетные данные для доступа к API, которые вы включили для этого проекта.

1. Перейдите на страницу «Клиенты» .
2. Нажмите «Создать клиента» .
3. Выберите тип приложения: Веб-приложение .
4. Заполните форму и нажмите «Создать» . Приложения, использующие языки и фреймворки, такие как PHP, Java, Python, Ruby и .NET, должны указывать авторизованные URI перенаправления . URI перенаправления — это конечные точки, на которые сервер OAuth 2.0 может отправлять ответы. Эти конечные точки должны соответствовать правилам проверки Google .

   Для тестирования можно указать URI, которые ссылаются на локальный компьютер, например, http://localhost:8080 . Во всех примерах в этом документе в качестве URI перенаправления используется http://localhost:8080 .

   Мы рекомендуем проектировать конечные точки аутентификации вашего приложения таким образом, чтобы оно не передавало коды авторизации другим ресурсам на странице.

После создания учетных данных загрузите файл client_secret.json из консоли API. Надежно сохраните файл в месте, доступном только вашему приложению.

Важно: не храните файл client_secret.json в общедоступном месте. Кроме того, если вы делитесь исходным кодом своего приложения — например, на GitHub — храните файл client_secret.json вне дерева исходного кода, чтобы избежать непреднамеренной передачи учетных данных клиента.

Секретный ключ клиента вашего приложения отобразится только после его создания. Вы не сможете просмотреть или загрузить секретный ключ клиента повторно. Подробнее .

Определите области доступа

Области доступа (scopes) позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также дают пользователям возможность контролировать объем предоставляемого ими доступа. Таким образом, может существовать обратная зависимость между количеством запрашиваемых областей доступа и вероятностью получения согласия пользователя.

Прежде чем приступать к внедрению авторизации OAuth 2.0, мы рекомендуем определить области доступа, к которым вашему приложению потребуются разрешения.

Мы также рекомендуем, чтобы ваше приложение запрашивало доступ к областям авторизации посредством поэтапного процесса авторизации , в рамках которого приложение запрашивает доступ к пользовательским данным в контексте. Эта передовая практика помогает пользователям легче понять, зачем вашему приложению нужен запрашиваемый доступ.

В документе «Области действия API OAuth 2.0» содержится полный список областей действия, которые вы можете использовать для доступа к API Google.

Если ваше общедоступное приложение использует области доступа, разрешающие доступ к определенным пользовательским данным, оно должно пройти процесс проверки. Если при тестировании приложения вы видите на экране сообщение «Непроверенное приложение» , необходимо отправить запрос на проверку, чтобы удалить его. Подробнее о непроверенных приложениях и ответы на часто задаваемые вопросы о проверке приложений вы найдете в Справочном центре.

Требования, специфичные для конкретного языка

Для запуска любого из примеров кода в этом документе вам потребуется учетная запись Google, доступ к Интернету и веб-браузер. Если вы используете одну из клиентских библиотек API, ознакомьтесь с требованиями для конкретного языка программирования:

PHP

Для запуска примеров PHP-кода, приведенных в этом документе, вам потребуется:

• PHP 8.0 или более поздней версии с установленным интерфейсом командной строки (CLI) и расширением JSON.
• Инструмент управления зависимостями Composer .

• Клиентская библиотека Google API для PHP:

  composer require google/apiclient:^2.15.0

Дополнительную информацию см. в клиентской библиотеке Google API для PHP .

Python

Для запуска примеров кода на Python, приведенных в этом документе, вам потребуется:

• Python 3.7 или выше
• Инструмент управления пакетами pip .
• Выпуск клиентской библиотеки Google API для Python 2.0:

  pip install --upgrade google-api-python-client

• Для авторизации пользователей используются библиотеки google-auth , google-auth-oauthlib и google-auth-httplib2 .

  pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

• Фреймворк Flask для веб-приложений на Python.

  pip install --upgrade flask

• Библиотека HTTP requests .

  pip install --upgrade requests

Если вы не можете обновить Python и соответствующее руководство по миграции, ознакомьтесь с примечаниями к выпуску клиентской библиотеки Google API для Python.

Руби

Для запуска примеров кода на Ruby, представленных в этом документе, вам потребуется:

• Ruby 2.6 или выше

• Библиотека аутентификации Google для Ruby:

  gem install googleauth

• Клиентские библиотеки для API Google Диска и Календаря:

  gem install google-apis-drive_v3 google-apis-calendar_v3

• Веб-фреймворк Sinatra Ruby.

  gem install sinatra

Node.js

Для запуска примеров кода Node.js, приведенных в этом документе, вам потребуется:

• Обновленная версия Node.js с поддержкой LTS, активная версия LTS или текущая версия.

• Клиент Google API на Node.js:

  npm install googleapis crypto express express-session

HTTP/REST

Для прямого вызова конечных точек OAuth 2.0 не требуется устанавливать какие-либо библиотеки.

Получение токенов доступа OAuth 2.0

Следующие шаги показывают, как ваше приложение взаимодействует с сервером Google OAuth 2.0 для получения согласия пользователя на выполнение запроса к API от его имени. Ваше приложение должно получить это согласие, прежде чем оно сможет выполнить запрос к API Google, требующий авторизации пользователя.

В этом списке кратко изложены следующие шаги:

1. Ваше приложение определяет необходимые ему разрешения.
2. Ваше приложение перенаправляет пользователя на сайт Google вместе со списком запрошенных разрешений.
3. Пользователь сам решает, предоставлять ли вашему приложению необходимые разрешения.
4. Ваше приложение выясняет, какое решение принял пользователь.
5. Если пользователь предоставил запрошенные разрешения, ваше приложение получит токены, необходимые для выполнения API-запросов от имени пользователя.

Шаг 1: Настройка параметров авторизации

Первым шагом является создание запроса на авторизацию. Этот запрос устанавливает параметры, которые идентифицируют ваше приложение и определяют разрешения, которые пользователю будет предложено предоставить вашему приложению.

• Если вы используете клиентскую библиотеку Google для аутентификации и авторизации OAuth 2.0, вам необходимо создать и настроить объект, определяющий эти параметры.
• Если вы напрямую обратитесь к конечной точке Google OAuth 2.0, вы сгенерируете URL-адрес и зададите параметры для этого URL-адреса.

На этих вкладках определены поддерживаемые параметры авторизации для веб-серверных приложений; примеры для конкретных языков также показывают, как использовать клиентскую библиотеку или библиотеку авторизации для настройки объекта, который задает эти параметры:

PHP

Приведённый ниже фрагмент кода создаёт объект Google\Client() , который определяет параметры в запросе авторизации.

Этот объект использует информацию из файла client_secret.json для идентификации вашего приложения. (Подробнее об этом файле см. в разделе «Создание учетных данных для авторизации» .) Объект также определяет области доступа, к которым ваше приложение запрашивает разрешение, и URL-адрес конечной точки аутентификации вашего приложения, которая будет обрабатывать ответ от сервера OAuth 2.0 от Google. Наконец, код устанавливает необязательные параметры access_type и include_granted_scopes .

Например, этот код запрашивает доступ только для чтения в автономном режиме к метаданным и событиям календаря пользователя в Google Диск:

use Google\Client;

$client = new Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfig('client_secret.json');

// Required, to set the scope value, call the addScope function
$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

// Required, call the setRedirectUri function to specify a valid redirect URI for the
// provided client_id
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');

// Recommended, 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');

// Recommended, call the setState function. Using a state value can increase your assurance that
// an incoming connection is the result of an authentication request.
$client->setState($sample_passthrough_value);

// Optional, if your application knows which user is trying to authenticate, it can use this
// parameter to provide a hint to the Google Authentication Server.
$client->setLoginHint('[e-mail]');

// Optional, call the setPrompt function to set "consent" will prompt the user for consent
$client->setPrompt('consent');

// Optional, call the setIncludeGrantedScopes function with true to enable incremental
// authorization
$client->setIncludeGrantedScopes(true);

Python

Приведённый ниже фрагмент кода использует модуль google-auth-oauthlib.flow для формирования запроса на авторизацию.

Код создает объект Flow , который идентифицирует ваше приложение, используя информацию из файла client_secret.json , который вы загрузили после создания учетных данных авторизации . Этот объект также определяет области доступа, к которым ваше приложение запрашивает разрешение, и URL-адрес конечной точки аутентификации вашего приложения, которая будет обрабатывать ответ от сервера Google OAuth 2.0. Наконец, код устанавливает необязательные параметры access_type и include_granted_scopes .

Например, этот код запрашивает доступ только для чтения в автономном режиме к метаданным и событиям календаря пользователя в Google Диск:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Required, call the from_client_secrets_file method to retrieve the client ID from a
# client_secret.json file. The client ID (from that file) and access scopes are required. (You can
# also use the from_client_config method, which passes the client configuration as it originally
# appeared in a client secrets file but doesn't access the file itself.)
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly',
            'https://www.googleapis.com/auth/calendar.readonly'])

# Required, 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(
    # Recommended, 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',
    # Optional, enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true',
    # Optional, if your application knows which user is trying to authenticate, it can use this
    # parameter to provide a hint to the Google Authentication Server.
    login_hint='[e-mail]',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Руби

Используйте созданный вами файл client_secrets.json для настройки объекта клиента в вашем приложении. При настройке объекта клиента вы указываете области действия, к которым должно иметь доступ ваше приложение, а также URL-адрес конечной точки аутентификации вашего приложения, которая будет обрабатывать ответ от сервера OAuth 2.0.

Например, этот код запрашивает доступ только для чтения в автономном режиме к метаданным и событиям календаря пользователя в Google Диск:

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/drive_v3'
require 'google/apis/calendar_v3'

# Required, call the from_file method to retrieve the client ID from a
# client_secret.json file.
client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')

# Required, scope value 
# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
         'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

# Required, Authorizers require a storage instance to manage long term persistence of
# access and refresh tokens.
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

# Required, 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.
callback_uri = '/oauth2callback'

# 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.
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope,
                                                token_store, callback_uri)

Ваше приложение использует объект клиента для выполнения операций OAuth 2.0, таких как генерация URL-адресов запросов авторизации и применение токенов доступа к HTTP-запросам.

Node.js

Приведенный ниже фрагмент кода создает объект google.auth.OAuth2 , который определяет параметры в запросе авторизации.

Этот объект использует информацию из файла client_secret.json для идентификации вашего приложения. Чтобы запросить у пользователя разрешение на получение токена доступа, вы перенаправляете его на страницу согласия. Чтобы создать URL-адрес страницы согласия:

const {google} = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a secure random state value.
const state = crypto.randomBytes(32).toString('hex');

// Store state in the session
req.session.state = state;

// Generate a url that asks permissions for the Drive activity and Google Calendar 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,
  // Include the state parameter to reduce the risk of CSRF attacks.
  state: state
});

Важное примечание : refresh_token возвращается только при первой авторизации. Подробнее здесь .

HTTP/REST

Конечная точка OAuth 2.0 от Google находится по адресу https://accounts.google.com/o/oauth2/v2/auth . Доступ к этой конечной точке возможен только по протоколу HTTPS. Простые HTTP-соединения отклоняются.

Сервер авторизации Google поддерживает следующие параметры строки запроса для веб-приложений:

Параметры
client_id	Необходимый Идентификатор клиента для вашего приложения. Это значение можно найти на странице «Клиенты» в консоли Cloud.
redirect_uri	Необходимый Определяет, куда API-сервер перенаправляет пользователя после завершения авторизации. Значение должно точно совпадать с одним из разрешенных URI перенаправления для клиента OAuth 2.0, который вы настроили на странице «Клиенты » в Cloud Console. Если это значение не совпадает с разрешенным URI перенаправления для указанного client_id вы получите ошибку redirect_uri_mismatch . Обратите внимание, что схема http или https , регистр и завершающая косая черта (' / ') должны совпадать.
response_type	Необходимый Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации. Установите значение параметра равным " code для приложений веб-сервера.
scope	Необходимый Разделённый пробелами список областей действия, определяющих ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения используются для формирования экрана согласия, который Google отображает пользователю. Области доступа (scopes) позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также дают пользователям возможность контролировать объем предоставляемого ими доступа. Таким образом, существует обратная зависимость между количеством запрашиваемых областей доступа и вероятностью получения согласия пользователя. Мы рекомендуем, чтобы ваше приложение запрашивало доступ к областям авторизации в контексте, когда это возможно. Запрашивая доступ к пользовательским данным в контексте, используя поэтапную авторизацию , вы помогаете пользователям понять, зачем вашему приложению нужен запрашиваемый доступ.
access_type	Рекомендуется Указывает, может ли ваше приложение обновлять токены доступа, когда пользователь отсутствует в браузере. Допустимые значения параметра: online (значение по умолчанию) и offline . Установите значение offline , если вашему приложению необходимо обновлять токены доступа, когда пользователь отсутствует в браузере. Это способ обновления токенов доступа, описанный далее в этом документе. Это значение указывает серверу авторизации Google возвращать токен обновления и токен доступа при первом обмене кодом авторизации на токены вашим приложением.
state	Рекомендуется Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом на авторизацию и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары name=value в компоненте запроса URL ( ? ) параметра redirect_uri после того, как пользователь дает согласие или отклоняет запрос на доступ вашего приложения. Этот параметр можно использовать для различных целей, например, для перенаправления пользователя на правильный ресурс в вашем приложении, отправки одноразовых чисел (nonce) и предотвращения подделки межсайтовых запросов (CSS). Поскольку ваш redirect_uri может быть угадан, использование значения state может повысить вашу уверенность в том, что входящее соединение является результатом запроса аутентификации. Если вы сгенерируете случайную строку или закодируете хеш cookie или другое значение, которое отражает состояние клиента, вы можете проверить ответ, чтобы дополнительно убедиться, что запрос и ответ были отправлены из одного и того же браузера, обеспечивая защиту от таких атак, как подделка межсайтовых запросов . Пример создания и подтверждения токена state см. в документации OpenID Connect. Важно: клиент OAuth должен предотвращать CSRF-атаки, как указано в спецификации OAuth2 . Один из способов добиться этого — использовать параметр state для поддержания состояния между вашим запросом на авторизацию и ответом сервера авторизации.
include_granted_scopes	Необязательный Позволяет приложениям использовать поэтапную авторизацию для запроса доступа к дополнительным областям действия в контексте. Если вы установите значение этого параметра равным true и запрос на авторизацию будет одобрен, то новый токен доступа будет также охватывать любые области действия, к которым пользователь ранее предоставил приложению доступ. Примеры см. в разделе « Поэтапная авторизация» .
enable_granular_consent	Необязательный По умолчанию — true . Если установлено значение false , более детальные разрешения учетной записи Google будут отключены для идентификаторов клиентов OAuth, созданных до 2019 года. Для более новых идентификаторов клиентов OAuth это не имеет значения, поскольку для них более детальные разрешения всегда включены. Когда Google включит детализированные разрешения для приложения, этот параметр перестанет оказывать какое-либо воздействие.
login_hint	Необязательный Если ваше приложение знает, какой пользователь пытается пройти аутентификацию, оно может использовать этот параметр для предоставления подсказки серверу аутентификации Google. Сервер использует эту подсказку для упрощения процесса входа в систему, либо предварительно заполняя поле электронной почты в форме входа, либо выбирая соответствующую сессию с несколькими учетными записями. Установите значение параметра равным адресу электронной почты или sub , эквивалентному идентификатору пользователя в Google.
prompt	Необязательный Список вопросов, разделенных пробелами и учитывающих регистр, для отображения пользователю. Если этот параметр не указан, пользователю будет предложено подтвердить согласие только при первом запросе доступа к вашему проекту. Дополнительную информацию см. в разделе «Предварительное подтверждение согласия» . Возможные значения: none Не отображать экраны аутентификации или согласия. Не должно указываться с другими значениями. consent Запросите у пользователя согласие. select_account Предложите пользователю выбрать учетную запись.

Шаг 2: Перенаправление на сервер Google OAuth 2.0

Перенаправьте пользователя на сервер Google OAuth 2.0 для запуска процесса аутентификации и авторизации. Обычно это происходит, когда вашему приложению впервые требуется доступ к данным пользователя. В случае поэтапной авторизации этот шаг также происходит, когда вашему приложению впервые требуется доступ к дополнительным ресурсам, к которым у него нет разрешения.

PHP

1. Сгенерируйте URL-адрес для запроса доступа к серверу Google OAuth 2.0:

   $auth_url = $client->createAuthUrl();

2. Перенаправить пользователя на $auth_url :

   header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

В этом примере показано, как перенаправить пользователя на URL-адрес авторизации с помощью веб-фреймворка Flask:

return flask.redirect(authorization_url)

Руби

1. Сгенерируйте URL-адрес для запроса доступа к серверу Google OAuth 2.0:

   auth_uri = authorizer.get_authorization_url(request: request)

2. Перенаправьте пользователя на auth_uri .

Node.js

1. Используйте сгенерированный URL-адрес authorizationUrl из шага 1 , полученный с помощью метода generateAuthUrl , для запроса доступа к серверу OAuth 2.0 от Google.
2. Перенаправьте пользователя на authorizationUrl .

   res.redirect(authorizationUrl);

HTTP/REST

Пример перенаправления на сервер авторизации Google.

Пример URL-адреса показан ниже, с переносами строк и пробелами для удобства чтения.

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

После создания URL-адреса запроса перенаправьте пользователя на него.

Сервер OAuth 2.0 от Google аутентифицирует пользователя и получает от него согласие на доступ вашего приложения к запрошенным областям действия. Ответ отправляется обратно в ваше приложение с использованием указанного вами URL-адреса перенаправления.

Шаг 3: Google запрашивает у пользователя согласие.

На этом этапе пользователь решает, предоставлять ли вашему приложению запрошенный доступ. На этом этапе Google отображает окно согласия, в котором указывается название вашего приложения и сервисы Google API, к которым запрашивается разрешение на доступ, а также учетные данные пользователя и краткое описание предоставляемых областей доступа. Затем пользователь может дать согласие на предоставление доступа к одной или нескольким областям, запрошенным вашим приложением, или отклонить запрос.

На данном этапе вашему приложению не нужно ничего делать, поскольку оно ожидает ответа от сервера OAuth 2.0 от Google, указывающего, был ли предоставлен доступ. Этот ответ объясняется на следующем шаге.

Ошибки

При обращении к конечной точке авторизации OAuth 2.0 от Google вместо ожидаемых процессов аутентификации и авторизации могут отображаться сообщения об ошибках, предназначенные для пользователя. Распространенные коды ошибок и рекомендуемые способы их устранения:

admin_policy_enforced

Учетная запись Google не может авторизовать одну или несколько запрошенных областей доступа из-за политики администратора Google Workspace. Дополнительную информацию о том, как администратор может ограничить доступ ко всем областям доступа или к конфиденциальным и ограниченным областям доступа до тех пор, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth, см. в справочной статье «Управление доступом сторонних и внутренних приложений к данным Google Workspace» .

disallowed_useragent

Точка авторизации отображается внутри встроенного пользовательского агента, что запрещено политикой Google OAuth 2.0 .

Разработчики iOS и macOS могут столкнуться с этой ошибкой при открытии запросов авторизации в WKWebView . Вместо этого разработчикам следует использовать библиотеки iOS, такие как Google Sign-In для iOS или AppAuth для iOS от OpenID Foundation.

Веб-разработчики могут столкнуться с этой ошибкой, когда приложение для iOS или macOS открывает обычную веб-ссылку во встроенном пользовательском агенте, и пользователь переходит на конечную точку авторизации Google OAuth 2.0 с вашего сайта. Разработчикам следует разрешить открытие обычных ссылок в обработчике ссылок по умолчанию операционной системы, включая обработчики универсальных ссылок или обработчики ссылок браузера по умолчанию. Библиотека SFSafariViewController также является поддерживаемым вариантом.

org_internal

Идентификатор клиента OAuth в запросе является частью проекта, ограничивающего доступ к учетным записям Google в конкретной организации Google Cloud . Для получения дополнительной информации об этом параметре конфигурации см. раздел «Тип пользователя» в справочной статье «Настройка экрана согласия OAuth».

invalid_client

Указан неверный секретный ключ клиента OAuth. Проверьте конфигурацию клиента OAuth , включая идентификатор клиента и секретный ключ, использованные для этого запроса.

deleted_client

Клиент OAuth, использованный для отправки запроса, был удален. Удаление может произойти вручную или автоматически в случае неиспользуемых клиентов . Удаленные клиенты могут быть восстановлены в течение 30 дней с момента удаления. Подробнее .

invalid_grant

При обновлении токена доступа или использовании инкрементальной авторизации срок действия токена может истечь или он может быть аннулирован. Повторно аутентифицируйте пользователя и запросите у него согласие на получение новых токенов. Если ошибка повторяется, убедитесь, что ваше приложение настроено правильно и что вы используете корректные токены и параметры в запросе. В противном случае учетная запись пользователя может быть удалена или отключена.

redirect_uri_mismatch

Передаваемый в запросе авторизации параметр redirect_uri не соответствует разрешенному URI перенаправления для идентификатора клиента OAuth. Проверьте разрешенные URI перенаправления на странице «Клиенты» в консоли Google Cloud.

Параметр redirect_uri может указывать на устаревший и больше не поддерживаемый поток OAuth out-of-band (OOB). Для обновления интеграции обратитесь к руководству по миграции .

invalid_request

В вашем запросе произошла ошибка. Причиной может быть ряд причин:

• Запрос был оформлен неправильно.
• В запросе отсутствовали необходимые параметры.
• В запросе используется метод авторизации, который Google не поддерживает. Убедитесь, что ваша интеграция OAuth использует рекомендуемый метод интеграции.

Шаг 4: Обработка ответа сервера OAuth 2.0

Важно: Перед обработкой ответа OAuth 2.0 на сервере необходимо убедиться, что state , полученное от Google, совпадает с state , отправленным в запросе авторизации. Эта проверка помогает гарантировать, что запрос отправляет пользователь, а не вредоносный скрипт, и снижает риск CSRF-атак .

Сервер OAuth 2.0 отвечает на запрос доступа вашего приложения, используя URL-адрес, указанный в запросе.

Если пользователь одобряет запрос на доступ, то в ответе содержится код авторизации. Если пользователь не одобряет запрос, в ответе содержится сообщение об ошибке. Код авторизации или сообщение об ошибке, возвращаемое веб-серверу, отображается в строке запроса:

Сообщение об ошибке:

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

Ответ с кодом авторизации:

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

Важно: если ваш конечный пункт ответа отображает HTML-страницу, любые ресурсы на этой странице смогут увидеть код авторизации в URL-адресе. Скрипты могут считывать URL-адрес напрямую, и URL-адрес из HTTP-заголовка Referer может быть отправлен любому или всем ресурсам на странице.

Тщательно обдумайте, хотите ли вы отправлять учетные данные авторизации всем ресурсам на этой странице (особенно сторонним скриптам, таким как плагины социальных сетей и аналитические инструменты). Чтобы избежать этой проблемы, мы рекомендуем серверу сначала обработать запрос, а затем перенаправить на другой URL-адрес, который не содержит параметров ответа.

Пример ответа сервера OAuth 2.0

Вы можете протестировать этот процесс, перейдя по следующей ссылке, которая запрашивает доступ только для чтения к просмотру метаданных файлов в вашем Google Диске и доступ только для чтения к просмотру событий вашего Календаря Google:

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

После завершения процесса OAuth 2.0 ваш браузер перенаправит вас на OAuth 2.0 Playground — инструмент для тестирования процессов OAuth. Вы увидите, что OAuth 2.0 Playground автоматически получил код авторизации.

Шаг 5: Обменяйте код авторизации на токены обновления и доступа.

После получения кода авторизации веб-сервер может обменять этот код на токен доступа.

PHP

Для обмена кода авторизации на токен доступа используйте метод fetchAccessTokenWithAuthCode :

$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

Python

На странице обратного вызова используйте библиотеку google-auth для проверки ответа сервера авторизации. Затем используйте метод flow.fetch_token для обмена кода авторизации из этого ответа на токен доступа:

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 browser session storage, but for security: client_id, client_secret,
# and token_uri are instead stored only on the backend server.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'granted_scopes': credentials.granted_scopes}

Руби

На странице обратного вызова используйте библиотеку googleauth для проверки ответа сервера авторизации. Используйте метод authorizer.handle_auth_callback_deferred , чтобы сохранить код авторизации и перенаправить пользователя обратно на URL-адрес, который изначально запрашивал авторизацию. Это откладывает обмен кодом, временно сохраняя результаты в сессии пользователя.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

Для обмена кода авторизации на токен доступа используйте метод getToken :

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
app.get('/oauth2callback', async (req, res) => {
  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 if (q.state !== req.session.state) { //check state value
    console.log('State mismatch. Possible CSRF attack');
    res.end('State mismatch. Possible CSRF attack');
  } else { // Get access and refresh tokens (if access_type is offline)

    let { tokens } = await oauth2Client.getToken(q.code);
    oauth2Client.setCredentials(tokens);
});

HTTP/REST

Для обмена кода авторизации на токен доступа вызовите конечную точку https://oauth2.googleapis.com/token и установите следующие параметры:

Поля
client_id	Идентификатор клиента, полученный на странице «Клиенты» в облачной консоли.
client_secret	Необязательный Секретный ключ клиента, полученный на странице «Клиенты» в облачной консоли.
code	Код авторизации, полученный в результате первоначального запроса.
grant_type	В соответствии со спецификацией OAuth 2.0 , значение этого поля должно быть установлено на authorization_code .
redirect_uri	Один из URI перенаправления, указанных для вашего проекта на странице «Клиенты» в Cloud Console для заданного client_id .

Хотя использование DPoP необязательно, оно рекомендуется для повышения безопасности. Безопасность DPoP основана на том, что закрытый ключ хранится только на одном устройстве; мы рекомендуем хранить его таким образом, чтобы его нельзя было скопировать за пределы устройства, например, с помощью TPM, защищенных анклавов или других аппаратных хранилищ ключей. Для использования DPoP ваше приложение должно генерировать новый, уникальный JWT-токен подтверждения DPoP для каждого запроса к конечной точке токена и добавлять его в заголовок HTTP-запроса.

Заголовок	Необходимый	Описание
DPoP	Необязательный	Доказательство DPoP — это JWT, подтверждающее владение закрытым ключом. Это заголовок, а не параметр. Если он предоставлен, возвращаемые токены привязываются к этому ключу. Для каждого запроса необходимо генерировать новое уникальное доказательство, которое должно включать утверждения htm (метод HTTP) и htu (URI HTTP), соответствующие запросу.

Следующий фрагмент кода демонстрирует пример запроса:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=https%3A//developers.google.com/oauthplayground&
grant_type=authorization_code

Создайте доказательство DPoP.

Следующие шаги показывают, как создать доказательство DPoP с помощью OpenSSL из командной строки:

1. Сгенерируйте пару ключей EC P-256:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. Создайте заголовок DPoP:

   Заголовок должен содержать утверждения typ , alg и jwk (открытый ключ). Значения x и y — это закодированные в Base64Url координаты вашего открытого ключа EC. Закодируйте этот JSON в Base64Url:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. Создайте полезную нагрузку DPoP:

   Полезная нагрузка должна включать jti (уникальный идентификатор запроса), htm (метод HTTP, например, POST ), htu (URI HTTP, например, https://oauth2.googleapis.com/token ) и iat (дата выдачи). Если вы получили nonce от сервера в заголовке DPoP-Nonce в ответе на предыдущий запрос, вы должны включить это значение nonce в утверждение nonce . Утверждение nonce является необязательным для обмена кодами авторизации и используется только в том случае, если заголовок DPoP-Nonce был получен ранее. Закодируйте этот JSON в Base64Url:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   Значение jti зависит от типа обмена:

   • Для обмена кодами авторизации jti должен представлять собой закодированный в Base64Url хеш SHA256 кода авторизации: "jti":" BASE64URL(SHA256(AUTHORIZATION_CODE)) " .
   • Для обмена токенов обновления jti должен быть уникальным идентификатором для каждого запроса: "jti":" YOUR_UNIQUE_PER_REQUEST_IDENTIFIER " .
4. Подпишите подтверждение:

   Объедините закодированный заголовок и полезную нагрузку точкой ( . ), затем подпишите результат своим закрытым ключом, используя ES256. Обратите внимание, что JWS требует, чтобы подпись была в необработанном формате R | S (64 байта для P-256). При использовании OpenSSL напрямую необходимо преобразовать стандартную подпись в формате ASN.1 DER в этот необработанный формат.

Успешный обмен подтверждается ответом 200 OK содержащим токены. Если во время обмена используется действительное подтверждение DPoP, токен обновления, возвращаемый Google, будет привязан к вашему ключу через DPoP, но токены доступа не будут привязаны к DPoP. Токены доступа сохранят token_type Bearer , а не DPoP . Кроме того, Google возвращает HTTP-заголовок DPoP-Nonce в ответе. Ваш клиент должен кэшировать этот nonce и включать его в утверждение nonce подтверждения DPoP в последующих запросах (например, при обмене токена обновления на новый токен доступа или при вызове API, защищенных DPoP). Используя этот заранее выданный nonce, вы можете избежать дополнительной ошибки при повторном обращении ( use_dpop_nonce ) в следующем запросе.

Для запросов на обмен токенов, выполняемых с использованием токенов обновления, привязанных к DPoP, необходимо приложить подтверждение DPoP.

Неудачный обмен происходит, если заголовок DPoP отсутствует, когда ожидалось, является недействительным, или если в подтверждении используется другой ключ, отличный от того, который привязан к токену. В этих случаях сервер возвращает ошибку 400 Bad Request . Если в подтверждении DPoP содержатся несовпадающие утверждения htm или htu , истек срок действия iat , повторно используется jti или подпись недействительна, Google возвращает код ошибки invalid_dpop_proof . Если требуется nonce для DPoP, например, при обмене токенов обновления, и в подтверждении DPoP отсутствует утверждение nonce , или значение nonce неприемлемо для сервера (например, оно истекло, уже использовалось или неверно), Google возвращает код ошибки use_dpop_nonce вместе с HTTP-заголовком DPoP-Nonce содержащим новый nonce, который можно использовать в последующем запросе. Другие сбои могут возвращать invalid_grant .

В ответ на этот запрос Google возвращает JSON-объект, содержащий кратковременный токен доступа и токен обновления. Обратите внимание, что токен обновления возвращается только в том случае, если ваше приложение установило параметр access_type в offline в первоначальном запросе к серверу авторизации Google .

Ответ содержит следующие поля:

Поля
access_token	Токен, который ваше приложение отправляет для авторизации запроса к API Google.
expires_in	Оставшийся срок действия токена доступа в секундах.
refresh_token	Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны до тех пор, пока пользователь не отзовет доступ или пока срок действия токена обновления не истечет. Если использовался DPoP, токен обновления привязан к закрытому ключу, использованному для подписи подтверждения DPoP. Еще раз подчеркнем, что это поле присутствует в этом ответе только в том случае, если вы установили параметр access_type в offline в первоначальном запросе к серверу авторизации Google.
refresh_token_expires_in	Оставшийся срок действия токена обновления в секундах. Это значение устанавливается только в том случае, если пользователь предоставляет доступ по времени .
scope	Области доступа, предоставляемые access_token выражены в виде списка строк, разделенных пробелами и чувствительных к регистру.
token_type	Тип возвращаемого токена. Это значение всегда Bearer , даже при использовании DPoP.

Важно: Ваше приложение должно хранить оба токена в безопасном, долговременном месте, доступном между различными запусками приложения. Токен обновления позволяет вашему приложению получить новый токен доступа, если срок действия имеющегося у вас токена истечет. Таким образом, если ваше приложение потеряет токен обновления, пользователю потребуется повторить процедуру согласия OAuth 2.0, чтобы ваше приложение могло получить новый токен обновления.

Следующий фрагмент кода демонстрирует пример заголовков и тела успешного ответа при использовании DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

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

Примечание: Ваше приложение должно игнорировать любые неопознанные поля, включенные в ответ.

Note: If your application already has a refresh token for the user and you want to obtain a new DPoP-bound refresh token, the user must revoke the existing grant or you must use the prompt=consent parameter in the initial authorization request to ensure a new refresh token is issued.

Ошибки

When exchanging the authorization code for an access token you may encounter the following error instead of the expected response. Common error codes and suggested resolutions are:

invalid_grant

The supplied authorization code is invalid or in the wrong format. Request a new code by restarting the OAuth process to prompt the user for consent again.

Step 6: Check which scopes users granted

When requesting multiple permissions (scopes), users may not grant your app access to all of them. Your app must verify which scopes were actually granted and gracefully handle situations where some permissions are denied, typically by disabling the features that rely on those denied scopes.

However, there are exceptions. Google Workspace Enterprise apps with domain-wide delegation of authority , or apps marked as Trusted , bypass the granular permissions consent screen. For these apps, users won't see the granular permission consent screen. Instead, your app will either receive all requested scopes or none.

For more detailed information, see How to handle granular permissions .

PHP

To check which scopes the user has granted, use the getGrantedScope() method:

// Space-separated string of granted scopes if it exists, otherwise null.
$granted_scopes = $client->getOAuth2Service()->getGrantedScope();

// Determine which scopes user granted and build a dictionary
$granted_scopes_dict = [
  'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
  'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
];

Python

The returned credentials object has a granted_scopes property, which is a list of scopes the user has granted to your app.

credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'granted_scopes': credentials.granted_scopes}

The following function checks which scopes the user has granted to your app.

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

Руби

When requesting multiple scopes at once, check which scopes were granted through the scope property of the credentials object.

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
  # User authorized read-only Drive activity permission.
  # Calling the APIs, etc
else
  # User didn't authorize read-only Drive activity permission.
  # Update UX and application accordingly
end

# Check if user authorized Calendar read permission.
if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
  # User authorized Calendar read permission.
  # Calling the APIs, etc.
else
  # User didn't authorize Calendar read permission.
  # Update UX and application accordingly
end

Node.js

When requesting multiple scopes at once, check which scopes were granted through the scope property of the tokens object.

// User authorized the request. Now, check which scopes were granted.
if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly'))
{
  // User authorized read-only Drive activity permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

// Check if user authorized Calendar read permission.
if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
{
  // User authorized Calendar read permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize Calendar read permission.
  // Update UX and application accordingly
}

HTTP/REST

To check whether the user has granted your application access to a particular scope, exam the scope field in the access token response. The scopes of access granted by the access_token expressed as a list of space-delimited, case-sensitive strings.

For example, the following sample access token response indicates that the user has granted your application access to the read-only Drive activity and Calendar events permissions:

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

Call Google APIs

PHP

Use the access token to call Google APIs by completing the following steps:

1. If you need to apply an access token to a new Google\Client object — for example, if you stored the access token in a user session — use the setAccessToken method:

   $client->setAccessToken($access_token);

2. Build a service object for the API that you want to call. You build a service object by providing an authorized Google\Client object to the constructor for the API you want to call. For example, to call the Drive API:

   $drive = new Google\Service\Drive($client);

3. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:

   $files = $drive->files->listFiles(array());

Python

After obtaining an access token, your application can use that token to authorize API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

1. Build a service object for the API that you want to call. You build a service object by calling the googleapiclient.discovery library's build method with the name and version of the API and the user credentials: For example, to call version 3 of the Drive API:

   from googleapiclient.discovery import build
   
   drive = build('drive', 'v2', credentials=credentials)

2. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:

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

Руби

After obtaining an access token, your application can use that token to make API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

1. Build a service object for the API that you want to call. For example, to call version 3 of the Drive API:

   drive = Google::Apis::DriveV3::DriveService.new

2. Set the credentials on the service:

   drive.authorization = credentials

3. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive:

   files = drive.list_files

Alternately, authorization can be provided on a per-method basis by supplying the options parameter to a method:

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

Node.js

After obtaining an access token and setting it to the OAuth2 object, use the object to call Google APIs. Your application can use that token to authorize API requests on behalf of a given user account or service account. Build a service object for the API that you want to call. For example, the following code uses the Google Drive API to list filenames in the user's Drive.

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

After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user account if the scope(s) of access required by the API have been granted. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the Drive Files API ).

You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground .

HTTP GET examples

A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:

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

Here is a call to the same API for the authenticated user using the access_token query string parameter:

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

curl examples

You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):

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

Or, alternatively, the query string parameter option:

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

Complete example

The following example prints a JSON-formatted list of files in a user's Google Drive after the user authenticates and gives consent for the application to access the user's Drive metadata.

PHP

To run this example:

1. In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add http://localhost:8080 .
2. Create a new directory and change to it. For example:

   mkdir ~/php-oauth2-example
   cd ~/php-oauth2-example

3. Install the Google API Client Library for PHP using Composer :

   composer require google/apiclient:^2.15.0

4. Create the files index.php and oauth2callback.php with the following content.
5. Run the example with the PHP's built-in test web server:

   php -S localhost:8080 ~/php-oauth2-example

index.php

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

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');

// User granted permission as an access token is in the session.
if (isset($_SESSION['access_token']) && $_SESSION['access_token'])
{
  $client->setAccessToken($_SESSION['access_token']);
  
  // Check if user granted Drive permission
  if ($_SESSION['granted_scopes_dict']['Drive']) {
    echo "Drive feature is enabled.";
    echo "</br>";
    $drive = new Drive($client);
    $files = array();
    $response = $drive->files->listFiles(array());
    foreach ($response->files as $file) {
        echo "File: " . $file->name . " (" . $file->id . ")";
        echo "</br>";
    }
  } else {
    echo "Drive feature is NOT enabled.";
    echo "</br>";
  }

   // Check if user granted Calendar permission
  if ($_SESSION['granted_scopes_dict']['Calendar']) {
    echo "Calendar feature is enabled.";
    echo "</br>";
  } else {
    echo "Calendar feature is NOT enabled.";
    echo "</br>";
  }
}
else
{
  // Redirect users to outh2call.php which redirects users to Google OAuth 2.0
  $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();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfigFile('client_secret.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);

// Required, to set the scope value, call the addScope function.
$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

// Enable incremental authorization. Recommended as a best practice.
$client->setIncludeGrantedScopes(true);

// Recommended, 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");

// Generate a URL for authorization as it doesn't contain code and error
if (!isset($_GET['code']) && !isset($_GET['error']))
{
  // Generate and set state value
  $state = bin2hex(random_bytes(16));
  $client->setState($state);
  $_SESSION['state'] = $state;

  // Generate a url that asks permissions.
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
}

// User authorized the request and authorization code is returned to exchange access and
// refresh tokens.
if (isset($_GET['code']))
{
  // Check the state value
  if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) {
    die('State mismatch. Possible CSRF attack.');
  }

  // Get access and refresh tokens (if access_type is offline)
  $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

  /** Save access and refresh token to the session variables.
    * ACTION ITEM: In a production app, you likely want to save the
    *              refresh token in a secure persistent storage instead. */
  $_SESSION['access_token'] = $token;
  $_SESSION['refresh_token'] = $client->getRefreshToken();
  
  // Space-separated string of granted scopes if it exists, otherwise null.
  $granted_scopes = $client->getOAuth2Service()->getGrantedScope();

  // Determine which scopes user granted and build a dictionary
  $granted_scopes_dict = [
    'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
    'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
  ];
  $_SESSION['granted_scopes_dict'] = $granted_scopes_dict;
  
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

// An error response e.g. error=access_denied
if (isset($_GET['error']))
{
  echo "Error: ". $_GET['error'];
}
?>

Python

This example uses the Flask framework. It runs a web application at http://localhost:8080 that lets you test the OAuth 2.0 flow. If you go to that URL, you should see five links:

• Call Drive API: This link points to a page that tries to execute a sample API request if users granted the permission. If necessary, it starts the authorization flow. If successful, the page displays the API response.
• Mock page to call Calendar API: This link points to a maockpage that tries to execute a sample Calendar API request if users granted the permission. If necessary, it starts the authorization flow. If successful, the page displays the API response.
• Test the auth flow directly: This link points to a page that tries to send the user through the authorization flow . The app requests permission to submit authorized API requests on the user's behalf.
• Revoke current credentials: This link points to a page that revokes permissions that the user has already granted to the application.
• Clear Flask session credentials: This link clears authorization credentials that are stored in the Flask session. This lets you see what would happen if a user who had already granted permission to your app tried to execute an API request in a new session. It also lets you see the API response your app would get if a user had revoked permissions granted to your app, and your app still tried to authorize a request with a revoked access token.

Note: To run this code locally, you must have followed the directions in the prerequisites section, including setting http://localhost:8080 as a valid redirect URI for your credentials and downloading the client_secret.json file for those credentials to your working directory.

# -*- coding: utf-8 -*-

import os
import flask
import json
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"

# The OAuth 2.0 access scope allows for access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly',
          'https://www.googleapis.com/auth/calendar.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('/drive')
def drive_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  features = flask.session['features']

  if features['drive']:
    # Load client secrets from the server-side file.
    with open(CLIENT_SECRETS_FILE, 'r') as f:
        client_config = json.load(f)['web']

    # Load user-specific credentials from browser session storage.
    session_credentials = flask.session['credentials']

    # Reconstruct the credentials object.
    credentials = google.oauth2.credentials.Credentials(
        refresh_token=session_credentials.get('refresh_token'),
        scopes=session_credentials.get('granted_scopes'),
        token=session_credentials.get('token'),
        client_id=client_config.get('client_id'),
        client_secret=client_config.get('client_secret'),
        token_uri=client_config.get('token_uri'))

    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.
    flask.session['credentials'] = credentials_to_dict(credentials)

    return flask.jsonify(**files)
  else:
    # User didn't authorize read-only Drive activity permission.
    return '<p>Drive feature is not enabled.</p>'

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

  features = flask.session['features']

  if features['calendar']:
    # User authorized Calendar read permission.
    # Calling the APIs, etc.
    return ('<p>User granted the Google Calendar read permission. '+
            'This sample code does not include code to call Calendar</p>')
  else:
    # User didn't authorize Calendar read permission.
    # Update UX and application accordingly
    return '<p>Calendar feature is not enabled.</p>'

@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
  
  credentials = credentials_to_dict(credentials)
  flask.session['credentials'] = credentials

  # Check which scopes user granted
  features = check_granted_scopes(credentials)
  flask.session['features'] = features
  return flask.redirect('/')
  
@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.')

  # Load client secrets from the server-side file.
  with open(CLIENT_SECRETS_FILE, 'r') as f:
      client_config = json.load(f)['web']

  # Load user-specific credentials from the session.
  session_credentials = flask.session['credentials']

  # Reconstruct the credentials object.
  credentials = google.oauth2.credentials.Credentials(
      refresh_token=session_credentials.get('refresh_token'),
      scopes=session_credentials.get('granted_scopes'),
      token=session_credentials.get('token'),
      client_id=client_config.get('client_id'),
      client_secret=client_config.get('client_secret'),
      token_uri=client_config.get('token_uri'))

  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:
    # Clear the user's session credentials after successful revocation
    if 'credentials' in flask.session:
        del flask.session['credentials']
        del flask.session['features']
    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,
          'granted_scopes': credentials.granted_scopes}

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

def print_index_table():
  return ('<table>' + 
          '<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="/drive">Call Drive API directly</a></td>' +
          '<td> Use stored credentials to call the API, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/calendar">Call Calendar API directly</a></td>' +
          '<td> Use stored credentials to call the API, 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="/authorize">authorize</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'

  # This disables the requested scopes and granted scopes check.
  # If users only grant partial request, the warning would not be thrown.
  os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '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)

Руби

This example uses the Sinatra framework.

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/drive_v3'
require 'google/apis/calendar_v3'

require 'sinatra'

configure do
  enable :sessions

  # Required, call the from_file method to retrieve the client ID from a
  # client_secret.json file.
  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')

  # Required, scope value
  # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
  scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
           'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

  # Required, Authorizers require a storage instance to manage long term persistence of
  # access and refresh tokens.
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

  # Required, 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.
  set :callback_uri, '/oauth2callback'

  # 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.
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope,
                          settings.token_store, callback_uri: settings.callback_uri)
end

get '/' do
  # NOTE: Assumes the user is already authenticated to the app
  user_id = request.session['user_id']

  # Fetch stored credentials for the user from the given request session.
  # nil if none present
  credentials = settings.authorizer.get_credentials(user_id, request)

  if credentials.nil?
    # Generate a url that asks the user to authorize requested scope(s).
    # Then, redirect user to the url.
    redirect settings.authorizer.get_authorization_url(request: request)
  end
  
  # User authorized the request. Now, check which scopes were granted.
  if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
    # User authorized read-only Drive activity permission.
    # Example of using Google Drive API to list filenames in user's Drive.
    drive = Google::Apis::DriveV3::DriveService.new
    files = drive.list_files(options: { authorization: credentials })
    "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
  else
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
  end

  # Check if user authorized Calendar read permission.
  if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
    # User authorized Calendar read permission.
    # Calling the APIs, etc.
  else
    # User didn't authorize Calendar read permission.
    # Update UX and application accordingly
  end
end

# Receive the callback from Google's OAuth 2.0 server.
get '/oauth2callback' do
  # Handle the result of the oauth callback. Defers the exchange of the code by
  # temporarily stashing the results in the user's session.
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

To run this example:

1. In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add http://localhost .
2. Make sure you have maintenance LTS, active LTS, or current release of Node.js installed.
3. Create a new directory and change to it. For example:

   mkdir ~/nodejs-oauth2-example
   cd ~/nodejs-oauth2-example

4. Install the Google API Client Library for Node.js using npm :

   npm install googleapis

5. Create the files main.js with the following content.
6. Run the example:

   node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

/* 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 app = express();

  app.use(session({
    secret: 'your_secure_secret_key', // Replace with a strong secret
    resave: false,
    saveUninitialized: false,
  }));

  // Example on redirecting user to Google's OAuth 2.0 server.
  app.get('/', async (req, res) => {
    // Generate a secure random state value.
    const state = crypto.randomBytes(32).toString('hex');
    // Store state in the session
    req.session.state = state;

    // Generate a url that asks permissions for the Drive activity and Google Calendar 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,
      // Include the state parameter to reduce the risk of CSRF attacks.
      state: state
    });

    res.redirect(authorizationUrl);
  });

  // Receive the callback from Google's OAuth 2.0 server.
  app.get('/oauth2callback', async (req, res) => {
    // 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 if (q.state !== req.session.state) { //check state value
      console.log('State mismatch. Possible CSRF attack');
      res.end('State mismatch. Possible CSRF attack');
    } 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;
      
      // User authorized the request. Now, check which scopes were granted.
      if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly'))
      {
        // User authorized read-only Drive activity permission.
        // 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.');
          }
        });
      }
      else
      {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
      }

      // Check if user authorized Calendar read permission.
      if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
      {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
      }
      else
      {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
      }
    }
  });

  // Example on revoking a token
  app.get('/revoke', async (req, res) => {
    // 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();
  });


  const server = http.createServer(app);
  server.listen(8080);
}
main().catch(console.error);

HTTP/REST

This Python example uses the Flask framework and the Requests library to demonstrate the OAuth 2.0 web flow. We recommend using the Google API Client Library for Python for this flow. (The example in the Python tab does use the client library.)

import json
import flask
import requests

app = flask.Flask(__name__)

# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit
# https://console.cloud.google.com/apis/credentials.
CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app

# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.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.
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: 
    # User authorized the request. Now, check which scopes were granted.
    if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['scope']:
      # User authorized read-only Drive activity permission.
      # Example of using Google Drive API to list filenames in user's Drive.
      headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
      req_uri = 'https://www.googleapis.com/drive/v2/files'
      r = requests.get(req_uri, headers=headers).text
    else:
      # User didn't authorize read-only Drive activity permission.
      # Update UX and application accordingly
      r = 'User did not authorize Drive permission.'

    # Check if user authorized Calendar read permission.
    if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['scope']:
      # User authorized Calendar read permission.
      # Calling the APIs, etc.
      r += 'User authorized Calendar permission.'
    else:
      # User didn't authorize Calendar read permission.
      # Update UX and application accordingly
      r += 'User did not authorize Calendar permission.'

  return r

@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    state = str(uuid.uuid4())
    flask.session['state'] = state
    # Generate a url that asks permissions for the Drive activity
    # and Google Calendar scope. Then, redirect user to the url.
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI,
                                                                          SCOPE, state)
    return flask.redirect(auth_uri)
  else:
    if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']:
      return 'State mismatch. Possible CSRF attack.', 400

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

    # Exchange authorization code for access and refresh tokens (if access_type is offline)
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))

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

Redirect URI validation rules

Google applies the following validation rules to redirect URIs in order to help developers keep their applications secure. Your redirect URIs must adhere to these rules. See RFC 3986 section 3 for the definition of domain, host, path, query, scheme and userinfo:

Validation rules
Схема	Redirect URIs must use the HTTPS scheme, not plain HTTP. Localhost URIs (including localhost IP address URIs) are exempt from this rule.
Хозяин	Hosts cannot be raw IP addresses. Localhost IP addresses are exempted from this rule.
Домен	Host TLDs ( Top Level Domains ) must belong to the public suffix list . Host domains cannot be “googleusercontent.com” . Redirect URIs cannot contain URL shortener domains (eg goo.gl ) unless the app owns the domain. Furthermore, if an app that owns a shortener domain chooses to redirect to that domain, that redirect URI must either contain “/google-callback/” in its path or end with “/google-callback” .
Userinfo	Redirect URIs cannot contain the userinfo subcomponent.
Путь	Redirect URIs cannot contain a path traversal (also called directory backtracking), which is represented by an “/..” or “\..” or their URL encoding.
Запрос	Redirect URIs cannot contain open redirects .
Фрагмент	Redirect URIs cannot contain the fragment component.
Персонажи	Redirect URIs cannot contain certain characters including: Wildcard characters ( '*' ) Non-printable ASCII characters Invalid percent encodings (any percent encoding that does not follow URL-encoding form of a percent sign followed by two hexadecimal digits) Null characters (an encoded NULL character, eg, %00 , %C0%80 )

Incremental authorization

In the OAuth 2.0 protocol, your app requests authorization to access resources, which are identified by scopes. It is considered a best user-experience practice to request authorization for resources at the time you need them. To enable that practice, Google's authorization server supports incremental authorization. This feature lets you request scopes as they are needed and, if the user grants permission for the new scope, returns an authorization code that may be exchanged for a token containing all scopes the user has granted the project.

For example, an app that lets people sample music tracks and create mixes might need very few resources at sign-in time, perhaps nothing more than the name of the person signing in. However, saving a completed mix would require access to their Google Drive. Most people would find it natural if they only were asked for access to their Google Drive at the time the app actually needed it.

In this case, at sign-in time the app might request the openid and profile scopes to perform basic sign-in, and then later request the https://www.googleapis.com/auth/drive.file scope at the time of the first request to save a mix.

To implement incremental authorization, you complete the normal flow for requesting an access token but make sure that the authorization request includes previously granted scopes. This approach allows your app to avoid having to manage multiple access tokens.

The following rules apply to an access token obtained from an incremental authorization:

• The token can be used to access resources corresponding to any of the scopes rolled into the new, combined authorization.
• When you use the refresh token for the combined authorization to obtain an access token, the access token represents the combined authorization and can be used for any of the scope values included in the response.
• The combined authorization includes all scopes that the user granted to the API project even if the grants were requested from different clients. For example, if a user granted access to one scope using an application's desktop client and then granted another scope to the same application via a mobile client, the combined authorization would include both scopes.
• If you revoke a token that represents a combined authorization, access to all of that authorization's scopes on behalf of the associated user are revoked simultaneously.

Caution: choosing to include granted scopes will automatically add scopes previously granted by the user to your authorization request. A warning or error page may be displayed if your app is not currently approved to request all scopes that may be returned in the response. See Unverified apps for more information.

The language-specific code samples in Step 1: Set authorization parameters and the sample HTTP/REST redirect URL in Step 2: Redirect to Google's OAuth 2.0 server all use incremental authorization. These code samples show the code that you need to add to use incremental authorization:

PHP

$client->setIncludeGrantedScopes(true);

Python

In Python, set the include_granted_scopes keyword argument to true to ensure that an authorization request includes previously granted scopes. It is very possible that include_granted_scopes will not be the only keyword argument that you set, as shown in the example below.

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

Руби

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.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
  redirect_uri=https%3A//developers.google.com/oauthplayground&
  prompt=consent&
  include_granted_scopes=true

Refresh an access token (offline access)

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

• If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
• If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server . In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online .

Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

PHP

If your application needs offline access to a Google API, set the API client's access type to offline :

$client->setAccessType("offline");

After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

Python

In Python, set the access_type keyword argument to offline to ensure that you will be able to refresh the access token without having to re-prompt the user for permission. It is very possible that access_type will not be the only keyword argument that you set, as shown in the example below.

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

After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

Руби

If your application needs offline access to a Google API, set the API client's access type to offline :

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

After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

Node.js

If your application needs offline access to a Google API, set the API client's access type to 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
});

After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

Access tokens expire. This library will automatically use a refresh token to obtain a new access token if it is about to expire. An easy way to make sure you always store the most recent tokens is to use the tokens event:

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

This tokens event only occurs in the first authorization, and you need to have set your access_type to offline when calling the generateAuthUrl method to receive the refresh token. If you have already given your app the requisiste permissions without setting the appropriate constraints for receiving a refresh token, you will need to re-authorize the application to receive a fresh refresh token.

To set the refresh_token at a later time, you can use the setCredentials method:

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

Once the client has a refresh token, access tokens will be acquired and refreshed automatically in the next call to the API.

HTTP/REST

To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters in the request body:

Имя	Ценить
client_id	The client ID obtained from the API Console .
client_secret	Необязательный The client secret obtained from the API Console .
grant_type	As defined in the OAuth 2.0 specification , this field's value must be set to refresh_token .
refresh_token	The refresh token returned from the authorization code exchange.

While the use of DPoP is optional, it is recommended for increased security. To use DPoP with a refresh token, your application must generate a new, unique DPoP proof JWT for each request to the token endpoint. This proof must be signed with the same private key that was used during the initial authorization code exchange. Your application adds the proof as a HTTP request header.

Заголовок	Необходимый	Описание
DPoP	Необязательный	A DPoP proof is a JWT that proves the possession of a private key. This is a header, not a parameter. If provided, the returned tokens are bound to this key. A new, unique proof must be generated for each request and must include htm (HTTP method) and htu (HTTP URI) claims that match the request.

The following snippet shows a sample request:

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

To use DPoP with a refresh token, you must generate a new, unique DPoP proof JWT for the request. See Construct a DPoP proof for step-by-step instructions on generating the key pair and constructing the JWT.

A successful exchange is indicated by a 200 OK response containing a new access token. When DPoP is used, the token_type is Bearer . A successful response confirms the DPoP proof for the refresh token was accepted. Google may also return a new DPoP-Nonce HTTP header in the response; if returned, your client must cache this nonce and include it in the nonce claim of the DPoP proof in subsequent requests.

A failed exchange occurs if the DPoP header is missing, invalid, or uses an incorrect key. For details on specific DPoP error codes and handling nonces, see Failed exchange .

The following snippet shows a sample successful response headers and body when DPoP is used:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

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

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Token revocation

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

PHP

To programmatically revoke a token, call revokeToken() :

$client->revokeToken();

Key Point: Revocation removes all OAuth 2.0 scopes previously granted to a project, invalidating any issued access or refresh tokens for all clients registered under that project.

Python

To programmatically revoke a token, make a request to https://oauth2.googleapis.com/revoke that includes the token as a parameter and sets the Content-Type header:

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

Key Point: Revocation removes all OAuth 2.0 scopes previously granted to a project, invalidating any issued access or refresh tokens for all clients registered under that project.

Руби

To programmatically revoke a token, make an HTTP request to the oauth2.revoke endpoint:

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

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the status code of the response is 200 . For error conditions, a status code 400 is returned along with an error code.

Key Point: Revocation removes all OAuth 2.0 scopes previously granted to a project, invalidating any issued access or refresh tokens for all clients registered under that project.

Node.js

To programmatically revoke a token, make an HTTPS POST request to /revoke endpoint:

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();

The token parameter can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the status code of the response is 200 . For error conditions, a status code 400 is returned along with an error code.

Key Point: Revocation removes all OAuth 2.0 scopes previously granted to a project, invalidating any issued access or refresh tokens for all clients registered under that project.

HTTP/REST

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

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

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

Key Point: Revocation removes all OAuth 2.0 scopes previously granted to a project, invalidating any issued access or refresh tokens for all clients registered under that project.

Note: Following a successful revocation response, it might take some time before the revocation has full effect.

Доступ по времени

Time-based access allows a user to grant your app access to their data for a limited duration to complete an action. Time-based access is available in select Google products during the consent flow, giving users the option to grant access for a limited period of time. An example is the Data Portability API which enables a one-time transfer of data.

When a user grants your application time-based access, the refresh token will expire after the specified duration. Note that refresh tokens may be invalidated earlier under specific circumstances; see these cases for details. The refresh_token_expires_in field returned in the authorization code exchange response represents the time remaining until the refresh token expires in such cases.

Implement Cross-Account Protection

An additional step you should take to protect your users' accounts is implementing Cross-Account Protection by utilizing Google's Cross-Account Protection Service. This service lets you subscribe to security event notifications which provide information to your application about major changes to the user account. You can then use the information to take action depending on how you decide to respond to events.

Some examples of the event types sent to your app by Google's Cross-Account Protection Service are:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

See the Protect user accounts with Cross-Account Protection page for more information on how to implement Cross Account Protection and for the full list of available events.