Привязка аккаунта с помощью OAuth

Тип связи OAuth поддерживает два стандартных потока OAuth 2.0: неявный поток и поток кода авторизации .

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

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

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

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

Реализуйте привязку учетных записей OAuth.

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

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

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

  5. В поле «Тип связи » выберите OAuth и « Код авторизации» .

  6. В информации о клиенте :

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

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

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

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

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

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

  2. Пользователь входит в систему (если он еще не вошел в систему) и предоставляет Google разрешение на доступ к своим данным с помощью вашего API, если он еще не предоставил разрешение.

  3. Ваш сервис создает код авторизации и возвращает его в Google, перенаправляя браузер пользователя обратно в Google с прикрепленным к запросу кодом авторизации.

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

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

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

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

Параметры конечной точки авторизации
client_id Идентификатор клиента Google, который вы зарегистрировали в Google.
redirect_uri URL-адрес, на который вы отправляете ответ на этот запрос.
state Бухгалтерское значение, которое передается обратно в Google без изменений в URI перенаправления.
scope Необязательно : набор строк области действия, разделенных пробелами, которые определяют данные, для которых Google запрашивает авторизацию.
response_type Строковый code .

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

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

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

  1. Убедитесь, что client_id соответствует идентификатору клиента Google, который вы зарегистрировали в Google, и что redirect_uri соответствует URL-адресу перенаправления, предоставленному Google для вашей службы. Эти проверки важны для предотвращения предоставления доступа непреднамеренным или неправильно настроенным клиентским приложениям.

    Если вы поддерживаете несколько потоков OAuth 2.0, также убедитесь, что response_type равен code .

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

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

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

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
    YOUR_PROJECT_ID — это идентификатор, который можно найти на странице настроек проекта в консоли действий.

  5. Перенаправьте браузер пользователя на URL-адрес, указанный параметром redirect_uri . Включите только что сгенерированный код авторизации и исходное неизмененное значение состояния при перенаправлении, добавив параметры code и state . Ниже приведен пример результирующего URL-адреса: 

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Обработка запросов на обмен токенов

Конечная точка обмена токенами вашей службы отвечает за два типа обмена токенов:

  • Обмен кодами авторизации для токенов доступа и токенов обновления.
  • Обмен токенов обновления на токены доступа

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

Параметры конечной точки обмена токенами
client_id Строка, которая идентифицирует источник запроса как Google. Эта строка должна быть зарегистрирована в вашей системе как уникальный идентификатор Google.
client_secret Секретная строка, которую вы зарегистрировали в Google для своей службы.
grant_type Тип обмениваемого токена. Либо authorization_code , либо refresh_token .
code grant_type=authorization_code — это код, который Google получил либо от вашей конечной точки входа, либо от конечной точки обмена токенами.
redirect_uri grant_type=authorization_code , этот параметр представляет собой URL-адрес, используемый в первоначальном запросе авторизации.
refresh_token grant_type=refresh_token — это токен обновления, который Google получил от вашей конечной точки обмена токенами.
Обмен кодами авторизации для токенов доступа и токенов обновления.

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

Для этих запросов значение grant_type — authorization_code , а значение code — это значение кода авторизации, который вы ранее предоставили Google. Ниже приведен пример запроса на обмен кода авторизации на токен доступа и токен обновления:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Для обмена кодами авторизации для токена доступа и токена обновления ваша конечная точка обмена токенами отвечает на запросы POST , выполняя следующие шаги:

  1. Убедитесь, что client_id идентифицирует источник запроса как авторизованный источник и что client_secret соответствует ожидаемому значению.
  2. Проверьте следующее:
    • Код авторизации действителен, срок его действия не истек, а идентификатор клиента, указанный в запросе, соответствует идентификатору клиента, связанному с кодом авторизации.
    • URL-адрес, указанный параметром redirect_uri , идентичен значению, используемому в первоначальном запросе авторизации.
  3. Если вы не можете проверить все вышеперечисленные критерии, верните ошибку HTTP 400 Bad Request с {"error": "invalid_grant"} в качестве тела.
  4. В противном случае, используя идентификатор пользователя из кода авторизации, сгенерируйте токен обновления и токен доступа. Эти токены могут иметь любое строковое значение, но они должны уникальным образом представлять пользователя и клиента, для которых предназначен токен, и их нельзя угадать. Для токенов доступа также запишите срок действия токена (обычно через час после выдачи токена). Токены обновления не имеют срока действия.
  5. Верните следующий объект JSON в текст ответа HTTPS:
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

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

Обмен токенов обновления на токены доступа

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

Для этих запросов grant_type — refresh_token , а refresh_token — это значение токена обновления, который вы ранее предоставили Google. Ниже приведен пример запроса на обмен токена обновления на токен доступа:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

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

  1. Убедитесь, что client_id идентифицирует источник запроса как Google и что client_secret соответствует ожидаемому значению.
  2. Убедитесь, что токен обновления действителен и что идентификатор клиента, указанный в запросе, соответствует идентификатору клиента, связанному с токеном обновления.
  3. Если вы не можете проверить все вышеперечисленные критерии, верните ошибку HTTP 400 Bad Request с {"error": "invalid_grant"} в качестве тела.
  4. В противном случае используйте идентификатор пользователя из токена обновления для создания токена доступа. Эти токены могут иметь любое строковое значение, но они должны уникальным образом представлять пользователя и клиента, для которых предназначен токен, и их нельзя угадать. Для токенов доступа также запишите срок действия токена (обычно через час после выдачи токена).
  5. Верните следующий объект JSON в текст ответа HTTPS:
    {
"token_type": "Bearer",
"access_token": " ACCESS_TOKEN ",
"expires_in": SECONDS_TO_EXPIRATION
}

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

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

  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. Нажмите Сохранить .

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

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