Обзор
Оптимизированное связывание входа в Google на основе OAuth добавляет вход в Google поверх связывания OAuth . Это обеспечивает беспрепятственное связывание для пользователей Google, а также позволяет создавать учетные записи, что позволяет пользователю создать новую учетную запись в вашей службе, используя свою учетную запись Google.
Чтобы связать учетную запись с помощью OAuth и входа в Google, выполните следующие общие шаги:
- Сначала попросите пользователя дать согласие на доступ к его профилю Google.
- Используйте информацию в их профиле, чтобы проверить, существует ли учетная запись пользователя.
- Для существующих пользователей свяжите учетные записи.
- Если вы не можете найти совпадение с пользователем Google в своей системе аутентификации, подтвердите идентификационный токен, полученный от Google. Затем вы можете создать пользователя на основе информации профиля, содержащейся в идентификационном токене.
Рисунок 1 . Привязка учетной записи на телефоне пользователя с помощью Streamlined Linking
Требования для упрощенного связывания
- Реализуйте базовый процесс связывания веб-OAuth . Ваш сервис должен поддерживать авторизацию , совместимую с OAuth 2.0, и конечные точки обмена токенами .
- Конечная точка обмена токенами должна поддерживать утверждения JSON Web Token (JWT) и реализовывать намерения
check
,create
иget
.
Внедрите свой сервер OAuth
Ваша конечная точка обмена токенами должна поддерживать намерения check
, create
, get
. Ниже показаны шаги, выполненные в процессе связывания учетной записи, и указано, когда вызываются различные намерения:
- Есть ли у пользователя учетная запись в вашей системе аутентификации? (Пользователь решает, выбирая ДА или НЕТ)
- ДА: использует ли пользователь адрес электронной почты, связанный с его учетной записью Google, для входа на вашу платформу? (Пользователь решает, выбирая ДА или НЕТ)
- ДА: есть ли у пользователя соответствующая учетная запись в вашей системе аутентификации? (
check intent
вызывается для подтверждения)- ДА: вызывается
get intent
, и учетная запись привязывается, если метод Get Intent возвращается успешно. - НЕТ : Создать новую учетную запись? (Пользователь решает, выбирая ДА или НЕТ)
- ДА: вызывается
create intent
, и учетная запись привязывается, если создание намерения завершается успешно. - НЕТ : поток Web OAuth запускается, пользователь перенаправляется в свой браузер, и ему предоставляется возможность установить ссылку на другой адрес электронной почты.
- ДА: вызывается
- ДА: вызывается
- НЕТ: поток Web OAuth запускается, пользователь перенаправляется в свой браузер, и ему предоставляется возможность установить ссылку на другой адрес электронной почты.
- ДА: есть ли у пользователя соответствующая учетная запись в вашей системе аутентификации? (
- НЕТ: есть ли у пользователя соответствующая учетная запись в вашей системе аутентификации? (
check intent
вызывается для подтверждения)- ДА: вызывается
get intent
, и учетная запись привязывается, если метод Get Intent возвращается успешно. - НЕТ: вызывается
create intent
, и учетная запись привязывается, если создание намерения возвращается успешно.
- ДА: вызывается
- ДА: использует ли пользователь адрес электронной почты, связанный с его учетной записью Google, для входа на вашу платформу? (Пользователь решает, выбирая ДА или НЕТ)
Check for an existing user account (check intent)
After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.
If the corresponding Google account is already present in your authentication
system, your token exchange endpoint responds with account_found=true
. If the
Google account doesn't match an existing user, your token exchange endpoint
returns an HTTP 404 Not Found error with account_found=false
.
The request has the following form:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Your token exchange endpoint must be able to handle the following parameters:
Token endpoint parameters | |
---|---|
intent |
For these requests, the value of this parameter is
check . |
grant_type |
The type of token being exchanged. For these requests, this
parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion |
A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address. |
client_id |
The client ID you assigned to Google. |
client_secret |
The client secret you assigned to Google. |
To respond to the check
intent requests, your token exchange endpoint must perform the following steps:
- Validate and decode the JWT assertion.
- Check if the Google account is already present in your authentication system.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "sub": "1234567890", // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "email_verified": true, // true, if Google has verified the email address "hd": "example.com", // If present, the host domain of the user's GSuite email address // If present, a URL to user's profile picture "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ", "locale": "en_US" // User's locale, from browser or phone settings }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Check if the Google account is already present in your authentication system
Check whether either of the following conditions are true:
- The Google Account ID, found in the assertion's
sub
field, is in your user database. - The email address in the assertion matches a user in your user database.
If either condition is true, the user has already signed up. In that case, return a response like the following:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
If neither the Google Account ID nor the email address specified in the
assertion matches a user in your database, the user hasn't signed up yet. In
this case, your token exchange endpoint needs to reply with a HTTP 404 error
that specifies "account_found": "false"
, as in the following example:
HTTP/1.1 404 Not found Content-Type: application/json;charset=UTF-8 { "account_found":"false", }
Обработка автоматического связывания (получение намерения)
После того как пользователь дает согласие на доступ к своему профилю Google, Google отправляет запрос, содержащий подписанное подтверждение личности пользователя Google. Утверждение содержит информацию, включающую идентификатор аккаунта Google, имя и адрес электронной почты пользователя. Конечная точка обмена токенами, настроенная для вашего проекта, обрабатывает этот запрос.
Если соответствующая учетная запись Google уже присутствует в вашей системе аутентификации, ваша конечная точка обмена токенами возвращает токен пользователю. Если учетная запись Google не соответствует существующему пользователю, ваша конечная точка обмена токенами возвращает ошибку linking_error
и необязательный login_hint
.
Запрос имеет следующую форму:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Конечная точка обмена токенами должна иметь возможность обрабатывать следующие параметры:
Параметры конечной точки токена | |
---|---|
intent | Для этих запросов значение этого параметра равно get . |
grant_type | Тип обмениваемого токена. Для этих запросов этот параметр имеет значение urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion | Веб-токен JSON (JWT), который обеспечивает подписанное подтверждение личности пользователя Google. JWT содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя. |
scope | Необязательно: любые области действия, которые вы настроили Google для запроса от пользователей. |
client_id | Идентификатор клиента, который вы назначили Google. |
client_secret | Секрет клиента, который вы передали Google. |
Чтобы ответить на запросы get
Intent, ваша конечная точка обмена токенами должна выполнить следующие шаги:
- Проверьте и декодируйте утверждение JWT.
- Проверьте, присутствует ли уже учетная запись Google в вашей системе аутентификации.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "sub": "1234567890", // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "email_verified": true, // true, if Google has verified the email address "hd": "example.com", // If present, the host domain of the user's GSuite email address // If present, a URL to user's profile picture "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ", "locale": "en_US" // User's locale, from browser or phone settings }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Проверьте, присутствует ли учетная запись Google в вашей системе аутентификации.
Проверьте, верно ли одно из следующих условий:
- Идентификатор аккаунта Google, указанный в
sub
утверждения, находится в вашей базе данных пользователей. - Адрес электронной почты в утверждении соответствует пользователю в вашей базе данных пользователей.
Если для пользователя найдена учетная запись, выдайте токен доступа и верните значения в объекте JSON в теле вашего ответа HTTPS, как в следующем примере:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
В некоторых случаях привязка учетной записи на основе токена идентификатора может оказаться неудачной для пользователя. Если это происходит по какой-либо причине, ваша конечная точка обмена токенами должна ответить ошибкой HTTP 401, которая указывает error=linking_error
, как показано в следующем примере:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
Когда Google получает ответ об ошибке 401 с linking_error
, Google отправляет пользователя в вашу конечную точку авторизации с login_hint
в качестве параметра. Пользователь завершает привязку учетной записи, используя процесс привязки OAuth в своем браузере.
Обработка создания учетной записи через вход в Google (создание намерения)
Когда пользователю необходимо создать учетную запись в вашем сервисе, Google отправляет запрос к вашей конечной точке обмена токенами, который указывает intent=create
.
Запрос имеет следующую форму:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET
Конечная точка обмена токенами должна иметь возможность обрабатывать следующие параметры:
Параметры конечной точки токена | |
---|---|
intent | Для этих запросов значение этого параметра равно create . |
grant_type | Тип обмениваемого токена. Для этих запросов этот параметр имеет значение urn:ietf:params:oauth:grant-type:jwt-bearer . |
assertion | Веб-токен JSON (JWT), который обеспечивает подписанное подтверждение личности пользователя Google. JWT содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя. |
client_id | Идентификатор клиента, который вы назначили Google. |
client_secret | Секрет клиента, который вы передали Google. |
JWT в параметре assertion
содержит идентификатор учетной записи Google, имя и адрес электронной почты пользователя, которые вы можете использовать для создания новой учетной записи в своей службе.
Чтобы ответить на запросы create
намерений, ваша конечная точка обмена токенами должна выполнить следующие шаги:
- Проверьте и декодируйте утверждение JWT.
- Подтвердите информацию о пользователе и создайте новую учетную запись.
Validate and decode the JWT assertion
You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.
When decoded, the JWT assertion looks like the following example:
{ "sub": "1234567890", // The unique ID of the user's Google Account "iss": "https://accounts.google.com", // The assertion's issuer "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID "iat": 233366400, // Unix timestamp of the assertion's creation time "exp": 233370000, // Unix timestamp of the assertion's expiration time "name": "Jan Jansen", "given_name": "Jan", "family_name": "Jansen", "email": "jan@gmail.com", // If present, the user's email address "email_verified": true, // true, if Google has verified the email address "hd": "example.com", // If present, the host domain of the user's GSuite email address // If present, a URL to user's profile picture "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ", "locale": "en_US" // User's locale, from browser or phone settings }
In addition to verifying the token's signature, verify that the assertion's
issuer (iss
field) is https://accounts.google.com
, that the audience
(aud
field) is your assigned client ID, and that the token has not expired
(exp
field).
Using the email
, email_verified
and hd
fields you can determine if
Google hosts and is authoritative for an email address. In cases where Google is
authoritative the user is currently known to be the legitimate account owner
and you may skip password or other challenges methods. Otherwise, these methods
can be used to verify the account prior to linking.
Cases where Google is authoritative:
email
has a@gmail.com
suffix, this is a Gmail account.email_verified
is true andhd
is set, this is a G Suite account.
Users may register for Google Accounts without using Gmail or G Suite. When
email
does not contain a @gmail.com
suffix and hd
is absent Google is not
authoritative and password or other challenge methods are recommended to verify
the user. email_verified
can also be true as Google initially verified the
user when the Google account was created, however ownership of the third party
email account may have since changed.
Подтвердите информацию о пользователе и создайте новую учетную запись
Проверьте, верно ли одно из следующих условий:
- Идентификатор аккаунта Google, указанный в
sub
утверждения, находится в вашей базе данных пользователей. - Адрес электронной почты в утверждении соответствует пользователю в вашей базе данных пользователей.
Если любое из условий верно, предложите пользователю связать существующую учетную запись со своей учетной записью Google. Для этого ответьте на запрос ошибкой HTTP 401, в которой указывается error=linking_error
и указывается адрес электронной почты пользователя в качестве login_hint
. Ниже приведен пример ответа:
HTTP/1.1 401 Unauthorized Content-Type: application/json;charset=UTF-8 { "error":"linking_error", "login_hint":"foo@bar.com" }
Когда Google получает ответ об ошибке 401 с linking_error
, Google отправляет пользователя в вашу конечную точку авторизации с login_hint
в качестве параметра. Пользователь завершает привязку учетной записи, используя процесс привязки OAuth в своем браузере.
Если ни одно из условий не верно, создайте новую учетную запись пользователя, используя информацию, предоставленную в JWT. Для новых учетных записей обычно не устанавливается пароль. Рекомендуется добавить функцию входа в Google на другие платформы, чтобы пользователи могли входить в систему с помощью Google на всех платформах вашего приложения. Кроме того, вы можете отправить пользователю по электронной почте ссылку, которая запустит процесс восстановления пароля, чтобы позволить пользователю установить пароль для входа на других платформах.
Когда создание будет завершено, выдайте токен доступа. и обновить токен и верните значения в объекте JSON в теле вашего ответа HTTPS, как в следующем примере:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Получите идентификатор клиента Google API
Вам необходимо будет предоставить свой идентификатор клиента Google API в процессе регистрации привязки учетной записи.
Чтобы получить идентификатор клиента API, используя проект, который вы создали при выполнении шагов связывания OAuth . Для этого выполните следующие шаги:
- Откройте страницу «Учетные данные» консоли Google API .
Создайте или выберите проект Google API.
Если в вашем проекте нет идентификатора клиента для типа веб-приложения, нажмите «Создать учетные данные» > «Идентификатор клиента OAuth», чтобы создать его. Обязательно укажите домен вашего сайта в поле «Авторизованное происхождение JavaScript» . При выполнении локального тестирования или разработки необходимо добавить
http://localhost
иhttp://localhost:<port_number>
в поле Авторизованное происхождение JavaScript .
Проверка вашей реализации
You can validate your implementation by using the OAuth 2.0 Playground tool.
In the tool, do the following steps:
- Click Configuration to open the OAuth 2.0 Configuration window.
- In the OAuth flow field, select Client-side.
- In the OAuth Endpoints field, select Custom.
- Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
- In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
- In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.
You can validate your implementation by using the Google Account Linking Demo tool.
In the tool, do the following steps:
- Click the Sign-in with Google button.
- Choose the account you'd like to link.
- Enter the service ID.
- Optionally enter one or more scopes that you will request access for.
- Click Start Demo.
- When prompted, confirm that you may consent and deny the linking request.
- Confirm that you are redirected to your platform.