На этой справочной странице описаны конечные точки API, которые ваш сервис должен реализовать для поддержки привязки учетных записей к Google. Это включает в себя привязку учетных записей на основе OAuth , упрощенную привязку учетных записей и переключение приложений .
Предварительные требования и стандарты
Для успешной реализации этих конечных точек ваш сервис должен соответствовать следующим стандартам:
- OAuth 2.0 : соответствует RFC 6749 .
- Отзыв токенов : соответствует RFC 7009 .
- JSON Web Tokens (JWT) : Соответствует RFC 7519 (необходим для упрощенной привязки).
- HTTPS : Все конечные точки должны обслуживаться через защищенное HTTPS-соединение.
Конечная точка авторизации
Точка авторизации отвечает за аутентификацию пользователей и получение их согласия на привязку их учетных записей к Google.
- URL: Настраивается в консоли действий или консоли Google Cloud.
- Метод:
GET
Параметры запроса
| Параметры | Описание |
|---|---|
client_id | Идентификатор клиента, который вы присвоили Google. |
redirect_uri | URL-адрес, на который вы отправляете ответ на этот запрос. |
state | Бухгалтерское значение, передаваемое обратно в Google без изменений в URI перенаправления. |
response_type | Это должен быть code для процесса авторизации. |
scope | (Необязательно) Разделенный пробелами список областей действия данных, запрашиваемых Google. |
user_locale | (Необязательно) Языковые настройки учетной записи Google, заданные с помощью языкового тега BCP-47 (например, en-US ). |
Конечная точка обмена токенов
Этот конечный пункт отвечает за обмен кодов авторизации на токены и обновление просроченных токенов доступа.
- URL: Настраивается в консоли действий или консоли Google Cloud.
- Метод:
POST - Content-Type:
application/x-www-form-urlencoded
Код авторизации обмена токенов
В первоначальном запросе на обмен токенов используются следующие параметры.
Параметры запроса
| Параметры | Описание |
|---|---|
client_id | Идентификатор клиента, который вы присвоили Google. |
client_secret | Секретный ключ клиента, который вы присвоили Google. |
grant_type | Должно быть authorization_code . |
code | Код авторизации, полученный от конечной точки авторизации. |
redirect_uri | Тот же URI перенаправления, что и в первоначальном запросе. |
Обменяйте токен обновления на токен доступа.
При обновлении токена доступа используются следующие параметры.
Параметры запроса
| Параметры | Описание |
|---|---|
client_id | Идентификатор клиента, который вы присвоили Google. |
client_secret | Секретный ключ клиента, который вы присвоили Google. |
grant_type | Должно быть refresh_token . |
refresh_token | Токен обновления, ранее выданный Google. |
Ответ (JSON)
Возвращает успешный ответ с JSON-объектом в теле HTTPS-запроса.
- Статус HTTP:
200 OK - Content-Type:
application/json;charset=UTF-8
| Поля | Описание |
|---|---|
token_type | Обязательно. Должен быть bearer . |
access_token | Обязательный параметр. Кратковременный токен, используемый для доступа к API вашего сервиса. |
refresh_token | Требуется для параметра authorization_code grant_type . Долгосрочный токен, используемый для получения новых токенов доступа. |
expires_in | Обязательно. Оставшийся срок действия токена доступа в секундах. |
Ответы об ошибках
Если запрос к конечной точке получения токена не удается, верните ошибку HTTP 400 Bad Request вместе с JSON-ответом, содержащим следующие поля:
- Статус HTTP:
400 Bad Request - Content-Type:
application/json;charset=UTF-8
| Поля ошибок (JSON) | Описание |
|---|---|
error | Обязательно. Должно быть invalid_grant . |
error_description | (Необязательно) Текст, удобочитаемый для восприятия, содержащий дополнительную информацию. |
Обработка оптимизированных намерений создания ссылок
Если ваш сервис поддерживает упрощенную привязку учетных записей (OAuth с входом через Google), ваша конечная точка обмена токенами должна дополнительно поддерживать утверждения JSON Web Token (JWT) и реализовывать намерения check , create и get .
В этих запросах используются следующие параметры:
Параметры запроса
| Параметры | Описание |
|---|---|
intent | Запрашиваемый конкретный упрощенный механизм связывания: check , get или create . |
grant_type | Для таких запросов этот параметр всегда имеет значение urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion | JSON Web Token (JWT) — это подписанное подтверждение личности пользователя Google. JWT содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя. Ваш сервер должен проверить этот JWT, используя критерии, указанные в разделе «Проверка JWT» . |
client_id | Идентификатор клиента, который вы присвоили Google. |
client_secret | Секретный ключ клиента, который вы присвоили Google. |
scope | Необязательно: любые области действия (scopes), которые вы настроили для запросов к Google у пользователей. Обычно присутствуют в интентах get и create данных. |
response_type | Для create намерения требуется: необходимо установить значение token . |
Проверка JWT
Для обеспечения безопасности упрощенной привязки ваш сервер должен проверять assertion (JWT) по следующим критериям:
- Подпись : Проверьте подпись, используя открытые ключи Google (доступны по адресу JWK-адрес Google ).
- Эмитент (
iss) : Должен бытьhttps://accounts.google.com. - Аудитория (
aud) : Должна совпадать с идентификатором клиента Google API, присвоенным вашей интеграции. - Срок действия (
exp) : Должен быть в будущем.
Ответ на вопрос о намерении check
Запрос с intent=check проверяет, существует ли учетная запись Google (идентифицированная по полю sub или email в декодированном утверждении JWT) в вашей базе данных пользователей.
- Статус HTTP:
200 OK(Учетная запись найдена) или404 Not Found(Учетная запись не найдена) - Content-Type:
application/json;charset=UTF-8
| Поля | Описание |
|---|---|
account_found | Обязательно. true если учетная запись существует, false в противном случае. |
Ответ на запрос get намерения
Запрос с intent=get запрашивает токен доступа для существующей учетной записи Google.
- Статус HTTP:
200 OK - Content-Type:
application/json;charset=UTF-8
В успешном ответе JSON-объект использует ту же структуру, что и в успешном стандартном ответе от службы обмена токенов (возвращает access_token , refresh_token и т. д.).
Если связать учетную запись не удается, возвращается ошибка HTTP 401.
- Статус HTTP:
401 Unauthorized - Content-Type:
application/json;charset=UTF-8
| Поля ошибок (JSON) | Описание |
|---|---|
error | Обязательно. Должно быть linking_error . |
login_hint | (Необязательно) Адрес электронной почты пользователя, который будет передан в резервный поток аутентификации OAuth. |
Ответ на запрос create намерения
Запрос с intent=create запрашивает создание новой учетной записи пользователя с использованием информации, предоставленной в JWT.
- Статус HTTP:
200 OK - Content-Type:
application/json;charset=UTF-8
В успешном ответе JSON-объект использует ту же структуру, что и в успешном стандартном ответе от службы обмена токенов (возвращает access_token , refresh_token и т. д.).
Если пользователь уже существует, возвращается ошибка HTTP 401, предлагающая пользователю связать свою существующую учетную запись.
- Статус HTTP:
401 Unauthorized - Content-Type:
application/json;charset=UTF-8
| Поля ошибок (JSON) | Описание |
|---|---|
error | Обязательно. Должно быть linking_error . |
login_hint | Адрес электронной почты пользователя, который будет передан в резервный поток аутентификации OAuth. |
Конечная точка UserInfo (необязательно)
Используется для получения основной информации профиля связанного пользователя, как указано в спецификации OpenID Connect Core 1.0 . Это необходимо для таких функций, как «Упрощенная привязка» или «Вход в систему одним касанием».
- Метод:
GET - Аутентификация:
Authorization: Bearer ACCESS_TOKEN
Ответ (JSON)
Возвращает успешный ответ с JSON-объектом в теле HTTPS-запроса.
- Статус HTTP:
200 OK - Content-Type:
application/json;charset=UTF-8
Поля ответа
| Поля | Описание |
|---|---|
sub | Обязательно. Уникальный идентификатор, который идентифицирует пользователя в вашей системе. |
email | Обязательно. Адрес электронной почты пользователя. |
email_verified | Обязательно. Логическое значение, указывающее, подтвержден ли адрес электронной почты. |
given_name | (Необязательно) Имя пользователя. |
family_name | (Необязательно) Фамилия пользователя. |
name | (Необязательно) Полное имя пользователя. |
picture | (Необязательно) URL-адрес фотографии профиля пользователя. |
Ответы об ошибках
Если токен доступа недействителен или истек срок его действия, верните ошибку HTTP 401 Unauthorized . Также следует включить заголовок ответа WWW-Authenticate .
Любой неудачный ответ (4xx или 5xx), полученный в процессе привязки, считается невосстановимым. В таких случаях Google аннулирует все полученные токены, и пользователю необходимо будет начать процесс привязки аккаунта заново.
Конечная точка отзыва токена (необязательно)
Позволяет Google уведомлять ваш сервис, когда пользователь отключает свою учетную запись от платформы Google. Эта конечная точка должна соответствовать требованиям, описанным в RFC 7009 .
- Метод:
POST - Content-Type:
application/x-www-form-urlencoded
Параметры запроса
| Параметры | Описание |
|---|---|
client_id | Строка, идентифицирующая источник запроса как Google. Эта строка должна быть зарегистрирована в вашей системе как уникальный идентификатор Google. |
client_secret | Секретная строка, которую вы зарегистрировали в Google для своего сервиса. |
token | Токен, подлежащий аннулированию. |
token_type_hint | (Необязательно) Указание типа отзываемого токена: access_token или refresh_token . Если не указано, по умолчанию используется access_token . |
Ответы
Возвращает успешный ответ, если токен успешно удален, или если токен уже недействителен.
- Статус HTTP:
200 OK - Content-Type:
application/json;charset=UTF-8
Ответы об ошибках
Если по какой-либо причине токен удалить не удается (например, из-за недоступности базы данных), возвращается ошибка HTTP 503. Google повторит запрос позже или в соответствии с заголовком Retry-After .
- Статус HTTP:
503 Service Unavailable - Content-Type:
application/json;charset=UTF-8 - Заголовки:
Retry-After: <HTTP-date / delay-seconds>