Упрощенное связывание с помощью OAuth и входа в Google

Обзор

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

Чтобы связать учетную запись с помощью OAuth и входа в Google, выполните следующие общие шаги:

1. Сначала попросите пользователя дать согласие на доступ к его профилю Google.
2. Используйте информацию в их профиле, чтобы проверить, существует ли учетная запись пользователя.
3. Для существующих пользователей свяжите учетные записи.
4. Если вы не можете найти совпадение с пользователем Google в своей системе аутентификации, подтвердите идентификационный токен, полученный от Google. Затем вы можете создать пользователя на основе информации профиля, содержащейся в идентификационном токене.

Рисунок 1 . Привязка учетной записи на телефоне пользователя с помощью Streamlined Linking

Требования для упрощенного связывания

• Реализуйте базовый процесс связывания веб-OAuth . Ваш сервис должен поддерживать авторизацию , совместимую с OAuth 2.0, и конечные точки обмена токенами .
• Конечная точка обмена токенами должна поддерживать утверждения JSON Web Token (JWT) и реализовывать намерения check , create и get .

• Зарегистрируйте свой идентификатор клиента API Google .

Внедрите свой сервер OAuth

Ваша конечная точка обмена токенами должна поддерживать намерения check , create , get . Ниже показаны шаги, выполненные в процессе связывания учетной записи, и указано, когда вызываются различные намерения:

1. Есть ли у пользователя учетная запись в вашей системе аутентификации? (Пользователь решает, выбирая ДА или НЕТ)
   1. ДА: использует ли пользователь адрес электронной почты, связанный с его учетной записью Google, для входа на вашу платформу? (Пользователь решает, выбирая ДА или НЕТ)
      1. ДА: есть ли у пользователя соответствующая учетная запись в вашей системе аутентификации? ( check intent вызывается для подтверждения)
         1. ДА: вызывается get intent , и учетная запись привязывается, если метод Get Intent возвращается успешно.
         2. НЕТ : Создать новую учетную запись? (Пользователь решает, выбирая ДА или НЕТ)
            1. ДА: вызывается create intent , и учетная запись привязывается, если создание намерения завершается успешно.
            2. НЕТ : поток Web OAuth запускается, пользователь перенаправляется в свой браузер, и ему предоставляется возможность установить ссылку на другой адрес электронной почты.
      2. НЕТ: поток Web OAuth запускается, пользователь перенаправляется в свой браузер, и ему предоставляется возможность установить ссылку на другой адрес электронной почты.
   2. НЕТ: есть ли у пользователя соответствующая учетная запись в вашей системе аутентификации? ( check intent вызывается для подтверждения)
      1. ДА: вызывается get intent , и учетная запись привязывается, если метод Get Intent возвращается успешно.
      2. НЕТ: вызывается create intent , и учетная запись привязывается, если создание намерения возвращается успешно.

Проверить существующую учетную запись пользователя (проверить намерение)

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

Если соответствующая учетная запись Google уже присутствует в вашей системе аутентификации, ваша конечная точка обмена токенами отвечает account_found=true . Если учетная запись Google не соответствует существующему пользователю, ваша конечная точка обмена токенами возвращает ошибку HTTP 404 Not Found с account_found=false .

Запрос имеет следующую форму:

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

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

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

• Проверьте и декодируйте утверждение 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 and hd 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 утверждения, находится в вашей базе данных пользователей.
• Адрес электронной почты в утверждении соответствует пользователю в вашей базе данных пользователей.

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

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Если ни идентификатор аккаунта Google, ни адрес электронной почты, указанные в утверждении, не соответствуют пользователю в вашей базе данных, значит, пользователь еще не зарегистрировался. В этом случае ваша конечная точка обмена токенами должна ответить ошибкой HTTP 404, в которой указано "account_found": "false" , как в следующем примере:

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

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

Чтобы ответить на запросы 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 and hd 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

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

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 and hd 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 . Для этого выполните следующие шаги:

1. Откройте страницу «Учетные данные» консоли Google API .

2. Создайте или выберите проект Google API.

   Если в вашем проекте нет идентификатора клиента для типа веб-приложения, нажмите «Создать учетные данные» > «Идентификатор клиента OAuth», чтобы создать его. Обязательно укажите домен вашего сайта в поле «Авторизованное происхождение JavaScript» . При выполнении локального тестирования или разработки необходимо добавить http://localhost и http://localhost:<port_number> в поле Авторизованное происхождение JavaScript .

Проверка вашей реализации

Вы можете проверить свою реализацию с помощью инструмента OAuth 2.0 Playground .

В инструменте выполните следующие действия:

1. Нажмите settings конфигурации» , чтобы открыть окно «Конфигурация OAuth 2.0».
2. В поле «Поток OAuth» выберите «Клиентская сторона» .
3. В поле «Конечные точки OAuth» выберите «Пользовательский» .
4. Укажите конечную точку OAuth 2.0 и идентификатор клиента, который вы назначили Google, в соответствующих полях.
5. В разделе «Шаг 1» не выбирайте области действия Google. Вместо этого оставьте это поле пустым или введите область действия, действительную для вашего сервера (или произвольную строку, если вы не используете области действия OAuth). Закончив, нажмите «Авторизовать API» .
6. В разделах «Шаг 2» и «Шаг 3» выполните процедуру OAuth 2.0 и убедитесь, что каждый шаг работает должным образом.

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

В инструменте выполните следующие действия:

1. Нажмите кнопку «Войти через Google» .
2. Выберите аккаунт, который хотите связать.
3. Введите идентификатор услуги.
4. При необходимости введите одну или несколько областей, для которых вы запросите доступ.
5. Нажмите «Начать демонстрацию» .
6. При появлении запроса подтвердите, что вы можете согласиться и отклонить запрос на установление связи.
7. Подтвердите, что вы перенаправлены на вашу платформу.