El tipo de vinculación de cuentas de OAuth es compatible con dos flujos de OAuth 2.0 estándar de la industria: el implícito y el de código de autorización. En el flujo de código implícito, Google abre el extremo de autorización en el navegador del usuario. Después de acceder correctamente, muestras un token de acceso de larga duración a Google. Este token de acceso se incluye en cada solicitud que se envía desde Asistente a tu Acción.
OAuth es la solución de vinculación de cuentas recomendada si se aplica alguna de las siguientes condiciones:
- Tienes una implementación existente de un servidor OAuth 2.0 y no puedes extender el extremo de intercambio de tokens 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, agrega los parámetros
intent=getyintent=createen las solicitudes a este extremo).
A fin de verificar que OAuth sea la solución adecuada para ti, consulta la página Elige tu tipo de vinculación de cuentas.
Términos clave
Antes de entender cómo funciona OAuth, familiarízate con los siguientes términos:
- Intent auxiliar de acceso a la cuenta: Es un intent de ayuda que llamas para solicitar un flujo de vinculación de cuentas de Asistente. Para obtener más información, consulta Acceso a la cuenta.
- String de contexto: Es una string personalizada que agregas al intent auxiliar de acceso de la cuenta que le indica al usuario por qué necesitas que vincule su cuenta.
Flujo de código de autorización: Durante este flujo de OAuth 2.0, Google abre tu extremo de autorización en el navegador del usuario. Si el acceso se realiza correctamente, tu servicio crea un código de autorización y se lo muestra a Google. Google envía este código de autorización a tu extremo de intercambio de token, que verifica la autenticidad del código y devuelve un token de acceso y de actualización.
Este flujo requiere los siguientes dos extremos:
- Extremo de autorización: Es el extremo responsable de encontrar o de obtener el consentimiento de los usuarios para el acceso a los datos. Este extremo hace lo siguiente:
- Presenta la IU de acceso a los usuarios que aún no accedieron.
- Los registros otorgan su 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 se usa para obtener strings encriptadas llamadas tokens que autorizan al usuario de Action a acceder a tu servicio. Este extremo es responsable de dos tipos de intercambios:
- 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.
- 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ó.
- Extremo de autorización: Es el extremo responsable de encontrar o de obtener el consentimiento de los usuarios para el acceso a los datos. Este extremo hace lo siguiente:
Flujo de código implícito: Durante este flujo de OAuth 2.0, 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 se incluye en cada solicitud que se envía desde Asistente a tu Acción. Este flujo solo requiere un extremo de autorizació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 y deben ser indescifrables.
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.
Cómo funciona
En esta sección, se describe el flujo general del código de autorización de OAuth y los flujos implícitos. En la siguiente sección, Flujos de OAuth, se describen los diversos flujos que pueden ocurrir con OAuth.
El flujo de código de autorización se puede resumir de la siguiente manera:
- Tu Acción le pregunta al usuario si quiere vincular su cuenta con tu servicio.
- Una vez que el usuario acepta vincular las cuentas, Google abre tu extremo de autorización en el navegador del usuario. Si el flujo se inicia en un dispositivo que solo requiere voz para una Acción, Google transferiría la ejecución a un teléfono.
- 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).
- 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.
- 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 vencen.
- 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.
El flujo de código implícito se puede resumir de la siguiente manera:
- Tu Acción le pregunta al usuario si quiere vincular su cuenta con tu servicio.
- Una vez que el usuario acepta vincular las cuentas, Google abre tu extremo de autorización en el navegador del usuario.
- 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).
- Tu servicio crea un token de acceso y lo muestra a Google. Para ello, redirecciona el navegador del usuario a Google con el token de acceso adjunto a la solicitud.
- Después de que el usuario completa el flujo de vinculación de cuentas, Google llama a las APIs de tu servicio y adjunta el token de acceso con cada solicitud. Tu servicio verifica que el token de acceso otorgue a Google autorización para acceder a la API y, luego, completa la llamada a la API.
El flujo de código de autorización fundamental es el siguiente:
- Tu Acción le pregunta al usuario si quiere vincular su cuenta con tu servicio.
- Una vez que el usuario acepta vincular las cuentas, Google abre tu extremo de autorización en el navegador del usuario. Si el flujo se inicia en un dispositivo que solo requiere voz para una Acción, Google transferiría la ejecución a un teléfono.
- 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).
- El servicio crea un código de autorización y lo muestra a Google cuando redirecciona el navegador del usuario a Google con el código de autorización de corta duración adjunto a la solicitud.
- 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 vencen.
- 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.
Flujos de OAuth
En esta sección, se explican los diversos flujos que pueden ocurrir con OAuth.
Cada flujo contiene estos pasos comunes después de que el usuario invoca tu acción:
En el flujo anterior, llamas al intent auxiliar actions.intent.SIGN_IN para iniciar el flujo de vinculación de cuentas. Asistente le preguntará al usuario si desea vincular su cuenta con tu servicio y le mostrará una pantalla con los permisos solicitados. Cuando el usuario otorga su consentimiento, Google lo redirecciona al extremo de autorización de tu servicio en el navegador. El usuario accede (o, según la configuración, crea una cuenta nueva) y le otorga a tu Acción permiso para acceder a sus datos.
Los flujos después de este punto difieren en función de si implementaste el flujo implícito o el flujo de código de autorización. Estos flujos se describen en las siguientes secciones.
Flujo 1: El usuario accede con un flujo implícito
Una vez que el usuario accede y se verifican sus credenciales, el servicio crea un token de acceso de larga duración y lo muestra a Google. En este punto, la identidad del usuario en tu Acción está vinculada a la cuenta con la que accedió, y el token de acceso se adjunta a cada llamada a la API que Google realiza a las APIs de tu servicio.
Flujo 2: El usuario accede con el flujo de código de autorización
Una vez que el usuario accede y se verifican sus credenciales, el servicio crea un código de autorización y lo muestra a Google.
Este código de autorización se envía a tu extremo de intercambio de token, que muestra un token de acceso y un token de actualización. En este punto, la identidad del usuario en tu Acción está vinculada a cualquier cuenta con la que haya accedido, y cada solicitud posterior que se envía desde Asistente a tu entrega contiene un token de acceso.