Привязка учетной записи к входу в Google на основе OAuth "Упрощенная" связывание

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

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

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

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

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

Рисунок 2. Визуальное представление процесса входа в систему OAuth и Google, когда информация пользователя не найдена в вашей системе.

Поддержка создания учетной записи с помощью голоса

Если вы разрешите создание учетной записи пользователя с помощью голоса, Ассистент спросит пользователя, хочет ли он сделать следующее:

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

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

Запретить создание учетной записи с помощью голоса

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

Запретить создание рекомендуется, если:

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

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

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

Разрешить создание учетной записи с помощью голоса Запретить создание учетной записи с помощью голоса

Внедрить «упрощенную» привязку входа в Google на основе OAuth.

Учетные записи связаны с потоками отраслевого стандарта OAuth 2.0. Действия в Google поддерживают потоки неявного кода и кода авторизации.

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

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

В потоке кода авторизации вам нужны две конечные точки:

• Конечная точка авторизации , которая отвечает за представление пользовательского интерфейса входа пользователям, которые еще не вошли в систему, и запись согласия на запрошенный доступ в виде кратковременного кода авторизации.
• Конечная точка обмена токенами , которая отвечает за два типа обмена:
  1. Обменивает код авторизации на долгоживущий токен обновления и недолговечный токен доступа. Этот обмен происходит, когда пользователь проходит процесс связывания учетной записи.
  2. Заменяет долгоживущий токен обновления на недолговечный токен доступа. Этот обмен происходит, когда Google нужен новый токен доступа, потому что срок его действия истек.

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

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

Код авторизации Неявный поток

Настроить проект

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

1. Откройте консоль действий и выберите проект, который вы хотите использовать.
2. Нажмите на вкладку «Разработка» и выберите «Связывание учетной записи» .
3. Включите переключатель рядом с пунктом «Привязка учетной записи» .
4. В разделе Создание учетной записи выберите Да .

5. В разделе «Тип связи » выберите «OAuth и вход в Google» и «Неявное» .

   

6. В разделе «Информация о клиенте» выполните следующие действия:

   • Присвойте значение идентификатору клиента, выданному вашими действиями Google, чтобы идентифицировать запросы, поступающие от Google.
   • Вставьте URL-адреса конечных точек авторизации и обмена токенами.

7. Нажмите Сохранить .

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

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

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

Типичный сеанс неявного потока OAuth 2.0, инициированный Google, имеет следующий поток:

1. Google открывает вашу конечную точку авторизации в браузере пользователя. Пользователь входит в систему, если он еще не вошел в систему, и предоставляет Google разрешение на доступ к своим данным с помощью вашего API, если он еще не предоставил разрешение.
2. Ваша служба создает токен доступа и возвращает его в Google, перенаправляя браузер пользователя обратно в Google с прикрепленным к запросу токеном доступа.
3. Google вызывает API вашего сервиса и прикрепляет токен доступа к каждому запросу. Ваша служба проверяет, что токен доступа предоставляет Google авторизацию для доступа к API, а затем выполняет вызов API.

Обработка запросов на авторизацию

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

Параметры конечной точки авторизации
client_id	Идентификатор клиента, который вы назначили Google.
redirect_uri	URL-адрес, на который вы отправляете ответ на этот запрос.
state	Бухгалтерское значение, которое передается обратно в Google без изменений в URI перенаправления.
response_type	Тип значения, возвращаемого в ответе. Для неявного потока OAuth 2.0 тип ответа всегда token .

Например, если ваша конечная точка авторизации доступна по адресу https://myservice.example.com/auth , запрос может выглядеть так:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

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

1. Проверьте значения client_id и redirect_uri , чтобы предотвратить предоставление доступа непреднамеренным или неправильно настроенным клиентским приложениям:

   • Убедитесь, что client_id соответствует идентификатору клиента, который вы назначили Google.
   • Убедитесь, что URL-адрес, указанный параметром redirect_uri , имеет следующую форму:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID — это идентификатор, найденный на странице настроек проекта в консоли действий.

2. Проверьте, вошел ли пользователь в ваш сервис. Если пользователь не вошел в систему, завершите процедуру входа или регистрации в вашей службе.

3. Создайте токен доступа, который Google будет использовать для доступа к вашему API. Маркер доступа может быть любым строковым значением, но он должен однозначно представлять пользователя и клиента, для которого предназначен токен, и не должен быть угадываемым.

4. Отправьте HTTP-ответ, который перенаправляет браузер пользователя на URL-адрес, указанный параметром redirect_uri . Включите все следующие параметры во фрагмент URL:

   • access_token : только что сгенерированный вами токен доступа.
   • token_type : bearer строки
   • state : немодифицированное значение состояния из исходного запроса. Ниже приведен пример результирующего URL-адреса:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Обработчик перенаправления OAuth 2.0 Google получит токен доступа и подтвердит, что значение state не изменилось. После того как Google получит токен доступа к вашей службе, Google прикрепит этот токен к последующим вызовам вашего действия как часть AppRequest .

Handle automatic linking

After the user gives your Action 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 returns a token for the user. If the Google account doesn't match an existing user, your token exchange endpoint returns a user_not_found error.

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=get&assertion=JWT&consent_code=CONSENT_CODE&scope=SCOPES

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
grant_type	The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
intent	For these requests, the value of this parameter is `get`.
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.
consent_code	Optional: When present, a one-time code that indicates that the user has granted consent for your Action to access the specified scopes.
scope	Optional: Any scopes you configured Google to request from users.

When your token exchange endpoint receives the linking request, it should do the following:

验证和解码 JWT 断言

您可以使用适合您的语言的 JWT 解码库来验证和解码 JWT 断言。使用 Google 的公钥（以 JWK 或 PEM 格式提供）来验证令牌的签名。

注意 ：键不应采用硬编码。而应按照 OpenID connect Discovery Protocol 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如下所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，请验证断言的颁发者（iss 字段）是否为 https://accounts.google.com，以及目标对象群组（aud 字段）是否为分配给您的 Action 的客户端 ID。

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 and you can issue an access token.

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 should reply with a HTTP 401 error, that specifies error=user_not_found, as in the following example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"user_not_found",
}

When Google receives the 401 error response with a user_not_found error, Google calls your token exchange endpoint with the value of the intent parameter set to create and sending an ID token that contains the user's profile information with the request.

Handle account creation via Google Sign-In

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create, as in the following example:

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&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]

The assertion parameter contains 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, which you can use to create a new account on your service.

To respond to account creation requests, your token exchange endpoint must do the following:

验证和解码 JWT 断言

您可以使用适合您的语言的 JWT 解码库来验证和解码 JWT 断言。使用 Google 的公钥（以 JWK 或 PEM 格式提供）来验证令牌的签名。

注意 ：键不应采用硬编码。而应按照 OpenID connect Discovery Protocol 并检查 cache-control 标头，以确定应将密钥缓存多长时间。

解码后，JWT 断言如下所示：

{
  "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": "[e-mail]", // If present, the user's email address
  "locale": "en_US"
}

除了验证令牌的签名之外，请验证断言的颁发者（iss 字段）是否为 https://accounts.google.com，以及目标对象群组（aud 字段）是否为分配给您的 Action 的客户端 ID。

Validate user information and create new account

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, prompt the user to link their existing account with their Google Account by responding to the request with an HTTP 401 error, specifying error=linking_error and the user's email address as the login_hint, as in the following example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

If neither condition is true, create a new user account using the information provided in the JWT. New accounts do not typically have a password set. It is recommended that you add Google Sign In to other platforms to enable users to log in via Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password for signing in on other platforms.

When the creation is completed, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  
  "expires_in": SECONDS_TO_EXPIRATION
}

Разработайте голосовой пользовательский интерфейс для процесса аутентификации.

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

Примечание. Для создания действия, реализующего связывание учетных записей, необходимо использовать Actions Builder .

Проверьте, подтвержден ли пользователь, и запустите процесс привязки учетной записи.

1. Откройте проект Actions Builder в консоли Actions .
2. Создайте новую сцену, чтобы начать привязку учетной записи в своем действии:
   1. Нажмите «Сцены» .
   2. Нажмите значок добавления (+), чтобы добавить новую сцену.
3. Во вновь созданной сцене щелкните значок « для «Условия» .
4. Добавьте условие, которое проверяет, является ли пользователь, связанный с беседой, проверенным пользователем. Если проверка не пройдена, ваше действие не сможет выполнить привязку учетной записи во время разговора и должно вернуться к предоставлению доступа к функциям, которые не требуют привязки учетной записи.
   1. В поле Enter new expression в разделе «Условие» введите следующую логику: user.verificationStatus != "VERIFIED"
   2. В разделе «Переход» выберите сцену, которая не требует привязки учетной записи, или сцену, которая является точкой входа в функции, доступные только для гостей.

1. Нажмите значок « для «Условия» .
2. Добавьте условие для запуска процесса связывания учетной записи, если у пользователя нет связанного удостоверения.
   1. В поле Enter new expression в разделе «Условие » введите следующую логику: user.verificationStatus == "VERIFIED"
   2. В разделе «Переход» выберите системную сцену «Связывание учетных записей» .
   3. Нажмите Сохранить .

После сохранения в ваш проект добавляется новая сцена системы связывания учетных записей под названием <SceneName>_AccountLinking .

Настройте сцену привязки учетной записи

1. В разделе «Сцены» выберите сцену системы привязки учетной записи.
2. Нажмите «Отправить запрос» и добавьте короткое предложение, описывающее пользователю, почему Действию необходим доступ к его личности (например, «Чтобы сохранить ваши настройки»).
3. Нажмите Сохранить .

1. В разделе «Условия» нажмите «Если пользователь успешно завершил привязку учетной записи» .
2. Настройте, как должен действовать поток, если пользователь соглашается связать свою учетную запись. Например, вызовите веб-перехватчик для обработки любой необходимой пользовательской бизнес-логики и возврата к исходной сцене.
3. Нажмите Сохранить .

1. В разделе «Условия» выберите «Если пользователь отменяет или отклоняет привязку учетной записи» .
2. Настройте порядок действий, если пользователь не согласен связать свою учетную запись. Например, отправьте подтверждающее сообщение и перенаправьте на сцены, которые предоставляют функциональные возможности, не требующие привязки учетной записи.
3. Нажмите Сохранить .

1. В разделе «Условия» выберите «При возникновении системной или сетевой ошибки» .
2. Настройте, как должен действовать процесс, если процесс связывания учетных записей не может быть завершен из-за системных или сетевых ошибок. Например, отправьте подтверждающее сообщение и перенаправьте на сцены, которые предоставляют функциональные возможности, не требующие привязки учетной записи.
3. Нажмите Сохранить .

Обработка запросов на доступ к данным

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