Тип привязки входа в Google на основе OAuth «Оптимизированный» добавляет вход в Google поверх привязки учетной записи на основе OAuth. Это обеспечивает беспрепятственное голосовое связывание для пользователей Google, а также позволяет связывать учетные записи для пользователей, которые зарегистрировались в вашей службе с помощью удостоверения, отличного от Google.
Этот тип связывания начинается с входа в систему Google, что позволяет вам проверить, существует ли в вашей системе информация о профиле пользователя Google. Если информация о пользователе не найдена в вашей системе, начинается стандартный процесс OAuth. Пользователь также может создать новую учетную запись с данными своего профиля Google.
Чтобы выполнить привязку учетной записи с типом привязки Streamlined, выполните следующие общие действия:
- Сначала попросите пользователя дать согласие на доступ к его профилю Google.
- Используйте информацию в своем профиле, чтобы идентифицировать пользователя.
- Если вы не можете найти совпадение для пользователя Google в своей системе аутентификации, процесс продолжится в зависимости от того, настроили ли вы свой проект Actions в консоли Actions, чтобы разрешить создание учетной записи пользователя с помощью голоса или только на вашем веб-сайте.
- Если вы разрешаете создание учетной записи с помощью голоса, подтвердите токен идентификатора, полученный от Google. Затем вы можете создать пользователя на основе информации профиля, содержащейся в токене идентификатора.
- Если вы не разрешаете создание учетной записи с помощью голоса, пользователь перенаправляется в браузер, где он может загрузить вашу страницу авторизации и завершить процесс создания пользователя.
Поддержка создания учетной записи с помощью голоса
Если вы разрешите создание учетной записи пользователя с помощью голоса, Ассистент спрашивает пользователя, хотят ли они сделать следующее:
- Создайте новую учетную запись в своей системе, используя данные своей учетной записи Google, или
- Войдите в свою систему аутентификации с другой учетной записью, если у них уже есть учетная запись, отличная от Google.
Разрешение создания учетной записи с помощью голоса рекомендуется, если вы хотите свести к минимуму трение процесса создания учетной записи. Пользователю нужно выйти из голосового потока только в том случае, если он хочет войти, используя существующую учетную запись, отличную от Google.
Запретить создание учетной записи с помощью голоса
Если вы запретили создание учетной записи пользователя с помощью голоса, Ассистент открывает URL-адрес веб-сайта, который вы указали для аутентификации пользователя. Если взаимодействие происходит на устройстве без экрана, Ассистент направляет пользователя к телефону, чтобы продолжить процесс привязки учетной записи.
Запрет создания рекомендуется, если:
Вы не хотите разрешать пользователям, у которых есть учетные записи, отличные от Google, создавать новую учетную запись пользователя, и вместо этого хотите, чтобы они связывались со своими существующими учетными записями пользователей в вашей системе аутентификации. Например, если вы предлагаете программу лояльности, вы можете убедиться, что пользователь не потеряет баллы, накопленные в его существующей учетной записи.
Вы должны иметь полный контроль над процессом создания учетной записи. Например, вы можете запретить создание, если вам нужно показать пользователю свои условия обслуживания во время создания учетной записи.
Реализовать «упрощенную» привязку входа в систему Google на основе OAuth.
Учетные записи связаны стандартными для отрасли потоками OAuth 2.0. Действия в Google поддерживают неявные потоки и потоки кода авторизации.
В потоке неявного кода Google открывает вашу конечную точку авторизации в браузере пользователя. После успешного входа вы возвращаете долговременный токен доступа в Google. Этот токен доступа теперь включается в каждый запрос, отправляемый помощником в ваше действие.
В потоке кода авторизации вам нужны две конечные точки:
- Конечная точка авторизации , которая отвечает за представление пользовательского интерфейса входа пользователям, которые еще не вошли в систему, и запись согласия на запрошенный доступ в виде кратковременного кода авторизации.
- Конечная точка обмена токенами , которая отвечает за два типа обмена:
- Обменивает код авторизации на долгоживущий токен обновления и недолговечный токен доступа. Этот обмен происходит, когда пользователь проходит процесс связывания учетной записи.
- Заменяет долгоживущий токен обновления на недолговечный токен доступа. Этот обмен происходит, когда Google нужен новый токен доступа, потому что срок его действия истек.
Хотя неявный поток кода реализовать проще, Google рекомендует, чтобы токены доступа, выданные с использованием неявного потока, никогда не истекали, потому что использование истечения срока действия токена с неявным потоком вынуждает пользователя снова связывать свою учетную запись. Если вам требуется истечение срока действия токена по соображениям безопасности, вам следует настоятельно рассмотреть возможность использования потока кода аутентификации.
Настроить проект
Чтобы настроить проект для использования упрощенного связывания, выполните следующие действия:
- Откройте консоль Actions и выберите проект, который хотите использовать.
- Перейдите на вкладку «Разработка» и выберите «Привязка учетной записи» .
- Включите переключатель рядом с Привязкой аккаунта .
- В разделе Создание учетной записи выберите Да .
В типе привязки выберите OAuth и Google Sign In и Implicit .
В информации о клиенте сделайте следующее:
- Назначьте значение идентификатору клиента, выдаваемому вашими действиями в Google, чтобы идентифицировать запросы, поступающие от Google.
- Вставьте URL-адреса ваших конечных точек авторизации и обмена токенами.
Нажмите Сохранить .
Внедрите свой сервер OAuth
Для поддержки неявного потока OAuth 2.0 ваша служба делает конечную точку авторизации доступной по HTTPS. Эта конечная точка отвечает за аутентификацию и получение согласия пользователей на доступ к данным. Конечная точка авторизации представляет пользовательский интерфейс входа для ваших пользователей, которые еще не вошли в систему, и записывает согласие на запрошенный доступ.
Когда вашему действию необходимо вызвать один из авторизованных API вашей службы, Google использует эту конечную точку, чтобы получить от ваших пользователей разрешение на вызов этих API от их имени.
Типичный сеанс неявного потока OAuth 2.0, инициированный Google, имеет следующий поток:
- Google открывает вашу конечную точку авторизации в браузере пользователя. Пользователь входит в систему, если он еще не выполнен, и предоставляет Google разрешение на доступ к своим данным с помощью вашего API, если он еще не предоставил разрешение.
- Ваша служба создает маркер доступа и возвращает его в Google, перенаправляя браузер пользователя обратно в Google с маркером доступа, прикрепленным к запросу.
- 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
Чтобы ваша конечная точка авторизации могла обрабатывать запросы на вход, выполните следующие действия:
Проверьте значения
client_idиredirect_uri, чтобы предотвратить предоставление доступа непреднамеренным или неправильно настроенным клиентским приложениям:- Убедитесь, что
client_idсоответствует идентификатору клиента, который вы присвоили Google. - Убедитесь, что URL-адрес, указанный параметром
redirect_uri, имеет следующую форму:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID — это идентификатор, найденный на странице настроек проекта в консоли действий.
- Убедитесь, что
Проверьте, вошел ли пользователь в вашу службу. Если пользователь не вошел в систему, завершите процесс входа или регистрации вашей службы.
Создайте токен доступа, который Google будет использовать для доступа к вашему API. Токен доступа может быть любым строковым значением, но он должен однозначно представлять пользователя и клиента, для которых предназначен токен, и его нельзя угадать.
Отправьте ответ 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
-
Обработчик перенаправления Google OAuth 2.0 получит токен доступа и подтвердит, что значение state не изменилось. После того, как Google получит токен доступа для вашей службы, Google прикрепит токен к последующим вызовам вашего действия как часть AppRequest .
Для поддержки неявного потока OAuth 2.0 ваша служба делает конечную точку авторизации доступной по HTTPS. Эта конечная точка отвечает за аутентификацию и получение согласия пользователей на доступ к данным. Конечная точка авторизации представляет пользовательский интерфейс входа для ваших пользователей, которые еще не вошли в систему, и записывает согласие на запрошенный доступ.
Когда вашему действию необходимо вызвать один из авторизованных API вашей службы, Google использует эту конечную точку, чтобы получить от ваших пользователей разрешение на вызов этих API от их имени.
Типичный сеанс неявного потока OAuth 2.0, инициированный Google, имеет следующий поток:
- Google открывает вашу конечную точку авторизации в браузере пользователя. Пользователь входит в систему, если он еще не выполнен, и предоставляет Google разрешение на доступ к своим данным с помощью вашего API, если он еще не предоставил разрешение.
- Ваша служба создает маркер доступа и возвращает его в Google, перенаправляя браузер пользователя обратно в Google с маркером доступа, прикрепленным к запросу.
- 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
Чтобы ваша конечная точка авторизации могла обрабатывать запросы на вход, выполните следующие действия:
Проверьте значения
client_idиredirect_uri, чтобы предотвратить предоставление доступа непреднамеренным или неправильно настроенным клиентским приложениям:- Убедитесь, что
client_idсоответствует идентификатору клиента, который вы присвоили Google. - Убедитесь, что URL-адрес, указанный параметром
redirect_uri, имеет следующую форму:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
YOUR_PROJECT_ID — это идентификатор, найденный на странице настроек проекта в консоли действий.
- Убедитесь, что
Проверьте, вошел ли пользователь в вашу службу. Если пользователь не вошел в систему, завершите процесс входа или регистрации вашей службы.
Создайте токен доступа, который Google будет использовать для доступа к вашему API. Токен доступа может быть любым строковым значением, но он должен однозначно представлять пользователя и клиента, для которых предназначен токен, и его нельзя угадать.
Отправьте ответ 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
-
Обработчик перенаправления Google OAuth 2.0 получит токен доступа и подтвердит, что значение state не изменилось. После того, как Google получит токен доступа для вашей службы, Google прикрепит токен к последующим вызовам вашего действия как часть AppRequest .
Обработка автоматического связывания
После того как пользователь дает ваше согласие на доступ к своему профилю Google, Google отправляет запрос, содержащий подписанное подтверждение личности пользователя Google. Утверждение содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя. Конечная точка обмена токенами, настроенная для вашего проекта, обрабатывает этот запрос.
Если соответствующая учетная запись Google уже присутствует в вашей системе аутентификации, ваша конечная точка обмена токенами возвращает токен для пользователя. Если учетная запись Google не соответствует существующему пользователю, ваша конечная точка обмена токенами возвращает ошибку user_not_found .
Запрос имеет следующий вид:
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
Ваша конечная точка обмена токенами должна иметь возможность обрабатывать следующие параметры:
| Параметры конечной точки токена | |
|---|---|
grant_type | Тип обмениваемого токена. Для этих запросов этот параметр имеет значение urn:ietf:params:oauth:grant-type:jwt-bearer . |
intent | Для этих запросов значение этого параметра равно `get`. |
assertion | Веб-маркер JSON (JWT), предоставляющий подписанное подтверждение личности пользователя Google. JWT содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя. |
consent_code | Необязательно : если присутствует, одноразовый код, указывающий, что пользователь дал согласие на доступ вашего действия к указанным областям. |
scope | Необязательно . Любые области, которые вы настроили Google для запроса от пользователей. |
Когда ваша конечная точка обмена токенами получает запрос на связывание, она должна сделать следующее:
Проверка и декодирование утверждения JWT
Вы можете проверить и декодировать утверждение JWT, используя библиотеку JWT-декодирования для вашего языка . Используйте открытые ключи Google (доступны в формате JWK или PEM ) для проверки подписи токена.
При декодировании утверждение 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": "jan@gmail.com", // If present, the user's email address
"locale": "en_US"
}
В дополнение к проверке подписи токена убедитесь, что издателем утверждения (поле iss ) является https://accounts.google.com , а аудиторией (поле aud ) является идентификатор клиента, назначенный вашему действию.
Проверьте, присутствует ли учетная запись Google в вашей системе аутентификации.
Проверьте, выполняется ли одно из следующих условий:
- Идентификатор учетной записи Google, указанный в
subутверждения, находится в вашей базе данных пользователей. - Адрес электронной почты в утверждении соответствует пользователю в вашей базе данных пользователей.
Если какое-либо из условий выполняется, пользователь уже зарегистрировался, и вы можете выдать токен доступа.
Если ни идентификатор учетной записи Google, ни адрес электронной почты, указанные в утверждении, не соответствуют пользователю в вашей базе данных, пользователь еще не зарегистрировался. В этом случае ваша конечная точка обмена токенами должна ответить ошибкой HTTP 401 с указанием error=user_not_found , как в следующем примере:
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"error":"user_not_found",
}
Когда Google получает ответ об ошибке 401 с ошибкой user_not_found , Google вызывает вашу конечную точку обмена токенами со значением параметра intent , установленным для создания и отправки токена идентификатора, который содержит информацию о профиле пользователя с запросом.
Управление созданием учетной записи через Google Sign-In
Когда пользователю необходимо создать учетную запись в вашем сервисе, 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&consent_code=CONSENT_CODE&assertion=JWT[&NEW_ACCOUNT_INFO]
Параметр assertion содержит веб-маркер JSON (JWT), предоставляющий подписанное подтверждение личности пользователя Google. JWT содержит информацию, включающую идентификатор учетной записи Google, имя и адрес электронной почты пользователя, которые можно использовать для создания новой учетной записи в вашей службе.
Чтобы отвечать на запросы о создании учетной записи, ваша конечная точка обмена токенами должна выполнять следующие действия:
Проверка и декодирование утверждения JWT
Вы можете проверить и декодировать утверждение JWT, используя библиотеку JWT-декодирования для вашего языка . Используйте открытые ключи Google (доступны в формате JWK или PEM ) для проверки подписи токена.
При декодировании утверждение 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": "jan@gmail.com", // If present, the user's email address
"locale": "en_US"
}
В дополнение к проверке подписи токена убедитесь, что издателем утверждения (поле iss ) является https://accounts.google.com , а аудиторией (поле aud ) является идентификатор клиента, назначенный вашему действию.
Подтвердите информацию о пользователе и создайте новую учетную запись
Проверьте, выполняется ли одно из следующих условий:
- Идентификатор учетной записи 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"
}
Если ни одно из условий не выполняется, создайте новую учетную запись пользователя, используя информацию, предоставленную в JWT. Новые учетные записи обычно не имеют пароля. Рекомендуется добавить Google Sign In на другие платформы, чтобы пользователи могли входить через Google на всех поверхностях вашего приложения. Кроме того, вы можете отправить пользователю по электронной почте ссылку, которая запускает процесс восстановления пароля, чтобы пользователь мог установить пароль для входа на других платформах.
По завершении создания выдайте токен доступа и верните значения в объекте JSON в теле ответа HTTPS, как в следующем примере:
{
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}
Разработайте голосовой пользовательский интерфейс для потока аутентификации
Проверьте, проверен ли пользователь, и запустите процесс привязки учетной записи.
- Откройте проект Actions Builder в консоли действий .
- Создайте новую сцену, чтобы начать привязку учетной записи в своем действии:
- Щелкните Сцены .
- Щелкните значок добавления (+), чтобы добавить новую сцену.
- В только что созданной сцене щелкните значок add для условий .
- Добавьте условие, которое проверяет, является ли пользователь, связанный с беседой, проверенным пользователем. Если проверка не пройдена, ваше действие не может выполнить привязку учетной записи во время разговора и должно вернуться к предоставлению доступа к функциям, не требующим привязки учетной записи.
- В поле
Enter new expressionпод Условием введите следующую логику:user.verificationStatus != "VERIFIED" - В разделе «Переход» выберите сцену, которая не требует привязки учетной записи, или сцену, которая является точкой входа в функциональность только для гостей.
- В поле
- Щелкните значок add для условий .
- Добавьте условие для запуска процесса связывания учетных записей, если у пользователя нет связанного удостоверения.
- В поле
Enter new expressionпод Условием введите следующую логику::user.verificationStatus == "VERIFIED" - В разделе «Переход» выберите системную сцену «Привязка учетной записи» .
- Нажмите Сохранить .
- В поле
После сохранения в ваш проект добавляется новая системная сцена привязки учетных записей под названием <SceneName>_AccountLinking .
Настройте сцену привязки учетной записи
- В разделе «Сцены» выберите системную сцену, связанную с учетной записью.
- Нажмите «Отправить приглашение» и добавьте короткое предложение, чтобы описать пользователю, почему действие должно получить доступ к его удостоверению (например, «Чтобы сохранить ваши настройки»).
- Нажмите Сохранить .
- В разделе «Условия» щелкните «Если пользователь успешно завершил привязку учетной записи» .
- Настройте, как должен действовать поток, если пользователь соглашается связать свою учетную запись. Например, вызовите веб-перехватчик, чтобы обработать любую необходимую пользовательскую бизнес-логику и вернуться к исходной сцене.
- Нажмите Сохранить .
- В разделе «Условия» нажмите «Если пользователь отменит или отклонит привязку учетной записи» .
- Настройте, как должен действовать поток, если пользователь не согласен связать свою учетную запись. Например, отправьте подтверждающее сообщение и перенаправьте на сцены, которые предоставляют функции, не требующие привязки учетной записи.
- Нажмите Сохранить .
- В разделе Условия щелкните Если произошла системная или сетевая ошибка .
- Настройте, как должен действовать процесс, если процесс связывания учетных записей не может быть завершен из-за системных или сетевых ошибок. Например, отправьте подтверждающее сообщение и перенаправьте на сцены, которые предоставляют функции, не требующие привязки учетной записи.
- Нажмите Сохранить .
Обработка запросов на доступ к данным
Если запрос Ассистента содержит токен доступа , сначала убедитесь, что токен доступа действителен и срок его действия не истек, а затем извлеките из базы данных учетных записей пользователей учетную запись пользователя, связанную с токеном.