OpenID Connect

Конечная точка OpenID Connect от Google сертифицирована OpenID.

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

Настройка OAuth 2.0

Чтобы использовать систему аутентификации OAuth 2.0 от Google для входа пользователей, необходимо настроить проект в консоли Google Cloud. Это позволит получить учетные данные OAuth 2.0, задать URI перенаправления и при необходимости настроить информацию о бренде, которую пользователи видят в окне запроса доступа. Вы также можете использовать Cloud Console, чтобы создать сервисный аккаунт, включить платежи, настроить фильтрацию и выполнить другие задачи. Подробную информацию можно найти в Справке по консоли Google Cloud.

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

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

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

Вы также можете посмотреть идентификатор клиента и секретный код клиента на странице Clients (Клиенты) в Cloud Console.

  1. Перейдите на страницу Клиенты.
  2. Нажмите на название клиента или на значок карандаша (). Идентификатор клиента и секретный код находятся в верхней части страницы.

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

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

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

  1. Перейдите на страницу Клиенты.
  2. Нажмите на клиента.
  3. Посмотрите или измените URI переадресации.

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

Настройте окно запроса доступа

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

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

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

  1. Откройте страницу Брендинг в консоли Google Cloud.
  2. Выберите существующий проект или создайте новый.
  3. Заполните форму и нажмите Сохранить.

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

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

Доступ к сервису

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

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

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

Аутентификация пользователя включает получение токена идентификатора и его проверку. Токены идентификации – это стандартизированная функция OpenID Connect, предназначенная для передачи утверждений идентификации в интернете.

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

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

Процесс на сервере

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

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

1. Создание токена состояния для защиты от подделки

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

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

В следующем примере кода показано, как генерировать уникальные токены сеансов.

PHP

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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
));

Java

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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);

Python

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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, который можно получить на странице клиентов в Cloud Console.
  • response_type, которое в базовом запросе на обработку кода авторизации должно быть равно code. Подробнее: response_type.
  • scope, которое в базовом запросе должно иметь значение openid email. Подробнее: scope.
  • redirect_uri – это конечная точка HTTP на вашем сервере, которая будет получать ответ от Google. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили на странице "Учетные данные" в Cloud Console. Если это значение не совпадает с авторизованным URI, запрос завершится ошибкой redirect_uri_mismatch.
  • state должен включать значение уникального токена сеанса для защиты от подделки, а также любую другую информацию, необходимую для восстановления контекста, когда пользователь возвращается в ваше приложение, например начальный URL. Подробнее: state.
  • nonce – случайное значение, сгенерированное вашим приложением. Оно позволяет защитить приложение от атак повторного воспроизведения.
  • login_hint может быть адресом электронной почты пользователя или строкой sub, которая эквивалентна идентификатору Google пользователя. Если вы не укажете login_hint, а пользователь войдет в аккаунт, в окне запроса доступа появится запрос на предоставление вашему приложению адреса электронной почты пользователя. Подробнее об этом рассказывается в статье login_hint.
  • Используйте параметр hd, чтобы оптимизировать процесс OpenID Connect для пользователей определенного домена, связанного с организацией Google Workspace или Cloud (подробнее: hd).

Ниже приведен пример полного 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//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

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

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

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

https://developers.google.com/oauthplayground?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

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

В следующем коде показано, как подтвердить токены сеанса, созданные на шаге 1.

PHP

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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);
}

Java

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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.");
}

Python

Чтобы использовать этот пример, необходимо скачать клиентскую библиотеку API Google для 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 отправляется в конечную точку токена, которую необходимо получить из документа обнаружения с помощью значения метаданных token_endpoint. В приведенном ниже обсуждении предполагается, что конечная точка – https://oauth2.googleapis.com/token. В теле запроса POST должны быть указаны следующие параметры:

Поля
code Код авторизации, возвращенный исходным запросом.
client_id Идентификатор клиента, который вы получили на странице Clients (Клиенты) в Cloud Console, как описано в разделе Получение учетных данных OAuth 2.0.
client_secret Секретный код клиента, который вы получили на странице клиентов в Cloud Console, как описано в разделе Получение учетных данных OAuth 2.0.
redirect_uri Авторизованный URI переадресации для указанного client_id, заданный на странице Clients (Клиенты) в Cloud Console, как описано в разделе Как задать 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//developers.google.com/oauthplayground&
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. Подробнее о токенах обновления…

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

Токен идентификации – это JWT (веб-токен JSON), то есть криптографически подписанный объект JSON, закодированный по алгоритму Base64. Обычно перед использованием токена идентификации необходимо проверить его. Однако в данном случае вы обмениваетесь данными напрямую с Google по каналу HTTPS без посредников и используете секретный код клиента для аутентификации в Google. Поэтому вы можете быть уверены, что полученный токен действительно отправлен Google и действителен. Если сервер передает токен идентификатора другим компонентам приложения, они должны проверять токен перед использованием.

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

Полезная нагрузка токена идентификации

Токен идентификации – это объект 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": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

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

Получить данные предоставлены Описание
aud Всегда Аудитория, для которой предназначен этот токен идентификации. Это должен быть один из идентификаторов клиента OAuth 2.0 вашего приложения.
exp Всегда Время, после которого токен идентификатора не должен приниматься. Указывается в формате Unix-времени (целое число секунд).
iat Всегда Время выдачи токена идентификации. Указывается в формате Unix-времени (целое число секунд).
iss Всегда Идентификатор эмитента, отправившего ответ. Всегда https://accounts.google.com или accounts.google.com для токенов идентификации Google.
sub Всегда Идентификатор пользователя, уникальный для всех аккаунтов Google и никогда не используемый повторно. В разное время с аккаунтом Google могут быть связаны разные адреса электронной почты, но значение sub никогда не меняется. Используйте sub в своем приложении в качестве уникального идентификатора пользователя. Максимальная длина – 255 символов ASCII с учетом регистра.
amr Массив JSON со строками, которые идентифицируют способы аутентификации, используемые для входа в аккаунт Google. Если присутствует, включает одно или несколько из следующих возможных значений [IANA.AMR]:
  • hwk использовался аппаратный ключ
  • mfa Многофакторная аутентификация завершена
  • pwd использован пароль
  • sms SMS-сообщение было использовано для подтверждения.
  • swk Использовался программный ключ, например ключ доступа.
  • tel подтверждение по телефону
Присутствует, только если утверждение amr включено в запрос на аутентификацию и активировано в настройках.
auth_time Время, когда была выполнена аутентификация пользователя. Число JSON, представляющее количество секунд, прошедших с начала эпохи Unix (00:00:00 1 января 1970 года по всемирному координированному времени). Предоставляется, если утверждение auth_time включено в запрос на аутентификацию и активировано в настройках.
at_hash Хеш токена доступа. Подтверждает, что токен доступа связан с токеном идентификации. Если токен идентификатора выпущен со значением access_token в потоке сервера, это утверждение всегда включается. Это утверждение можно использовать в качестве альтернативного механизма защиты от атак с межсайтовой подделкой запросов, но если вы выполните шаг 1 и шаг 3, проверять токен доступа не потребуется.
azp client_id уполномоченного представителя. Это утверждение необходимо только в том случае, если сторона, запрашивающая токен идентификатора, не совпадает с аудиторией токена идентификатора. Например, в Google это может быть гибридное приложение, в котором веб-приложение и приложение для Android имеют разные client_id OAuth 2.0, но используют один и тот же проект API Google.
email Адрес электронной почты пользователя. Предоставляется, только если в запрос включена область действия email. Значение этого утверждения может быть неуникальным для аккаунта и со временем меняться, поэтому не используйте его в качестве основного идентификатора для связи с записью пользователя. Вы также не можете полагаться на домен утверждения email для идентификации пользователей Google Workspace или организаций Cloud. Вместо этого используйте утверждение hd.
email_verified True, если адрес электронной почты пользователя подтвержден; в противном случае – false.
family_name Фамилия пользователя. Может предоставляться, если есть утверждение name.
given_name Имя или имена пользователя. Может предоставляться, если есть утверждение name.
hd Домен, связанный с организацией Google Workspace или Cloud, к которой относится пользователь. Предоставляется, только если пользователь принадлежит к организации Google Cloud. Это утверждение необходимо проверять, если доступ к ресурсу предоставляется только участникам определенных доменов. Отсутствие этого утверждения указывает на то, что аккаунт не принадлежит домену, размещенному в Google.
locale Региональные настройки пользователя, представленные языковым тегом BCP 47. Может предоставляться, если есть утверждение name.
name Полное имя пользователя в формате, подходящем для отображения. Может предоставляться в следующих случаях:
  • Область действия запроса включала строку "profile".
  • Токен идентификации возвращается при обновлении токена.

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

nonce Значение nonce, предоставленное вашим приложением в запросе на аутентификацию. Чтобы защититься от атак повторного воспроизведения, используйте это значение только один раз.
picture URL фото профиля пользователя. Может предоставляться в следующих случаях:
  • Область действия запроса включала строку "profile".
  • Токен идентификации возвращается при обновлении токена.

Если утверждения picture присутствуют, вы можете использовать их для обновления записей пользователей в приложении. Обратите внимание, что наличие этого утверждения не гарантируется.

profile URL страницы профиля пользователя. Может предоставляться в следующих случаях:
  • Область действия запроса включала строку "profile".
  • Токен идентификации возвращается при обновлении токена.

Если утверждения profile присутствуют, вы можете использовать их для обновления записей пользователей в приложении. Обратите внимание, что наличие этого утверждения не гарантируется.

6. Выполните аутентификацию пользователя

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

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

Дополнительные темы

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

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

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

Токены обновления

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

Что необходимо учитывать

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

Подробнее о том, как обновить токен доступа (офлайн-режим)…

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

Подробнее о параметре prompt рассказывается в разделе prompt таблицы Параметры URI аутентификации.

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

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

Параметр Обязательно Описание
client_id (обязательно) Строка идентификатора клиента, которую вы получаете на странице клиентов в Cloud Console, как описано в разделе Получение учетных данных OAuth 2.0.
nonce (обязательно) Случайное значение, сгенерированное приложением и позволяющее защититься от повторного воспроизведения.
response_type (обязательно) Если значение равно code, запускается базовая обработка кода авторизации, для которой требуется POST к конечной точке токена, чтобы получить токены. Если значение равно token id_token или id_token token, запускается неявное предоставление доступа, при котором для получения токенов из идентификатора URI #fragment требуется использовать JavaScript в URI перенаправления.
redirect_uri (обязательно) Определяет, куда отправляется ответ. Значение этого параметра должно точно совпадать с одним из авторизованных значений перенаправления, заданных вами в Cloud Console на странице клиентов (включая схему HTTP или HTTPS, регистр и косую черту в конце, если она есть).
scope (обязательно)

Параметр scope должен начинаться со значения openid, а затем включать значение profile, email или оба.

Если присутствует значение области действия profile, токен идентификатора может включать утверждения profile пользователя по умолчанию (но это не гарантируется).

Если указана область действия email, то токен идентификации включает утверждения email и email_verified.

Помимо этих областей действия, относящихся к OpenID, аргумент scope может включать и другие значения. Все значения области действия должны быть разделены пробелами. Например, если вам нужен доступ к отдельным файлам на Google Диске пользователя, параметр scope может быть таким: 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.
claims (Необязательно) Параметр claims используется для указания одного или нескольких необязательных полей, которые должны быть включены в конечную точку userinfo или типы ответов токена идентификатора запроса аутентификации. Значение представляет собой объект JSON, содержащий тип ответа и запрошенные утверждения. Серверы Google принимают следующие запросы на заявки:
Запросы на получение
amr Запросите метод, который использовался при последней аутентификации пользователя. Чтобы в ответе на запрос токена идентификации возвращалось поле amr, добавьте параметр запроса claims: claims={"id_token":{"amr":{"essential":true}}} Его необходимо включить в настройках.
auth_time Запросить время последней аутентификации пользователя. Чтобы в ответе на запрос токена идентификации возвращалось поле auth_time, добавьте параметр запроса claims: claims={"id_token":{"auth_time":{"essential":true}}} Его необходимо включить в настройках.
display (Необязательно) Строка ASCII, указывающая, как сервер авторизации отображает страницы пользовательского интерфейса для аутентификации и согласия. Следующие значения указываются и принимаются серверами Google, но не влияют на работу протокола: page, popup, touch и wap.
hd (Необязательно)

Упростите процесс входа в аккаунты, принадлежащие организации Google Cloud. Указав домен организации Google Cloud (например, mycollege.edu), вы можете сообщить, что интерфейс выбора аккаунта должен быть оптимизирован для аккаунтов в этом домене. Чтобы оптимизировать работу для всех корпоративных аккаунтов организации Google Cloud, а не только для одного домена, укажите в качестве значения звездочку (*): hd=*.

Не полагайтесь на эту оптимизацию интерфейса для управления доступом к приложению, поскольку клиентские запросы можно изменить. Обязательно проверьте, что возвращенный токен идентификатора имеет значение утверждения hd, соответствующее вашим ожиданиям (например, mycolledge.edu). В отличие от параметра запроса, утверждение hd токена идентификатора содержится в токене безопасности от Google, поэтому этому значению можно доверять.

include_granted_scopes (Необязательно) Если этот параметр имеет значение true и запрос на авторизацию одобрен, авторизация будет включать все предыдущие авторизации, предоставленные этому пользователю или приложению для других областей. Подробнее о добавочной авторизации…

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

login_hint (Необязательно) Если приложение знает, какого пользователя оно пытается аутентифицировать, оно может передать этот параметр в качестве подсказки серверу аутентификации. При передаче этой подсказки окно выбора аккаунта не показывается, а поле адреса электронной почты в форме входа заполняется автоматически или выбирается нужный сеанс (если пользователь использует систему множественного входа). Это позволяет избежать проблем, которые возникают, если приложение входит в неправильный аккаунт пользователя. Значением может быть адрес электронной почты или строка sub, которая эквивалентна идентификатору Google пользователя.
prompt (Необязательно) Список строковых значений, разделенных пробелами, который указывает, запрашивает ли сервер авторизации у пользователя повторную аутентификацию и согласие. Возможные значения:
  • none

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

  • consent

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

  • select_account

    Сервер авторизации предлагает пользователю выбрать аккаунт. Это позволяет пользователю, у которого есть несколько аккаунтов на сервере авторизации, выбрать один из них, для которого у него могут быть текущие сеансы.

Если значение не указано и пользователь ранее не разрешал доступ, ему будет показано окно запроса доступа.

hl (Необязательно) Языковой тег BCP 47, который используется для указания языка интерфейса на экранах входа, выбора аккаунта и запроса согласия. Если этот параметр не указан, по умолчанию используется язык, заданный в аккаунте Google или настройках браузера пользователя. Например, чтобы интерфейс был на британском английском, задайте значение en-GB.

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

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

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

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

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

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

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

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

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

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

Документ Discovery

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

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

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

Чтобы использовать сервисы OpenID Connect от Google, необходимо задать в коде приложения URI discovery-документа (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 (их значения можно найти в этом документе). Значения приведены исключительно в качестве примера и могут меняться, хотя они скопированы из недавней версии фактического discovery-документа рекомендаций Google:

{
  "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 за счет интеграции с популярными фреймворками:

Соответствие OpenID Connect

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