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.
- Перейдите на страницу Клиенты.
- Нажмите на название клиента или на значок карандаша (create). Идентификатор клиента и секретный код находятся в верхней части страницы.
Как настроить URI перенаправления
URI перенаправления, который вы задаете в Cloud Console, определяет, куда Google отправляет ответы на ваши запросы аутентификации.
Чтобы создать, посмотреть или изменить URI перенаправления для определенных учетных данных OAuth 2.0, выполните следующие действия:
- Перейдите на страницу Клиенты.
- Нажмите на клиента.
- Посмотрите или измените URI переадресации.
Если на странице "Клиенты" нет ни одного клиента, значит у вашего проекта нет учетных данных OAuth. Чтобы создать его, нажмите Создать клиента.
Настройте окно запроса доступа
При аутентификации OAuth 2.0 пользователи видят окно запроса доступа, в котором описаны передаваемые данные и действующие условия. Например, при входе в систему пользователю может быть предложено предоставить вашему приложению доступ к его адресу электронной почты и основной информации об аккаунте. Запрос на доступ к этой информации отправляется с помощью параметра scope, который приложение включает в запрос на аутентификацию. Вы также можете использовать области действия, чтобы запрашивать доступ к другим API Google.
На экране запроса согласия также представлена информация о бренде, например название продукта, логотип и URL главной страницы. Вы можете управлять информацией о бренде в Cloud Console.
Чтобы включить окно запроса доступа для проекта, выполните следующие действия:
- Откройте страницу Брендинг в консоли Google Cloud.
- Выберите существующий проект или создайте новый.
- Заполните форму и нажмите Сохранить.
Ниже показано, как выглядит диалоговое окно для получения согласия пользователей, когда в запросе присутствуют области действия OAuth 2.0 и Google Диска. (Это стандартное диалоговое окно было создано с помощью Google OAuth 2.0 Playground, поэтому оно не содержит информацию о бренде, которая была бы задана в Cloud Console.)
Доступ к сервису
Google и сторонние разработчики предоставляют библиотеки, которые можно использовать для реализации аутентификации пользователей и получения доступа к API Google. Примеры: Сервисы идентификации Google и клиентские библиотеки Google, доступные для различных платформ.
Если вы не хотите использовать библиотеку, следуйте инструкциям в оставшейся части этого документа, в которой описываются потоки HTTP-запросов, лежащие в основе доступных библиотек.
Аутентификация пользователя
Аутентификация пользователя включает получение токена идентификатора и его проверку. Токены идентификации – это стандартизированная функция OpenID Connect, предназначенная для передачи утверждений идентификации в интернете.
Наиболее распространенные подходы к аутентификации пользователя и получению токена идентификатора называются "server flow" и "implicit flow". Серверный поток позволяет бэкенд-серверу приложения подтверждать личность пользователя, который работает с браузером или мобильным устройством. Неявное предоставление доступа используется, когда клиентскому приложению (обычно это приложение JavaScript, работающее в браузере) требуется прямой доступ к API, а не через бэкенд-сервер.
В этом документе описывается, как выполнить аутентификацию пользователя на сервере. Неявное предоставление доступа значительно сложнее из-за рисков безопасности, связанных с обработкой и использованием токенов на стороне клиента. Если вам нужно реализовать неявное предоставление доступа, настоятельно рекомендуем использовать сервисы идентификации Google.
Процесс на сервере
Чтобы приложение могло использовать эти протоколы и выполнять аутентификацию пользователей, настройте его в Cloud Console. Когда пользователь пытается войти с аккаунтом Google, вам нужно:
- Создание токена состояния для защиты от подделки
- Отправка запроса на аутентификацию в Google
- Подтвердите токен состояния для защиты от подделки
- Обмен
codeна токен доступа и токен идентификатора - Как получить информацию о пользователе из токена идентификатора
- Аутентификация пользователя
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 |
(необязательно)
Это поле присутствует, только если в запросе на аутентификацию для параметра |
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]:
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 |
Полное имя пользователя в формате, подходящем для отображения. Может предоставляться в следующих случаях:
Если утверждения |
|
nonce |
Значение nonce, предоставленное вашим приложением в запросе на аутентификацию.
Чтобы защититься от атак повторного воспроизведения, используйте это значение только один раз. |
|
picture |
URL фото профиля пользователя. Может предоставляться в следующих случаях:
Если утверждения |
|
profile |
URL страницы профиля пользователя. Может предоставляться в следующих случаях:
Если утверждения |
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, аргумент scope может включать и другие значения. Все значения области действия должны быть разделены пробелами. Например, если вам нужен доступ к отдельным файлам на Google Диске пользователя, параметр scope может быть таким: Информацию о доступных областях действия можно найти в статье Области действия OAuth 2.0 для API Google или в документации по API Google, который вы хотите использовать. |
||||||
state |
(необязательно, но настоятельно рекомендуется) | Непрозрачная строка, которая передается в протоколе туда и обратно. Это значит, что она возвращается как параметр URI в базовом потоке и в идентификаторе URI
|
||||||
access_type |
(Необязательно) | Допустимые значения: offline и online. Результат описан в разделе Офлайн-режим. Если запрашивается токен доступа, клиент не получит токен обновления, пока не будет указано значение offline. |
||||||
claims |
(Необязательно) | Параметр claims используется для указания одного или нескольких необязательных полей, которые должны быть включены в конечную точку userinfo или типы ответов токена идентификатора запроса аутентификации. Значение представляет собой объект JSON, содержащий тип ответа и запрошенные утверждения. Серверы Google принимают следующие запросы на заявки:
|
||||||
display |
(Необязательно) | Строка ASCII, указывающая, как сервер авторизации отображает страницы пользовательского интерфейса для аутентификации и согласия. Следующие значения указываются и принимаются серверами Google, но не влияют на работу протокола: page, popup, touch и wap. |
||||||
hd |
(Необязательно) | Упростите процесс входа в аккаунты, принадлежащие организации Google Cloud. Указав домен организации Google Cloud (например, mycollege.edu), вы можете сообщить, что интерфейс выбора аккаунта должен быть оптимизирован для аккаунтов в этом домене. Чтобы оптимизировать работу для всех корпоративных аккаунтов организации Google Cloud, а не только для одного домена, укажите в качестве значения звездочку ( Не полагайтесь на эту оптимизацию интерфейса для управления доступом к приложению, поскольку клиентские запросы можно изменить. Обязательно проверьте, что возвращенный токен идентификатора имеет значение утверждения |
||||||
include_granted_scopes |
(Необязательно) | Если этот параметр имеет значение true и запрос на авторизацию одобрен, авторизация будет включать все предыдущие авторизации, предоставленные этому пользователю или приложению для других областей. Подробнее о добавочной авторизации…
Обратите внимание, что вы не можете использовать пошаговую авторизацию в процессе установки приложения. |
||||||
login_hint |
(Необязательно) | Если приложение знает, какого пользователя оно пытается аутентифицировать, оно может передать этот параметр в качестве подсказки серверу аутентификации. При передаче этой подсказки окно выбора аккаунта не показывается, а поле адреса электронной почты в форме входа заполняется автоматически или выбирается нужный сеанс (если пользователь использует систему множественного входа). Это позволяет избежать проблем, которые возникают, если приложение входит в неправильный аккаунт пользователя.
Значением может быть адрес электронной почты или строка sub, которая эквивалентна идентификатору Google пользователя. |
||||||
prompt |
(Необязательно) | Список строковых значений, разделенных пробелами, который указывает, запрашивает ли сервер авторизации у пользователя повторную аутентификацию и согласие. Возможные значения:
Если значение не указано и пользователь ранее не разрешал доступ, ему будет показано окно запроса доступа. |
||||||
hl |
(Необязательно) | Языковой тег BCP 47, который используется для указания языка интерфейса на экранах входа, выбора аккаунта и запроса согласия. Если этот параметр не указан, по умолчанию используется язык, заданный в аккаунте Google или настройках браузера пользователя. Например, чтобы интерфейс был на британском английском, задайте значение en-GB.
|
||||||
Проверка токена идентификации
Вам необходимо проверять все идентификационные токены на своем сервере, если вы не уверены, что они получены непосредственно от Google. Например, сервер должен проверять подлинность всех токенов идентификации, которые он получает от клиентских приложений.
Ниже приведены распространенные ситуации, в которых вы можете отправлять токены идентификатора на свой сервер:
- Отправка токенов идентификации с запросами, требующими аутентификации. Токены идентификации содержат информацию о пользователе, который отправляет запрос, и о клиенте, которому был предоставлен токен.
Токены идентификации содержат конфиденциальные данные и могут быть использованы злоумышленниками, если будут перехвачены. Вы должны обеспечить безопасную обработку этих токенов, передавая их только по протоколу HTTPS и только с использованием данных POST или в заголовках запросов. Если вы храните токены идентификации на сервере, то должны обеспечить их безопасность.
Токены идентификации удобны тем, что их можно передавать между разными компонентами приложения. Эти компоненты могут использовать токен идентификации как упрощенный механизм аутентификации приложения и пользователя. Однако прежде чем использовать информацию из токена идентификации или полагаться на него как на подтверждение того, что пользователь прошел аутентификацию, вы должны проверить его.
Проверка токена идентификации состоит из нескольких шагов:
- Убедитесь, что токен идентификатора правильно подписан эмитентом. Токены, выпущенные Google, подписываются с помощью одного из сертификатов, которые можно найти по URI, указанному в значении метаданных
jwks_uriдокумента обнаружения. - Убедитесь, что значение утверждения
issв токене идентификации равноhttps://accounts.google.comилиaccounts.google.com. - Убедитесь, что значение утверждения
audв токене идентификатора совпадает с идентификатором клиента вашего приложения. - Убедитесь, что срок действия (утверждение
exp) токена идентификации не истек. - Если в запросе указано значение параметра 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.
Чтобы обеспечить соответствие стандарту OpenID, необходимо включить значения области действия
openid profileв запрос на аутентификацию.Если вы хотите, чтобы в ответ был включен адрес электронной почты пользователя, укажите дополнительное значение области действия
email. Чтобы указать иprofile, иemail, добавьте в URI запроса на аутентификацию следующий параметр:scope=openid%20profile%20emailДобавьте токен доступа в заголовок авторизации и отправьте 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 за счет интеграции с популярными фреймворками:
- Клиентская библиотека API Google для Java
- Клиентская библиотека API Google для Python
- Клиентская библиотека API Google для .NET
- Клиентская библиотека API Google для Ruby
- Клиентская библиотека API Google для PHP
- Библиотека OAuth 2.0 для Google Web Toolkit
- Контроллеры OAuth 2.0 в Google Toolbox для Mac
Соответствие OpenID Connect
Система аутентификации Google OAuth 2.0 поддерживает обязательные функции спецификации OpenID Connect Core. Любой клиент, предназначенный для работы с OpenID Connect, должен взаимодействовать с этим сервисом (за исключением объекта запроса OpenID).
