Vinculación de cuentas con OAuth

El tipo de vinculación de OAuth admite 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.

Nota: Elige el flujo de OAuth 2.0 que quieres implementar. Si es necesario, el contenido de esta guía se vuelve a cargar para adaptarlo a tu elección.

Código de autenticación Flujo implícito

Implementa la vinculación de cuentas de OAuth

Nota: Si implementas la vinculación de cuentas para administrar información financiera, ten en cuenta que se pueden aplicar políticas adicionales a tu acción. La revisión de una Acción con la vinculación de la cuenta para obtener información financiera puede tardar hasta seis semanas, por lo que debes tener en cuenta ese tiempo cuando planifiques tu programación de lanzamiento. A fin de facilitar el proceso de revisión, asegúrate de cumplir con las políticas de servicios financieros antes de enviar tu acción para su revisión.

Configura el proyecto

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

1. Abre la Consola de Actions y selecciona el proyecto que quieres usar.
2. Haz clic en la pestaña Desarrollar y selecciona Vinculación de cuentas.
3. Habilite el interruptor junto a Vinculación de cuentas.
4. En la sección Creación de cuentas, seleccione No, solo quiero permitir la creación de cuentas en mi sitio web.

5. En Linking type, seleccione OAuth y Implicit.

   

6. En Información del cliente:

   • Asigna un valor al ID de cliente emitido por tus acciones para Google a fin de identificar las solicitudes que provienen de Google.
   • Inserte las URL de sus extremos de autorización y de intercambio de tokens.

Nota: Si deseas que tu ID de cliente se envíe como una string codificada en base64, haz clic en la flecha desplegable junto a Configura tu cliente (opcional) y marca la casilla Google para transmitir el ID y secreto del cliente a través del encabezado de autenticación HTTP básico.

6. Haz clic en Guardar.

Implementa tu servidor de OAuth

Para admitir el flujo implícito de OAuth 2.0, tu servicio pone a disposición un extremo de autorización mediante HTTPS. Este extremo es responsable de la autenticación y la obtención del consentimiento de los usuarios para el acceso a los datos. 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.

Cuando tu acción necesita llamar a una de las APIs autorizadas de tu servicio, Google usa este extremo a fin de obtener permiso de los usuarios para llamar a estas APIs en su nombre.

Una sesión de flujo implícita típica de OAuth 2.0 que inicia Google tiene el siguiente flujo:

1. Google abre tu extremo de autorización en el navegador del usuario. El usuario accede si aún no lo ha hecho y le otorga permiso a Google para acceder a sus datos con tu API si aún no lo ha otorgado.
2. Tu servicio crea un token de acceso y lo muestra a Google mediante el redireccionamiento del navegador del usuario a Google con el token de acceso adjunto a la solicitud.
3. Google llama a las API de tu servicio y adjunta el token de acceso con cada solicitud. Tu servicio verifica que el token de acceso otorgue autorización a Google para acceder a la API y, luego, completa la llamada a la API.

Controla las solicitudes de autorización

Cuando tu acción necesita realizar una vinculación de cuentas a través de un flujo implícito 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 de extremo de autorización
client_id	Es el ID de cliente que asignaste a Google.
redirect_uri	La URL a la que envías la respuesta a esta solicitud.
state	Un valor de contabilidad que se devuelve a Google sin cambios en el URI de redireccionamiento.
response_type	El tipo de valor que se muestra en la respuesta. Para el flujo implícito de OAuth 2.0, el tipo de respuesta siempre es token.

Por ejemplo, si tu extremo de autorización está disponible en https://myservice.example.com/auth, la 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&response_type=token

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

1. Verifica los valores client_id y redirect_uri para evitar otorgar acceso a apps cliente no deseadas o mal configuradas:

   • Confirma que client_id coincida con el ID de cliente que le asignaste a Google.
   • 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.

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

3. Genera un token de acceso que Google usará para acceder a tu API. El token de acceso puede ser cualquier valor de string, pero debe representar de manera única al usuario y al cliente al que corresponde el token y no debe poder adivinarse.

4. Envía una respuesta HTTP que redireccione el navegador del usuario a la URL que especifica el parámetro redirect_uri. Incluye todos los siguientes parámetros en el fragmento de URL:

   • access_token: Es el token de acceso que acabas de generar.
   • token_type: Es la string bearer.
   • state: Es el valor de estado no modificado de la solicitud original. El siguiente es un ejemplo de la URL resultante:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

     .

El controlador de redireccionamiento de OAuth 2.0 de Google recibirá el token de acceso y confirmará que el valor state no haya cambiado. Una vez que Google haya obtenido un token de acceso para el servicio, adjuntará el token a las llamadas subsiguientes a la acción como parte de AppRequest.

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

Advertencia: No brindes a los usuarios un mensaje de vinculación de cuentas obligatorio al comienzo de la conversación con tu acción. En su lugar, otorga a los usuarios no autenticados un flujo de invitados para mostrar cómo funciona tu acción y, luego, solicita la vinculación de cuentas solo si es necesario para continuar. Si los usuarios abandonan la acción de manera constante debido a problemas de vinculación de cuentas, Google no la promocionará de forma activa, lo que podría disminuir el tráfico de usuarios de la acción.

Nota: Debes usar Actions Builder para crear una acción que implemente la vinculación de cuentas.

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

1. Abra su proyecto de Actions Builder en Actions Console.
2. Crea una escena nueva para iniciar la vinculación de cuentas en tu acción:
   1. Haz clic en Escenas.
   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 para agregar en Condiciones.
4. Agrega una condición que verifique si el usuario asociado con la conversación es un usuario verificado. Si falla la verificación, tu acción no podrá realizar la vinculación de cuentas durante la conversación y debería dar acceso a funcionalidades que no requieran la vinculación de cuentas.
   1. En el campo Enter new expression, en Condition, ingresa la siguiente lógica: user.verificationStatus != "VERIFIED"
   2. En Transition, selecciona una escena que no requiera la vinculación de cuentas o una escena que sea el punto de entrada a la funcionalidad solo para invitados.

1. Haz clic en el ícono para agregar en Condiciones.
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 Condition, 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 agregará a tu proyecto una nueva escena del sistema de vinculación de cuentas llamada <SceneName>_AccountLinking.

Cómo personalizar la escena de vinculación de cuentas

1. En Escenas, selecciona la escena del sistema de vinculación de cuentas.
2. Haz clic en Enviar mensaje y agrega una oración corta para describir al usuario por qué la acción debe acceder a su identidad (por ejemplo, "Para guardar tus preferencias").
3. Haz clic en Guardar.

1. En Condiciones, haga clic en Si el usuario completa la vinculación de la cuenta 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 necesaria y volver a la escena de origen.
3. Haz clic en Guardar.

1. En Condiciones, haga 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 una funcionalidad que no requiera la vinculación de cuentas.
3. Haz clic en Guardar.

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

Cómo controlar solicitudes de acceso a datos

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