Se usó la API de Cloud Translation para traducir esta página.

Guía de conceptos para la vinculación al acceso de Google basada en OAuth "Optimizada"

El tipo de vinculación “Optimizada” de Acceso con Google basado en OAuth agrega el Acceso con Google además de 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 del perfil de Google del usuario existe en tu sistema. Si no lo hace, se inicia un flujo de OAuth estándar. Cuando 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 sin ella. 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 tu acción funciona con una app para Android).
Si tienes un sistema de autenticación existente y deseas permitir que los usuarios vinculen sus identidades con cuentas ajenas a 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 el tipo de vinculación de cuentas.

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: Una aserción firmada de la identidad de un usuario que contiene información básica del perfil de Google del usuario (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 el sistema establece para indicar si la sesión actual tiene un usuario verificado.
user.accountLinkingStatus: Es una propiedad que el sistema establece para indicar si el usuario que está en 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 que se puede personalizar a fin de que se ajuste a casos prácticos específicos.
Flujo de código de autorización: Un flujo de OAuth 2.0 que puedes implementar con la vinculación optimizada. Este flujo requiere dos extremos:
- Extremo de autorización: 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 tokens: 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 ocurre 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 venció.
Flujo de código implícito: 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 completa correctamente, se muestra un token de acceso de larga duración a Google. Este token de acceso ahora se incluye en todas las solicitudes que envía Asistente a tu acción.
Token de acceso: Es un token que autoriza a tu servicio a acceder a partes de los datos del 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 optimizada, necesita lo siguiente:

Un servidor OAuth 2.0
Un extremo de intercambio de tokens

El extremo del intercambio de tokens se debe extender a fin de agregar compatibilidad con los protocolos de Google para la vinculación automática y la creación de cuentas desde un token de ID (es decir, agrega los parámetros intent=get y intent=create a 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 voz y b) si usas el flujo de código implícito o de autorización.

El flujo fundamental es el siguiente:

Tu Acción solicita al usuario su consentimiento para acceder a su perfil de Google.
Una vez que el usuario da su consentimiento, tu acción recibe un token de ID de Google que contiene la información del perfil de Google del usuario.
Debes validar y decodificar el token para leer el contenido del perfil.
Tu acción usa este token para comprobar si la información del perfil de Google del usuario existe en tu sistema.
1. Si lo hace, el usuario ya accedió a tu sistema con su Cuenta de Google, y Asistente vincula 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 lo hace, consulta el paso 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 habilita o inhabilita la creación de la cuenta con la voz. Si el usuario decide acceder a tu sistema con una cuenta diferente, comienza el flujo estándar de OAuth.
Después de que el usuario cree una cuenta nueva o acceda con un proveedor diferente, tu servicio le mostrará 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).
El usuario ahora puede continuar la conversación con Asistente con su cuenta vinculada.

Flujos de vinculación optimizados

En esta sección, se repasan los diversos flujos que pueden ocurrir con la vinculación optimizada. Estos diagramas repasan los flujos que ocurren con el flujo de código de autorización en lugar del flujo de código implícito, y suponen que usas Actions Builder.

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

En el flujo anterior, haces la transición a la escena del sistema de vinculación de cuentas y proporcionas una lógica personalizada. La escena le solicita permiso al usuario para acceder a la información de su perfil de Google. Una vez que el usuario otorgue su consentimiento, Asistente enviará una solicitud con la información del perfil de user@gmail.com.

Los flujos después de este punto difieren en función de si configuraste o no la vinculación de cuentas con la voz y 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 por 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 el extremo del 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 rutina”) coincide con el intent del usuario order_drink. Tu webhook luego controla la entrega del intent coincidente y consulta su base de datos para ver el orden 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 por voz y user@gmail.com no existe en tu backend, Asistente le pregunta al usuario si quiere hacer lo siguiente:

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

b) Accede a tu sistema con una cuenta diferente.

En este caso, el usuario elige crear una nueva cuenta por 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) a fin de crearle una cuenta.

Después de crear la cuenta, tu 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 rutina”) coincide con el intent del usuario order_drink. Tu webhook luego se encarga de la entrega del intent coincidente y consulta a tu base de datos 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é quiere pedir.

Flujo 3: la información no existe y el usuario accede con otra cuenta

Habilitaste la creación de cuenta por voz, por lo que Asistente le pregunta al usuario si quiere realizar una de las siguientes acciones:

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

b) Accede a tu sistema con una cuenta diferente.

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 solo de voz, Google transfiere la ejecución a un teléfono. Luego, Google abre el extremo de autorización en el navegador del usuario y, según tu configuración, este puede elegir entre lo siguiente: 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 rutina”) coincide con el intent del usuario order_drink. Tu webhook luego se encarga de la entrega del intent coincidente y consulta a tu base de datos el orden habitual de user@gmail.com, que aún no existe porque el usuario es nuevo. Tu acción puede preguntarle al usuario qué le gustaría pedir o pedirle que configure su orden 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 abre el extremo de autorización en el navegador del usuario (si el flujo comenzó en un dispositivo solo de voz, Google transfiere la ejecución a un dispositivo con pantalla). El usuario puede elegir entre a) acceder con un proveedor diferente, si se registró en el servicio con una cuenta diferente, 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.