Vinculación de cuentas con OAuth

El tipo de vinculación de OAuth es compatible con dos flujos de OAuth 2.0 estándar de la industria: los flujos de código implícito y de autorización.

En el flujo de código implícito, Google abre tu extremo de autorización en el navegador del usuario. Después de acceder correctamente, devuelves un token de acceso de larga duración a Google. Este token de acceso ahora se incluye en cada solicitud que envía el Asistente a tu acción.

En el flujo de código de autorización, necesitas dos extremos:

  • El extremo authorization, que se encarga de presentar la IU de acceso a los usuarios que aún no accedieron y de registrar el consentimiento para el acceso solicitado en forma de un código de autorización de corta duración.
  • El extremo de intercambio de tokens, que es responsable de dos tipos de intercambios:
    1. Intercambia un código de autorización por un token de actualización de larga duración y un token de acceso de corta duración. Este intercambio se produce cuando el usuario pasa por el flujo de vinculación de cuentas.
    2. Intercambia un token de actualización de larga duración por un token de acceso de corta duración. Este intercambio ocurre cuando Google necesita un token de acceso nuevo porque el que había vencido.

Si bien el flujo de código implícito es más fácil de implementar, Google recomienda que los tokens de acceso emitidos con el flujo implícito nunca venzan, porque el vencimiento del token con el flujo implícito obliga al usuario a vincular su cuenta nuevamente. Si necesitas el vencimiento del token por razones de seguridad, debes considerar usar el flujo de código de Auth.

Implementa la vinculación de cuentas mediante OAuth

Configura el proyecto

Si deseas configurar tu proyecto para que use la vinculación de OAuth, sigue estos pasos:

  1. Abre la Consola de Actions y selecciona el proyecto que deseas usar.
  2. Haz clic en la pestaña Desarrollo y elige Vinculación de cuentas.
  3. Habilita el interruptor que se encuentra junto a Vinculación de cuentas.
  4. En la sección Creación de cuenta, selecciona No, solo quiero permitir la creación de cuentas en mi sitio web.
  5. En Tipo de vinculación, selecciona OAuth y Código de autorización.

  6. En Información del cliente (Client information), haz lo siguiente:

    • Asigna un valor al ID de cliente emitido por tus acciones a Google para identificar las solicitudes que provienen de Google.
    • Toma nota del valor del ID de cliente emitido por Google para tus acciones.
    • Inserta las URL para tus extremos de autorización y de intercambio de tokens.
  1. Haz clic en Guardar.

Implementa tu servidor OAuth

Una implementación del servidor OAuth 2.0 del flujo de código de autorización consta de dos extremos, que tu servicio pone a disposición mediante HTTPS. El primer extremo es el de autorización, que es responsable de obtener el consentimiento de los usuarios para el acceso a los datos o de encontrar el resultado. El extremo de autorización presenta una IU de acceso a los usuarios que aún no accedieron y registra el consentimiento para el acceso solicitado. El segundo extremo es el de intercambio de tokens, que se usa para obtener strings encriptadas llamadas tokens que autorizan al usuario de la acción a acceder a tu servicio.

Cuando tu Acción necesita llamar a una de las APIs de tu servicio, Google usa estos extremos juntos a fin de obtener el permiso de tus usuarios para llamar a estas APIs en su nombre.

La sesión de flujo de código de autorización de OAuth 2.0 que inicia Google tiene el siguiente flujo:

  1. Google abrirá tu extremo de autorización en el navegador del usuario. Si el flujo de una Acción se inició en un dispositivo que solo funciona por voz, Google transferiría la ejecución a un teléfono.
  2. El usuario accede (si aún no lo hizo) y le otorga permiso a Google para acceder a sus datos con tu API si aún no lo hizo.

  3. El servicio crea un código de autorización y lo muestra a Google cuando se redirecciona el navegador del usuario a Google con el código de autorización adjunto a la solicitud.

  4. Google envía el código de autorización a tu extremo de intercambio de tokens, que verifica la autenticidad del código y muestra un token de acceso y un token de actualización. El token de acceso es un token de corta duración que tu servicio acepta como credenciales para acceder a las APIs. El token de actualización es de larga duración que Google puede almacenar y usar para adquirir tokens de acceso nuevos cuando venzan.

  5. Después de que el usuario complete el flujo de vinculación de cuentas, cada solicitud posterior que se envíe desde el Asistente a tu webhook de entrega contendrá un token de acceso.

Cómo controlar solicitudes de autorización

Cuando tu Acción necesita realizar una vinculación de cuentas a través de un flujo de código de autorización de OAuth 2.0, Google envía al usuario a tu extremo de autorización con una solicitud que incluye los siguientes parámetros:

Parámetros del extremo de autorización
client_id El ID de cliente de Google que registraste en Google.
redirect_uri La URL a la que envías la respuesta a esta solicitud.
state Es un valor de contabilidad que se pasa a Google sin cambios en el URI de redireccionamiento.
scope Opcional: Un conjunto de strings de alcance delimitado por espacios que especifica los datos para los que Google solicita autorización.
response_type La string code.

Por ejemplo, si tu extremo de autorización está disponible en https://myservice.example.com/auth, una solicitud podría verse de la siguiente manera:

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

Para que tu extremo de autorización controle las solicitudes de acceso, sigue estos pasos:

  1. Verifica que client_id coincida con el ID de cliente de Google que registraste en Google y que redirect_uri coincida con la URL de redireccionamiento proporcionada por Google para tu servicio. Estas verificaciones son importantes para evitar otorgar acceso a apps cliente mal configuradas o no deseadas.

    Si admites varios flujos de OAuth 2.0, confirma también que response_type sea code.

  2. Verifica si el usuario accedió a tu servicio. Si el usuario no accedió, completa el flujo de acceso o registro de tu servicio.

  3. Genera un código de autorización que Google usará para acceder a tu API. El código de autorización puede ser cualquier valor de cadena, pero debe representar de manera inequívoca al usuario, al cliente al que pertenece el token y a la fecha de vencimiento del código, y no debe ser adivinable. Por lo general, emites códigos de autorización que vencen después de unos 10 minutos.

  4. Confirma que la URL especificada por el parámetro redirect_uri tenga el siguiente formato:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
    YOUR_PROJECT_ID es el ID que se encuentra en la página Configuración del proyecto de la Consola de Actions.

  5. Redirecciona el navegador del usuario a la URL especificada por el parámetro redirect_uri. Incluye el código de autorización que acabas de generar y el valor de estado original sin modificar cuando realices el redireccionamiento agregando los parámetros code y state. A continuación, se muestra un ejemplo de la URL resultante:

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

Cómo controlar solicitudes de intercambio de tokens

El extremo de intercambio de tokens de tu servicio es responsable de dos tipos de intercambio de tokens:

  • Intercambia códigos de autorización por tokens de acceso y tokens de actualización
  • Intercambia tokens de actualización por tokens de acceso

Las solicitudes de intercambio de tokens incluyen los siguientes parámetros:

Parámetros del extremo de intercambio de tokens
client_id Es una cadena que identifica el origen de la solicitud como Google. Esta string debe estar registrada en tu sistema como el identificador único de Google.
client_secret Una string secreta que registraste en Google para tu servicio.
grant_type El tipo de token que se intercambia. authorization_code o refresh_token.
code Cuando es grant_type=authorization_code, el código que Google recibió del extremo de intercambio de tokens o de acceso
redirect_uri Cuando es grant_type=authorization_code, este parámetro es la URL que se usa en la solicitud de autorización inicial.
refresh_token Cuando es grant_type=refresh_token, el token de actualización que Google recibió del extremo de intercambio de tokens.
Intercambia códigos de autorización por tokens de acceso y tokens de actualización

Después de que el usuario accede y el extremo de autorización le muestra un código de autorización de corta duración a Google, Google envía una solicitud a tu extremo de intercambio de tokens para intercambiar el código de autorización por un token de acceso y un token de actualización.

Para estas solicitudes, el valor de grant_type es authorization_code, y el valor de code es el valor del código de autorización que le otorgaste a Google antes. El siguiente es un ejemplo de una solicitud para intercambiar un código de autorización por un token de acceso y un token de actualización:

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

Para intercambiar códigos de autorización por un token de acceso y un token de actualización, el extremo de intercambio de tokens responde a las solicitudes POST que ejecutan los siguientes pasos:

  1. Verifica que client_id identifique el origen de la solicitud como un origen autorizado y que client_secret coincida con el valor esperado.
  2. Verifica lo siguiente:
    • El código de autorización es válido y no está vencido, y el ID de cliente especificado en la solicitud coincide con el ID de cliente asociado con el código de autorización.
    • La URL que especifica el parámetro redirect_uri es idéntica al valor utilizado en la solicitud de autorización inicial.
  3. Si no puedes verificar todos los criterios anteriores, muestra un error HTTP 400 de solicitud incorrecta con {"error": "invalid_grant"} como cuerpo.
  4. De lo contrario, genera un token de actualización y un token de acceso con el ID de usuario del código de autorización. Estos tokens pueden ser cualquier valor de cadena, pero deben representar de forma única al usuario y al cliente para el que se encuentra el token, y no deben poder adivinarse. En el caso de los tokens de acceso, también registra la hora de vencimiento del token (por lo general, una hora después de su emisión). Los tokens de actualización no vencen.
  5. Muestra el siguiente objeto JSON en el cuerpo de la respuesta HTTPS:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }
    

Google almacena el token de acceso y el de actualización para el usuario y registra el vencimiento del token de acceso. Cuando vence el token de acceso, Google usa el token de actualización para obtener uno nuevo del extremo de intercambio de tokens.

Intercambia tokens de actualización por tokens de acceso

Cuando vence un token de acceso, Google envía una solicitud a tu extremo de intercambio de tokens para intercambiar un token de actualización por uno nuevo.

Para estas solicitudes, el valor de grant_type es refresh_token, y el valor de refresh_token es el valor del token de actualización que le otorgaste a Google. El siguiente es un ejemplo de una solicitud para intercambiar un token de actualización por un token de acceso:

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

Para intercambiar un token de actualización por un token de acceso, el extremo de intercambio de tokens responde a las solicitudes POST que ejecutan los siguientes pasos:

  1. Verifica que client_id identifique el origen de la solicitud como Google y que client_secret coincida con el valor esperado.
  2. Verifica que el token de actualización sea válido y que el ID de cliente especificado en la solicitud coincida con el ID de cliente asociado con el token de actualización.
  3. Si no puedes verificar todos los criterios anteriores, muestra un error HTTP 400 de solicitud incorrecta con {"error": "invalid_grant"} como cuerpo.
  4. De lo contrario, usa el ID de usuario del token de actualización para generar un token de acceso. Estos tokens pueden ser cualquier valor de cadena, pero deben representar de manera inequívoca al usuario y al cliente para el que se encuentra el token, y no deben poder adivinarse. En el caso de los tokens de acceso, también registra la hora de vencimiento del token (por lo general, una hora después de su emisión).
  5. Muestra el siguiente objeto JSON en el cuerpo de la respuesta HTTPS:
    {
    "token_type": "Bearer",
    "access_token": "ACCESS_TOKEN",
    "expires_in": SECONDS_TO_EXPIRATION
    }

Diseñar la interfaz de usuario de voz para el flujo de autenticación

Comprueba si el usuario está verificado y comienza el flujo de vinculación de cuentas

  1. Abre tu proyecto de Actions Builder en la Consola de Actions.
  2. Crea una escena nueva para comenzar a vincular cuentas en tu acción:
    1. Haz clic en Scenes.
    2. Haz clic en el ícono de agregar (+) para agregar una escena nueva.
  3. En la escena recién creada, haz clic en el ícono de agregar para Conditions.
  4. Agrega una condición que verifique si el usuario asociado con la conversación es un usuario verificado. Si la verificación falla, tu Acción no podrá realizar la vinculación de cuentas durante la conversación y debería volver a proporcionar acceso a la funcionalidad que no requiera la vinculación de cuentas.
    1. En el campo Enter new expression, en Condición, ingresa la siguiente lógica: user.verificationStatus != "VERIFIED"
    2. En Transición, selecciona una escena que no requiera la vinculación de una cuenta o una que sea el punto de entrada a la funcionalidad solo para invitados.

  1. Haz clic en el ícono de agregar para Conditions.
  2. Agrega una condición para activar un flujo de vinculación de cuentas si el usuario no tiene una identidad asociada.
    1. En el campo Enter new expression, en Condición, ingresa la siguiente lógica: user.verificationStatus == "VERIFIED"
    2. En Transition, selecciona la escena del sistema Account Linking.
    3. Haz clic en Guardar.

Después de guardar, se agrega a tu proyecto una nueva escena del sistema de vinculación de cuentas llamada <SceneName>_AccountLinking.

Personaliza la escena de vinculación de cuentas

  1. En Scenes, selecciona la escena del sistema de vinculación de cuentas.
  2. Haz clic en Send prompt y agrega una oración breve para describirle al usuario por qué la acción necesita acceder a su identidad (por ejemplo, "Para guardar tus preferencias").
  3. Haz clic en Guardar.

  1. En Condiciones, haz clic en Si el usuario completa la vinculación de cuentas correctamente.
  2. Configura cómo debe proceder el flujo si el usuario acepta vincular su cuenta. Por ejemplo, llama al webhook para procesar cualquier lógica empresarial personalizada que se requiera y realizar la transición a la escena de origen.
  3. Haz clic en Guardar.

  1. En Condiciones, haz clic en Si el usuario cancela o descarta la vinculación de cuentas.
  2. Configura cómo debe proceder el flujo si el usuario no acepta vincular su cuenta. Por ejemplo, envía un mensaje de confirmación y redirecciona a escenas que proporcionen funcionalidades que no requieren la vinculación de cuentas.
  3. Haz clic en Guardar.

  1. En Condiciones, haz clic en Si se produce un error de sistema o red.
  2. Configura cómo debe proceder el flujo si el flujo de vinculación de cuentas no se puede completar debido a errores del sistema o de la red. Por ejemplo, envía un mensaje de confirmación y redirecciona a escenas que proporcionen funcionalidades que no requieren la vinculación de cuentas.
  3. Haz clic en Guardar.

Controla las solicitudes de acceso a los datos

Si la solicitud de Asistente contiene un token de acceso, primero verifica que el token sea válido (y no haya vencido) y, luego, recupera la cuenta de usuario asociada de tu base de datos.