Концептуальное руководство по OAuth и входу в Google (Dialogflow)

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

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

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

Чтобы убедиться, что вход через OAuth и Google подходит вам, см. страницу «Выберите тип привязки учетной записи» .

Ключевые термины

Прежде чем читать о том, как работают OAuth и вход в Google, ознакомьтесь со следующими терминами:

  • Токен Google ID: подписанное подтверждение личности пользователя, содержащее основную информацию профиля пользователя Google (имя, адрес электронной почты и изображение профиля). Токен Google ID — это веб-токен JSON (JWT). Ниже приведен пример декодированного токена: 
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token'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"
}
  • Вспомогательное намерение для входа в учетную запись: вспомогательное намерение, которое вы вызываете, чтобы запросить у Ассистента процесс связывания учетной записи. Дополнительную информацию см. в разделе Вход в учетную запись .
    • Контекстная строка: настраиваемая строка, которую вы добавляете в вспомогательное намерение входа в учетную запись и которая сообщает пользователю, почему вы хотите связать его учетную запись.
  • Поток кода авторизации: поток OAuth 2.0, который можно реализовать с помощью OAuth + вход в Google. Для этого потока требуются две конечные точки:
    • Конечная точка авторизации: конечная точка, которая предоставляет пользовательский интерфейс входа вашим пользователям, которые еще не вошли в систему. Она записывает согласие на запрошенный доступ в форме кратковременного кода авторизации.
    • Конечная точка обмена токенами. Эта конечная точка отвечает за два типа обмена:
      1. Заменяет код авторизации на долгосрочный токен обновления и кратковременный токен доступа. Этот обмен происходит, когда пользователь проходит процедуру привязки учетной записи.
      2. Заменяет долгосрочный токен обновления на кратковременный токен доступа. Этот обмен происходит, когда Google нужен новый токен доступа, поскольку срок действия того, у которого истек срок действия.
  • Неявный поток кода: поток OAuth 2.0, который можно реализовать с помощью OAuth + вход в Google. Для этого потока требуется только конечная точка авторизации. Во время этого процесса Google открывает вашу конечную точку авторизации в браузере пользователя. Если вход успешен, вы возвращаете долгосрочный токен доступа в Google. Этот токен доступа теперь включается в каждый запрос, отправляемый Ассистентом к вашему действию.
  • Токен доступа: токен, который разрешает вашей службе получать доступ к частям данных пользователя. Токены доступа связаны с каждым отдельным пользователем.
  • Токен обновления: токен, который заменяется на новый токен доступа после истечения срока действия краткосрочного токена доступа.

Предварительные условия

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

  • Сервер OAuth 2

  • Конечная точка обмена токенами

    Конечную точку обмена токенами необходимо расширить, чтобы добавить поддержку протоколов Google для автоматического связывания и создания учетной записи на основе идентификационного токена (т. е. добавить параметры intent=get и intent=create в запросах к этой конечной точке).

Как это работает

В этом разделе описан общий процесс входа в систему через OAuth и Google. В следующем разделе «Потоки OAuth и GSI» описаны различные потоки, которые могут возникнуть в зависимости от того, а) включаете ли вы или отключите создание учетной записи с помощью голоса и б) используете ли вы неявный поток или поток кода авторизации.

Основной поток заключается в следующем:

  1. Ваше действие запрашивает у пользователя согласие на доступ к его профилю Google.
  2. После того как пользователь дает согласие, ваше действие получает токен идентификатора Google, который содержит информацию профиля Google пользователя.
  3. Вы должны проверить и декодировать токен, чтобы прочитать содержимое профиля.
  4. Ваше действие использует этот токен, чтобы проверить, существует ли информация профиля Google пользователя в вашей системе.
    1. Если да, то пользователь уже вошел в вашу систему под своей учетной записью Google, и Ассистент связывает личность пользователя с его учетной записью Google. Пользователь может продолжить общение с Ассистентом, привязав свою учетную запись.
    2. Если это не так, см. шаг 5.
  5. Пользователь может либо а) создать новую учетную запись, используя информацию своего профиля Google, либо б) войти в вашу систему, используя другую учетную запись. Варианты выбора, предлагаемые пользователю, различаются в зависимости от того, включаете ли вы или отключите создание учетной записи с помощью голоса. Если пользователь решает войти в вашу систему под другой учетной записью, начинается стандартный процесс OAuth.
  6. После того как пользователь создает новую учетную запись или входит в систему у другого провайдера, ваша служба возвращает токен доступа в Google. (Если вы используете поток кода авторизации, ваша служба также возвращает токен обновления.)
  7. Теперь пользователь может продолжить общение с Помощником, привязав свою учетную запись.

Потоки OAuth и GSI

В этом разделе рассматриваются различные потоки, которые могут возникнуть при использовании OAuth и GSI. На этих диаграммах показаны потоки, которые происходят с потоком кода авторизации , а не с потоком неявного кода, и предполагается, что вы используете Dialogflow в качестве решения для понимания естественного языка для вашего действия.

Каждый поток содержит следующие общие шаги после того, как пользователь вызывает ваше действие:

В приведенном выше потоке вы вызываете вспомогательное намерение actions.intent.SIGN_IN с настраиваемой вами контекстной строкой. Это намерение запрашивает у пользователя разрешение на доступ к информации его профиля Google. После согласия пользователя Ассистент отправляет запрос, содержащий информацию профиля для user@gmail.com .

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

Потоки с включенным созданием голосовой учетной записи

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

Последовательность 1: информация о пользователе существует в вашей системе.

В этом случае пользователь, представленный user@gmail.com , существует в вашей серверной части, поэтому ваша конечная точка обмена токенами возвращает токен для пользователя. Личность пользователя в вашем действии теперь связана с его учетной записью Google. Исходный запрос пользователя ( «Закажи мой обычный» ) соответствует пользовательскому намерению order_drink. Затем ваш вебхук обрабатывает выполнение совпадающего намерения и запрашивает в вашей базе данных обычный порядок пользователя user@gmail.com . После этого пользователь может продолжить разговор с Ассистентом.

Поток 2: информация пользователя не существует, и пользователь создает учетную запись.

Поскольку вы включили создание учетной записи с помощью голоса, а user@gmail.com не существует в вашей серверной части, Ассистент спрашивает пользователя, хочет ли он выполнить одно из следующих действий:

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

б) Войдите в свою систему под другой учетной записью.

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

После создания учетной записи ваша служба возвращает токен доступа и токен обновления для вновь созданной учетной записи. Личность пользователя в вашем действии теперь связана с его учетной записью Google. Исходный запрос пользователя ( «Закажи мой обычный» ) соответствует пользовательскому намерению order_drink. Затем ваш вебхук обрабатывает выполнение совпадающего намерения и запрашивает в вашей базе данных обычный порядок пользователя user@gmail.com , которого еще не существует, поскольку пользователь новый. Затем ваше действие может спросить пользователя, что он хочет заказать.

Последовательность 3: информация пользователя не существует, и пользователь входит в систему с другой учетной записью.

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

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

б) Войдите в свою систему под другой учетной записью.

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

После проверки учетных данных пользователя ваша служба возвращает в Google токен доступа и токен обновления. Личность пользователя в вашем действии теперь связана с учетной записью, не принадлежащей Google. Исходный запрос пользователя ( «Закажи мой обычный» ) соответствует пользовательскому намерению order_drink. Затем ваш вебхук обрабатывает выполнение совпадающего намерения и запрашивает в вашей базе данных обычный порядок пользователя user@gmail.com , которого еще не существует, поскольку пользователь новый. Затем ваше действие может спросить пользователя, что он хочет заказать, или попросить его настроить свой обычный порядок.

Flow с отключенным созданием голосовой учетной записи

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

Поток 4: информация пользователя не существует.

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

После проверки учетных данных пользователя ваша служба возвращает в Google токен доступа и токен обновления. Личность пользователя в вашем действии теперь связана с учетной записью, не принадлежащей Google. Исходный запрос пользователя ( «Закажи мой обычный» ) соответствует пользовательскому намерению order_drink. Затем ваш вебхук обрабатывает выполнение совпадающего намерения и запрашивает в вашей базе данных обычный порядок user@gmail.com , которого еще не существует, поскольку пользователь новый. Затем ваше действие может попросить пользователя настроить свой обычный порядок.