Guía conceptual de vinculación del Acceso con Google basado en OAuth

El tipo de vinculación "optimizado" del Acceso con Google basado en OAuth agrega el Acceso con Google a la vinculación de cuentas basada en OAuth. Si usas este tipo de vinculación en tu Acción, el flujo comienza con el Acceso con Google, que te permite verificar si la información de perfil del usuario en Google existe en tu sistema. De lo contrario, se inicia un flujo estándar de OAuth. Si proporcionas una combinación de estos dos tipos de vinculación, tus usuarios pueden vincular su identidad en tu Acción con una Cuenta de Google o una que no sea de Google. Si lo desean, también pueden crear una cuenta nueva con la información de su perfil de Google.

La vinculación optimizada es la solución de vinculación de cuentas recomendada si se aplica alguna de las siguientes condiciones:

  • Tienes una acción que abarca varias plataformas (por ejemplo, si funciona con una app para Android).
  • Tienes un sistema de autenticación existente y deseas permitir que los usuarios vinculen sus identidades con cuentas que no sean de Google. Por ejemplo, si ofreces un programa de lealtad y quieres asegurarte de que el usuario no pierda los puntos acumulados en su cuenta existente.

Para verificar que la vinculación optimizada es la solución adecuada para ti, consulta la página Elige tu tipo de vinculación de cuenta.

Términos clave

Antes de leer sobre cómo funciona la vinculación optimizada, familiarízate con los siguientes términos:

  • Token de ID de Google: es una aserción firmada de la identidad de un usuario que contiene la información básica de perfil de Google de este (su nombre, dirección de correo electrónico y foto de perfil). Un token de ID de Google es un token web JSON (JWT). El siguiente es un ejemplo de un token decodificado:
{
  "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"
}
  • user.verificationStatus: Es una propiedad que establece el sistema para indicar si la sesión actual tiene un usuario verificado.

  • user.accountLinkingStatus: Es una propiedad que establece el sistema para indicar si el usuario de la sesión actual tiene una identidad vinculada.

  • Escena del sistema de vinculación de cuentas: Es una escena predefinida que implementa el flujo de confirmación para la vinculación de cuentas y se puede personalizar para adaptarla a casos de uso específicos.

  • Flujo de código de autorización: Es un flujo de OAuth 2.0 que puedes implementar con la vinculación optimizada. Este flujo requiere los siguientes dos extremos:

    • Extremo de autorización: Es el extremo que presenta la IU de acceso a los usuarios que aún no accedieron. Registra el consentimiento para el acceso solicitado en forma de un código de autorización de corta duración.
    • Extremo de intercambio de token: Este extremo 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 se produce cuando Google necesita un nuevo token de acceso porque el que venció.
  • Flujo de código implícito: Es un flujo de OAuth 2.0 que puedes implementar con la vinculación optimizada. Este flujo solo requiere un extremo de autorización. Durante este flujo, Google abre tu extremo de autorización en el navegador del usuario. Si el acceso se realiza correctamente, muestras un token de acceso de larga duración a Google. Este token de acceso ahora se incluye en cada solicitud que se envía desde Asistente a tu Acción.

  • Token de acceso: Es un token que autoriza a tu servicio a acceder a partes de los datos de un usuario. Los tokens de acceso se asocian con cada usuario individual.

  • Token de actualización: Es un token que se intercambia por un token de acceso nuevo una vez que vence un token de acceso de corta duración.

Requisitos previos

Para usar el tipo de vinculación optimizado, debe hacer lo siguiente:

  • Un servidor de OAuth 2.0
  • Un extremo de intercambio de tokens

    El extremo de intercambio de token se debe extender para agregar compatibilidad con los protocolos de Google de vinculación automática y creación de cuentas desde un token de ID (es decir, agregar los parámetros intent=get y intent=create en las solicitudes a este extremo).

Cómo funciona

En esta sección, se describe el flujo general de la vinculación optimizada. En la siguiente sección, Flujos de vinculación optimizados, se describen los diversos flujos que pueden ocurrir según a) si habilitas o inhabilitas la creación de cuentas mediante la voz y b) si usas el flujo de código implícito o de autorización.

El flujo fundamental es el siguiente:

  1. Tu Acción le solicita al usuario el consentimiento para acceder a su perfil de Google.
  2. Una vez que el usuario da su consentimiento, tu Acción recibe un token de ID de Google que contiene la información de perfil de Google del usuario.
  3. Debes validar y decodificar el token para leer el contenido del perfil.
  4. Tu Acción usa este token para verificar si la información de perfil de Google del usuario existe en tu sistema.
    1. Si lo hace, el usuario ya accedió al sistema con su Cuenta de Google, y Asistente vinculará la identidad del usuario con su Cuenta de Google. El usuario puede continuar la conversación con Asistente con su cuenta vinculada.
    2. Si no es así, consulta el paso 5.
  5. El usuario puede a) crear una cuenta nueva con la información de su perfil de Google o b) acceder a tu sistema con una cuenta diferente. Las opciones que se le presentan al usuario difieren en función de si habilitas o inhabilitas la creación de cuentas mediante la voz. Si el usuario elige acceder a tu sistema con una cuenta diferente, se inicia el flujo estándar de OAuth.
  6. Después de que el usuario crea una cuenta nueva o accede con otro proveedor, el servicio le muestra un token de acceso a Google. (Si usas el flujo de código de autorización, tu servicio también muestra un token de actualización).
  7. El usuario ahora puede continuar la conversación con Asistente con su cuenta vinculada.

Flujos de vinculación optimizados

En esta sección, se explican los diversos flujos que pueden ocurrir con la vinculación optimizada. En estos diagramas, se muestran los flujos que se producen con el flujo de código de autorización en lugar del flujo de código implícito y se presupone que usas Actions Builder.

Cada flujo contiene estos pasos comunes después de que el usuario invoca tu acción:

En el flujo anterior, realizas la transición a la escena del sistema de vinculación de cuentas y proporcionas una lógica personalizada. En la escena, se le solicita permiso al usuario para acceder a la información de su perfil de Google. Una vez que el usuario otorga su consentimiento, Asistente envía una solicitud que contiene la información de perfil de user@gmail.com.

Los flujos después de este punto difieren en función de si configuras la vinculación de cuentas con la voz y de si la información del usuario ya existe en tu sistema. Cada uno de estos flujos se describe en las siguientes secciones.

Flujos con la creación de cuentas de voz habilitada

En esta sección, se detallan los flujos de vinculación de cuentas que pueden ocurrir si habilitas la creación de cuentas mediante la voz.

Flujo 1: La información del usuario existe en tu sistema

En este caso, el usuario representado por user@gmail.com existe en tu backend, por lo que tu extremo de intercambio de tokens muestra un token para el usuario. La identidad del usuario en tu Acción ahora está vinculada a su Cuenta de Google. La solicitud original del usuario ("Pedir mi pedido de siempre") coincide con el intent del usuario order_drink. Luego, tu webhook maneja la entrega del intent coincidente y consulta tu base de datos para obtener el pedido habitual de user@gmail.com. El usuario puede continuar su conversación con Asistente.

Flujo 2: La información del usuario no existe, y el usuario crea una cuenta

Debido a que habilitaste la creación de cuentas con la voz y user@gmail.com no existe en tu backend, Asistente le preguntará al usuario si desea realizar alguna de las siguientes acciones:

a) Crea una cuenta nueva en tu sistema con la información de perfil de Google, que se logra mediante la voz

b) Accede al sistema con otra cuenta.

En este caso, el usuario elige crear una cuenta nueva mediante la voz. Google llama al extremo de intercambio de tokens de tu servicio con una solicitud para crear una cuenta. Esta solicitud contiene el token de ID de Google, que incluye los componentes necesarios para crear una cuenta nueva. Luego, puedes usar la información de este token (el nombre y la dirección de correo electrónico del usuario) para crearle una cuenta.

Después de crear la cuenta, el servicio muestra un token de acceso y un token de actualización para la cuenta recién creada. La identidad del usuario en tu Acción ahora está vinculada a su Cuenta de Google. La solicitud original del usuario (“Pedir mi pedido de siempre”) coincide con el intent del usuario. order_drink. Luego, tu webhook maneja la entrega del intent coincidente y consulta tu base de datos para obtener el orden habitual de user@gmail.com, que aún no existe porque el usuario es nuevo. Luego, tu Acción puede preguntarle al usuario qué le gustaría pedir.

Flujo 3: La información del usuario no existe, y el usuario accede con una cuenta diferente

Habilitaste la creación de cuentas por voz, por lo que Asistente le preguntará al usuario si desea realizar alguna de las siguientes acciones:

a) Crea una cuenta nueva en tu sistema con la información de perfil de Google, que se logra mediante la voz

b) Accede al sistema con otra cuenta.

En este caso, el usuario elige acceder con una cuenta diferente, lo que inicia el flujo estándar de OAuth. Si el flujo comenzó en un dispositivo que solo funciona por voz, Google transferirá la ejecución a un teléfono. Luego, Google abre tu extremo de autorización en el navegador del usuario y, según la configuración, el usuario puede elegir a) acceder al servicio con una cuenta existente que no use el Acceso con Google o b) crear una cuenta nueva con un proveedor diferente. Para obtener más información sobre el flujo de OAuth, consulta la guía de conceptos de vinculación de OAuth.

Después de verificar las credenciales del usuario, tu servicio muestra un token de acceso y un token de actualización a Google. La identidad del usuario en tu Acción ahora está vinculada a una cuenta que no es de Google. La solicitud original del usuario (“Pedir mi pedido de siempre”) coincide con el intent del usuario. order_drink. Luego, el webhook maneja la entrega del intent coincidente y consulta tu base de datos para conocer el pedido habitual de user@gmail.com, que aún no existe porque el usuario es nuevo. Luego, tu Acción puede preguntarle al usuario qué desea pedir o pedirle que configure su pedido habitual.

Flujo con la creación de cuentas de voz inhabilitada

En esta sección, se detalla el flujo de vinculación de cuentas que puede ocurrir si inhabilitas la creación de cuentas por voz.

Flujo 4: La información del usuario no existe

No habilitaste la creación de cuentas por voz y el usuario no existe en tu backend, por lo que comienza el flujo estándar de OAuth. Asistente abrirá el extremo de autorización en el navegador del usuario (si el flujo comenzó en un dispositivo solo de voz, Google transferirá la ejecución a un dispositivo con pantalla). El usuario puede elegir a) acceder con otro proveedor si se registró en tu servicio con una cuenta diferente o b) crear una cuenta nueva con otro proveedor. Para obtener más información sobre el flujo de OAuth, consulta la guía de conceptos de vinculación de OAuth.

Después de verificar las credenciales del usuario, tu servicio muestra un token de acceso y un token de actualización a Google. La identidad del usuario en tu Acción ahora está vinculada a una cuenta que no es de Google. La solicitud original del usuario (“Pedir mi pedido de siempre”) coincide con el intent del usuario. order_drink. Luego, el webhook maneja la entrega del intent coincidente y consulta tu base de datos para conocer el pedido habitual de user@gmail.com, que aún no existe porque el usuario es nuevo. Luego, tu Acción puede pedirle al usuario que configure su pedido habitual.