OpenID Connect

API OAuth 2.0 от Google можно использовать как для аутентификации, так и для авторизации. В этом документе описывается наша реализация OAuth 2.0 для аутентификации, которая соответствует спецификации OpenID Connect и сертифицирована OpenID . Документация, изложенная в статье «Использование OAuth 2.0 для доступа к API Google», также применима к этому сервису. Для интерактивного изучения этого протокола рекомендуем использовать Google OAuth 2.0 Playground . Чтобы получить помощь на Stack Overflow , добавляйте к своим вопросам тег «google-oauth».

Примечание: Чтобы добавить кнопку «Войти через Google» на свой сайт, используйте Google Identity Services — нашу клиентскую библиотеку для входа, построенную на протоколе OpenID Connect. Эта библиотека предоставляет токены идентификаторов в формате OpenID Connect. Приложения Android должны использовать API Credential Manager для реализации входа через Google.

Настройка OAuth 2.0

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

Получите учетные данные OAuth 2.0

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

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

Или просмотрите свой идентификатор клиента и секрет клиента со страницы учетных данных в API Console :

1. Go to the Credentials page.
2. Нажмите на имя вашего удостоверения или значок карандаша ( ). Ваш идентификатор клиента и секретные данные находятся вверху страницы.

Установить URI перенаправления

URI перенаправления, который вы установили в определяет, куда Google отправляет ответы на ваши запросы аутентификации .

Чтобы создать, просмотреть или изменить URI перенаправления для заданных учетных данных OAuth 2.0, выполните следующие действия:

1. Go to the Credentials page.
2. В разделе идентификаторов клиентов OAuth 2.0 на странице щелкните учетные данные.
3. Просмотр или редактирование URI перенаправления.

Если на странице «Учетные данные» нет раздела идентификаторов клиентов OAuth 2.0 , значит, у вашего проекта нет учетных данных OAuth. Чтобы создать его, нажмите « Создать учетные данные» .

Настройте экран согласия пользователя

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

На экране согласия пользователя также отображается информация о бренде, такая как название вашего продукта, логотип и URL домашней страницы. Вы можете управлять информацией о бренде в .

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

1. Откройте Consent Screen page в Google API Console .
2. If prompted, select a project, or create a new one.
3. Заполните форму и нажмите Сохранить .

В следующем диалоговом окне согласия показано, что увидит пользователь, если в запросе присутствует комбинация областей OAuth 2.0 и Google Drive. (Этот общий диалог был создан с использованием Google OAuth 2.0 Playground , поэтому он не включает информацию о брендинге, которая будет установлена в .)

Рисунок 1. Скриншот страницы согласия

Доступ к услуге

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

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

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

Аутентификация пользователя

Аутентификация пользователя включает получение идентификационного токена и его проверку. Идентификационные токены — это стандартизированная функция OpenID Connect , предназначенная для обмена идентификационными данными в Интернете.

Наиболее распространённые подходы к аутентификации пользователя и получению токена ID называются «серверным» и «неявным» потоками. Серверный поток позволяет бэкенд-серверу приложения проверять личность пользователя, используя браузер или мобильное устройство. Неявный поток используется, когда клиентскому приложению (обычно JavaScript-приложению, работающему в браузере) требуется прямой доступ к API, а не к бэкенд-серверу.

В этом документе описывается, как реализовать серверный поток аутентификации пользователя. Неявный поток значительно сложнее из-за рисков безопасности при обработке и использовании токенов на стороне клиента. Если вам необходимо реализовать неявный поток, мы настоятельно рекомендуем использовать Google Identity Services .

Поток сервера

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

1. Создать государственный токен, защищённый от подделки
2. Отправьте запрос на аутентификацию в Google
3. Подтвердите токен состояния защиты от подделки
4. Обменять code на токен доступа и идентификационный токен
5. Получить информацию о пользователе из идентификатора токена
6. Аутентифицировать пользователя

1. Создайте государственный токен, защищенный от подделки

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

Хорошим вариантом токена состояния является строка длиной около 30 символов, созданная с помощью высококачественного генератора случайных чисел. Другой вариант — хеш, сгенерированный путём подписания некоторых переменных состояния сеанса ключом, который хранится в секрете на вашем сервере.

Следующий код демонстрирует генерацию уникальных токенов сеанса.

PHP

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для PHP .

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Ява

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Java .

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Питон

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Python .

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Отправьте запрос на аутентификацию в Google.

Следующий шаг — формирование HTTPS-запроса GET с соответствующими параметрами URI. Обратите внимание на использование HTTPS вместо HTTP на всех этапах этого процесса; HTTP-подключения отклоняются. Базовый URI следует получить из документа Discovery, используя значение метаданных authorization_endpoint . В дальнейшем обсуждении предполагается, что базовый URI — https://accounts.google.com/o/oauth2/v2/auth .

Для базового запроса укажите следующие параметры:

• client_id , который вы получаете из .
• response_type , который в базовом запросе потока кода авторизации должен быть code . (Подробнее см. в response_type .)
• scope , которая в базовом запросе должна быть openid email . (Подробнее см. в scope .)
• redirect_uri должен быть конечной точкой HTTP на вашем сервере, которая получит ответ от Google. Значение должно точно соответствовать одному из авторизованных URI перенаправления для клиента OAuth 2.0, настроенных вами в Credentials page. Если это значение не соответствует авторизованному URI, запрос завершится ошибкой redirect_uri_mismatch .
• state должно включать значение уникального токена сеанса, защищающего от подделки, а также любую другую информацию, необходимую для восстановления контекста при возвращении пользователя в ваше приложение, например, начальный URL-адрес. (Подробнее см. в state .)
• nonce — это случайное значение, генерируемое вашим приложением, которое при наличии включает защиту от повторного воспроизведения.
• login_hint может быть адресом электронной почты пользователя или sub , эквивалентной идентификатору Google ID пользователя. Если login_hint не указан, а пользователь уже вошёл в систему, на экране согласия будет запрошено разрешение на передачу адреса электронной почты пользователя в ваше приложение. (Подробнее см. на login_hint .)
• Используйте параметр hd для оптимизации потока OpenID Connect для пользователей определенного домена, связанного с организацией Google Workspace или Cloud (подробнее см. hd ).
Примечание: Это некоторые из наиболее часто используемых параметров. Полный список и более подробную информацию о параметрах см. в разделе «Параметры URI аутентификации» .

Вот пример полного URI аутентификации OpenID Connect с переносами строк и пробелами для удобства чтения:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

3. Подтвердите статус токена защиты от подделки

Ответ отправляется на redirect_uri , указанный в запросе . Все ответы возвращаются в строке запроса:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

На сервере необходимо подтвердить, что state полученное от Google, соответствует токену сеанса, созданному на шаге 1. Такая круговая проверка позволяет убедиться, что запрос отправляет именно пользователь, а не вредоносный скрипт.

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

PHP

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для PHP .

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Ява

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Java .

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Питон

Чтобы использовать этот пример, вам необходимо загрузить клиентскую библиотеку Google API для Python .

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Обменяйте code на токен доступа и идентификационный токен.

Ответ включает параметр code — одноразовый код авторизации, который ваш сервер может обменять на токен доступа и токен идентификатора. Ваш сервер выполняет этот обмен, отправляя HTTPS-запрос POST . Запрос POST отправляется на конечную точку токена, которую необходимо получить из документа Discovery с помощью значения метаданных token_endpoint . В дальнейшем обсуждении предполагается, что конечная точка — https://oauth2.googleapis.com/token . Запрос должен содержать следующие параметры в теле POST :

Поля
code	Код авторизации, возвращаемый из первоначального запроса .
client_id	Идентификатор клиента, который вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
client_secret	Секрет клиента, который вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
redirect_uri	Авторизованный URI перенаправления для данного client_id , указанного в , как описано в разделе Установка URI перенаправления .
grant_type	Это поле должно содержать значение authorization_code , как определено в спецификации OAuth 2.0 .

Фактический запрос может выглядеть следующим образом:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Успешный ответ на этот запрос содержит следующие поля в массиве JSON:

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

Примечание: количество токенов на одну учётную запись Google ограничено, и любой запрос на аутентификацию, превышающий это ограничение, может незаметно аннулировать выданный токен обновления. Подробнее см. в разделе «Окончание срока действия токена» .

5. Получите информацию о пользователе из идентификатора токена.

Идентификационный токен (ID Token) — это JWT (JSON Web Token), то есть криптографически подписанный JSON-объект, закодированный в формате Base64. Обычно крайне важно проверить ID Token перед его использованием, но поскольку вы взаимодействуете напрямую с Google по HTTPS-каналу без посредников и используете свой секретный ключ клиента для аутентификации в Google, вы можете быть уверены, что полученный вами токен действительно получен от Google и является действительным. Если ваш сервер передаёт ID Token другим компонентам вашего приложения, крайне важно, чтобы эти компоненты проверили его перед использованием.

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

Полезная нагрузка токена ID

Идентификационный токен — это JSON-объект, содержащий набор пар «имя/значение». Вот пример, отформатированный для удобства чтения:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Внимание: При внедрении системы управления аккаунтами не следует использовать поле адреса email в токене ID в качестве уникального идентификатора пользователя. Всегда используйте sub , поскольку оно уникально для аккаунта Google, даже если пользователь меняет свой адрес электронной почты.

Токены Google ID могут содержать следующие поля (известные как утверждения ):

Требовать	Предоставил	Описание
aud	всегда	Аудитория, для которой предназначен этот токен. Это должен быть один из идентификаторов клиента OAuth 2.0 вашего приложения.
exp	всегда	Срок действия, по истечении которого токен ID не должен быть принят. Указывается в формате времени эпохи Unix (целое число секунд).
iat	всегда	Время выдачи токена ID. Указывается в формате времени Unix (целое число секунд).
iss	всегда	Идентификатор эмитента ответа. Для токенов Google ID всегда https://accounts.google.com или accounts.google.com .
sub	всегда	Идентификатор пользователя, уникальный среди всех учётных записей Google и никогда не используемый повторно. Учётная запись Google может иметь несколько адресов электронной почты в разные моменты времени, но значение sub никогда не меняется. Используйте sub в своём приложении в качестве уникального идентификатора пользователя. Максимальная длина — 255 символов ASCII с учётом регистра.
at_hash		Хеш токена доступа. Обеспечивает проверку того, что токен доступа привязан к идентификационному токену. Если идентификационный токен выдаётся со значением access_token в серверном потоке, это утверждение всегда включается. Это утверждение можно использовать в качестве альтернативного механизма защиты от атак с подделкой межсайтовых запросов, но если вы выполните шаги 1 и 3, то проверять токен доступа не обязательно.
azp		client_id авторизованного докладчика. Это утверждение необходимо только в том случае, если сторона, запрашивающая токен ID, не совпадает с аудиторией токена ID. Это может иметь место в гибридных приложениях Google, когда веб-приложение и приложение для Android имеют разные идентификаторы client_id OAuth 2.0, но используют один и тот же проект API Google.
email		Адрес электронной почты пользователя. Предоставляется только в том случае, если вы включили область действия адреса email в свой запрос. Значение этого утверждения может быть не уникальным для данной учётной записи и меняться со временем, поэтому не следует использовать это значение в качестве основного идентификатора для связи с вашей записью пользователя. Вы также не можете полагаться на домен утверждения адреса email для идентификации пользователей организаций Google Workspace или Cloud; вместо этого используйте утверждение hd . Внимание: Не используйте поле email в качестве уникального идентификатора пользователя. Всегда используйте sub поле.
email_verified		True, если адрес электронной почты пользователя подтвержден; в противном случае false.
family_name		Фамилия (имена) пользователя. Может быть указана при наличии заявки name .
given_name		Имя (имена) пользователя. Может быть указано при наличии заявки name .
hd		Домен, связанный с организацией Google Workspace или Cloud пользователя. Указывается только в том случае, если пользователь принадлежит организации Google Cloud. Необходимо проверить это утверждение, если доступ к ресурсу ограничен только для участников определённых доменов. Отсутствие этого утверждения означает, что учётная запись не принадлежит домену, размещённому в Google.
locale		Локаль пользователя, представленная языковым тегом BCP 47. Может быть указана при наличии заявки name .
name		Полное имя пользователя в отображаемой форме. Может быть указано в следующих случаях: В область запроса включена строка «профиль». Идентификационный токен возвращается после обновления токена. При наличии заявок name вы можете использовать их для обновления записей пользователей вашего приложения. Обратите внимание, что наличие этой заявки не гарантируется.
nonce		Значение nonce предоставленное вашим приложением в запросе аутентификации. Для защиты от атак повторного воспроизведения это значение следует указывать только один раз.
picture		URL-адрес изображения профиля пользователя. Может предоставляться в следующих случаях: В область запроса включена строка «профиль». Идентификационный токен возвращается после обновления токена. При наличии заявок picture вы можете использовать их для обновления пользовательских записей вашего приложения. Обратите внимание, что наличие этой заявки не гарантируется.
profile		URL-адрес страницы профиля пользователя. Может предоставляться в следующих случаях: В область запроса включена строка «профиль». Идентификационный токен возвращается после обновления токена. При наличии заявок profile вы можете использовать их для обновления записей пользователей вашего приложения. Обратите внимание, что наличие этой заявки не гарантируется.

6. Аутентифицируйте пользователя.

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

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

Продвинутые темы

В следующих разделах API Google OAuth 2.0 описывается более подробно. Эта информация предназначена для разработчиков с повышенными требованиями к аутентификации и авторизации.

Доступ к другим API Google

Одним из преимуществ использования OAuth 2.0 для аутентификации является то, что ваше приложение может получить разрешение на использование других API Google от имени пользователя (например, YouTube, Google Drive, Calendar или Contacts) одновременно с аутентификацией пользователя. Для этого включите другие необходимые области действия в запрос на аутентификацию , отправляемый в Google. Например, чтобы добавить возрастную группу пользователя в запрос на аутентификацию, передайте параметр области действия openid email https://www.googleapis.com/auth/profile.agerange.read . Пользователь получит соответствующий запрос на экране согласия . Токен доступа, который вы получите от Google, позволит вашему приложению получить доступ ко всем API, связанным с запрошенными и предоставленными вами областями действия.

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

Обновление токенов

В запросе на доступ к API вы можете запросить токен обновления, который будет возвращен при обмене code . Токен обновления обеспечивает вашему приложению постоянный доступ к API Google, даже если пользователь отсутствует в приложении. Чтобы запросить токен обновления, добавьте в запрос аутентификации параметр access_type , установив значение offline .

Соображения:

• Обязательно сохраните токен обновления в безопасном и постоянном месте, поскольку получить токен обновления можно только при первом выполнении потока обмена кодами.
• Существуют ограничения на количество выдаваемых токенов обновления: один на комбинацию клиент/пользователь и ещё один на пользователя для всех клиентов. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.

Дополнительные сведения см. в разделе Обновление токена доступа (автономный доступ) .

Приглашение к повторному согласию

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

Дополнительную информацию о параметре prompt см. в разделе prompt в таблице параметров аутентификации URI .

Параметры URI аутентификации

В следующей таблице приведены более полные описания параметров, принимаемых API аутентификации Google OAuth 2.0.

Параметр	Необходимый	Описание
client_id	(Необходимый)	Строка идентификатора клиента, которую вы получаете от , как описано в разделе Получение учетных данных OAuth 2.0 .
nonce	(Необходимый)	Случайное значение, генерируемое вашим приложением, которое включает защиту от повторного воспроизведения.
response_type	(Необходимый)	Если значение равно code , запускает базовый поток авторизации code , требующий POST к конечной точке токена для получения токенов. Если значение равно token id_token или id_token token , запускает неявный поток , требующий использования JavaScript в URI перенаправления для получения токенов из URI #fragment identifier .
redirect_uri	(Необходимый)	Определяет, куда будет отправлен ответ. Значение этого параметра должно точно соответствовать одному из разрешенных значений перенаправления, заданных в (включая схему HTTP или HTTPS, регистр и конечный символ «/», если таковой имеется).
scope	(Необходимый)	Параметр области действия должен начинаться со значения openid , а затем включать значение profile , значение email или и то, и другое. Если значение области действия profile присутствует, токен идентификатора может (но не гарантируется) включать утверждения profile пользователя по умолчанию. Если значение области действия email присутствует, токен идентификатора включает утверждения email и email_verified . Помимо этих областей действия, специфичных для OpenID, ваш аргумент области действия может включать и другие значения области действия. Все значения области действия должны быть разделены пробелами. Например, если вам нужен доступ к Google Диску пользователя по каждому файлу, параметр области действия может быть следующим: openid profile email https://www.googleapis.com/auth/drive.file . Информацию о доступных областях действия см. в разделе Области действия OAuth 2.0 для API Google или в документации по API Google, который вы хотели бы использовать.
state	(Необязательно, но настоятельно рекомендуется)	Непрозрачная строка, которая передается по протоколу; то есть она возвращается как параметр URI в основном потоке и в идентификаторе URI #fragment в неявном потоке. state может быть полезно для сопоставления запросов и ответов. Поскольку redirect_uri можно угадать, использование значения state может повысить уверенность в том, что входящее соединение является результатом запроса аутентификации, инициированного вашим приложением. Сгенерировав случайную строку или закодировав хеш какого-либо состояния клиента (например, cookie) в этой переменной state , вы можете проверить ответ и убедиться, что запрос и ответ были получены из одного и того же браузера. Это обеспечивает защиту от атак, таких как межсайтовая подделка запросов.
access_type	(Необязательный)	Допустимые значения: offline и online . Этот эффект описан в разделе «Offline Access» : если запрашивается токен доступа, клиент не получает токен обновления, если не указано значение offline .
display	(Необязательный)	Строковое значение ASCII, определяющее, как сервер авторизации отображает страницы пользовательского интерфейса аутентификации и согласия. Следующие значения указаны и принимаются серверами Google, но не влияют на поведение потока протоколов: page , popup , touch и wap .
hd	(Необязательный)	Оптимизируйте процесс входа для учётных записей, принадлежащих организации Google Cloud. Указав домен организации Google Cloud (например, mycollege.edu ), вы можете указать, что пользовательский интерфейс выбора учётной записи должен быть оптимизирован для учётных записей в этом домене. Чтобы оптимизировать учётные записи организации Google Cloud в целом, а не только для одного домена организации Google Cloud, установите значение звёздочки ( * ): hd=* . Не полагайтесь на эту оптимизацию пользовательского интерфейса для управления доступом к вашему приложению, поскольку запросы на стороне клиента могут быть изменены. Убедитесь , что возвращаемый токен идентификатора имеет значение утверждения hd , соответствующее ожидаемому (например, mycolledge.edu ). В отличие от параметра запроса, утверждение hd токена идентификатора содержится в токене безопасности от Google, поэтому этому значению можно доверять.
include_granted_scopes	(Необязательный)	Если этому параметру предоставлено значение true и запрос на авторизацию удовлетворен, авторизация будет включать все предыдущие авторизации, предоставленные этой комбинации пользователь/приложение для других областей; см. Инкрементная авторизация . Обратите внимание, что вы не можете выполнить поэтапную авторизацию с помощью потока «Установленное приложение».
login_hint	(Необязательный)	Когда ваше приложение знает, какого пользователя оно пытается аутентифицировать, оно может предоставить этот параметр в качестве подсказки серверу аутентификации. Передача этой подсказки блокирует выбор учётной записи и либо автоматически заполняет поле электронной почты в форме входа, либо выбирает нужный сеанс (если пользователь использует множественный вход ), что помогает избежать проблем, возникающих при входе в приложение с неправильной учётной записью. Значением может быть адрес электронной почты или sub , эквивалентная идентификатору Google ID пользователя.
prompt	(Необязательный)	Список строковых значений, разделенных пробелами, который определяет, будет ли сервер авторизации запрашивать у пользователя повторную аутентификацию и согласие. Возможные значения: none Сервер авторизации не отображает экраны аутентификации или согласия пользователя; он возвращает ошибку, если пользователь ещё не аутентифицирован и не настроил предварительно согласие для запрошенных областей. Для проверки наличия аутентификации и/или согласия можно использовать none . consent Сервер авторизации запрашивает у пользователя согласие, прежде чем вернуть информацию клиенту. select_account Сервер авторизации предлагает пользователю выбрать учётную запись. Это позволяет пользователю, имеющему несколько учётных записей на сервере авторизации, выбирать среди нескольких учётных записей, для которых у него могут быть текущие сеансы. Если значение не указано и пользователь ранее не авторизовал доступ, то пользователю будет показан экран согласия.

Проверка идентификационного токена

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

Ниже приведены распространенные ситуации, в которых вы можете отправлять идентификационные токены на свой сервер:

• Отправка идентификационных токенов с запросами, требующими аутентификации. Идентификационные токены сообщают, какой именно пользователь сделал запрос и какому клиенту был предоставлен этот идентификационный токен.

Идентификационные токены конфиденциальны и могут быть использованы не по назначению в случае перехвата. Необходимо обеспечить безопасную обработку этих токенов, передавая их только по протоколу HTTPS и используя только данные POST или в заголовках запросов. Если вы храните идентификационные токены на сервере, вы также должны обеспечить их безопасное хранение.

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

Проверка идентификационного токена требует нескольких шагов:

1. Убедитесь, что идентификационный токен правильно подписан эмитентом. Токены, выпущенные Google, подписываются с использованием одного из сертификатов, найденных в URI, указанном в значении метаданных jwks_uri документа Discovery .
2. Убедитесь, что значение утверждения iss в токене ID равно https://accounts.google.com или accounts.google.com .
3. Убедитесь, что значение утверждения aud в токене ID равно идентификатору клиента вашего приложения.
4. Убедитесь, что срок действия ( exp ) токена ID не истек.
5. Если вы указали значение параметра hd в запросе, убедитесь, что токен ID имеет утверждение hd , которое соответствует принятому домену, связанному с организацией Google Cloud.

Шаги 2–5 включают только сравнение строк и дат, что довольно просто, поэтому мы не будем их здесь подробно описывать.

Первый шаг более сложен и включает проверку криптографической подписи. Для отладки вы можете использовать конечную точку Google tokeninfo для сравнения с локальной обработкой, реализованной на вашем сервере или устройстве. Предположим, что значение вашего токена идентификатора — XYZ123 . Затем вы разыменуете URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Если подпись токена верна, ответ будет представлять собой полезную нагрузку JWT в виде декодированного JSON-объекта.

Конечная точка tokeninfo полезна для отладки, но в производственных целях извлеките открытые ключи Google из конечной точки keys и выполните локальную проверку. URI ключей следует извлечь из документа Discovery, используя значение метаданных jwks_uri . Запросы к конечной точке отладки могут быть ограничены или подвержены периодическим ошибкам.

Поскольку Google меняет свои открытые ключи лишь изредка, вы можете кэшировать их с помощью директив кэширования HTTP-ответа и, в подавляющем большинстве случаев, выполнять локальную валидацию гораздо эффективнее, чем с помощью конечной точки tokeninfo . Эта валидация требует извлечения и анализа сертификатов, а также выполнения соответствующих криптографических вызовов для проверки подписи. К счастью, для этого существуют хорошо отлаженные библиотеки на самых разных языках (см. jwt.io ).

Получение информации профиля пользователя

Для получения дополнительной информации о профиле пользователя вы можете использовать токен доступа (который ваше приложение получает во время процесса аутентификации ) и стандарт OpenID Connect :

1. Чтобы соответствовать требованиям OpenID, необходимо включить значения области действия openid profile в запрос на аутентификацию .

   Если вы хотите включить адрес электронной почты пользователя, вы можете указать дополнительное значение области действия email . Чтобы указать и profile , и email , вы можете включить следующий параметр в URI запроса аутентификации:

   scope=openid%20profile%20email

2. Добавьте свой токен доступа в заголовок авторизации и отправьте HTTPS-запрос GET к конечной точке userinfo, которую следует получить из документа Discovery, используя значение метаданных userinfo_endpoint . Ответ userinfo содержит информацию о пользователе, как описано в OpenID Connect Standard Claims и значении метаданных claims_supported документа Discovery. Пользователи или их организации могут предоставлять или не предоставлять определённые поля, поэтому вы можете получить информацию не по всем полям для ваших авторизованных областей доступа.

Документ Discovery

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

Для упрощения реализации и повышения гибкости OpenID Connect позволяет использовать «документ обнаружения» — JSON-документ, находящийся в известном месте и содержащий пары «ключ-значение», которые содержат подробную информацию о конфигурации поставщика OpenID Connect, включая URI конечных точек авторизации, токена, отзыва, информации о пользователе и открытых ключей. Документ обнаружения для сервиса OpenID Connect от Google можно получить здесь:

https://accounts.google.com/.well-known/openid-configuration

Чтобы использовать службы OpenID Connect от Google, необходимо жёстко прописать в коде приложения URI Discovery-document ( https://accounts.google.com/.well-known/openid-configuration ). Приложение извлекает документ, применяет правила кэширования в ответе, а затем при необходимости извлекает из него URI конечных точек. Например, для аутентификации пользователя ваш код извлечёт значение метаданных authorization_endpoint ( https://accounts.google.com/o/oauth2/v2/auth в примере ниже) в качестве базового URI для запросов аутентификации, отправляемых в Google.

Вот пример такого документа; названия полей соответствуют именам, указанным в OpenID Connect Discovery 1.0 (их значения см. в этом документе). Значения приведены исключительно в качестве иллюстрации и могут измениться, хотя они и скопированы из последней версии документа Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

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

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

Следующие клиентские библиотеки облегчают реализацию OAuth 2.0, интегрируя с популярными рамками:

• Google APIS клиентская библиотека для Java
• Клиентская библиотека Google APIS для Python
• Google APIS клиентская библиотека для .net
• Google APIS клиентская библиотека для Ruby
• Клиентская библиотека Google APIS для PHP
• Библиотека OAuth 2.0 для Google Web Toolkit
• Google Toolbox для контроллеров Mac OAuth 2.0

OpenID Connect Compliance

Система аутентификации OAuth от Google 2.0 поддерживает необходимые функции спецификации ядра Connect Connect . Любой клиент, который предназначен для работы с OpenID Connect, должен взаимодействовать с этой службой (за исключением объекта OpenID запроса ).