Vinculación optimizada con OAuth y Acceder con Google

Descripción general

La vinculación optimizada de Acceder con Google basada en OAuth agrega Acceder con Google sobre la vinculación de OAuth. Esto proporciona una experiencia de vinculación fluida para los usuarios de Google y, de manera opcional, habilita la creación de cuentas, lo que permite que el usuario cree una cuenta nueva en tu servicio con su Cuenta de Google.

Para vincular cuentas con OAuth y Acceder con Google, sigue estos pasos generales:

1. Primero, pídele al usuario que otorgue su consentimiento para acceder a su perfil de Google.
2. Usa la información de su perfil para verificar si existe la cuenta de usuario.
3. En el caso de los usuarios existentes, vincula las cuentas.
4. Si no encuentras una coincidencia para el usuario de Google en tu sistema de autenticación, valida el token de ID que recibiste de Google. Si tu servicio admite la creación de cuentas, puedes crear un usuario basado en la información del perfil que se incluye en el token de ID.

Vinculación de cuentas en el teléfono de un usuario con la vinculación optimizada

Figura 1. Vinculación de cuentas en el teléfono de un usuario con la vinculación optimizada

Vinculación optimizada: Flujo de OAuth y Acceder con Google

En el siguiente diagrama de secuencia, se detallan las interacciones entre el usuario, Google y tu extremo de intercambio de tokens para la vinculación optimizada.

Figura 2: Secuencia de eventos en el flujo de vinculación optimizada

Funciones y responsabilidades

En la siguiente tabla, se definen los roles y las responsabilidades de los participantes en el flujo de vinculación optimizada.

Actor / componente	Rol de GAL	Responsabilidades
App o servidor de Google	Cliente de OAuth	Obtiene el consentimiento del usuario para el Acceso con Google, pasa las aserciones de identidad (JWT) a tu servidor y almacena de forma segura los tokens resultantes.
Tu extremo de intercambio de tokens	Proveedor de identidad o servidor de autorización	Valida las aserciones de identidad, verifica si hay cuentas existentes, controla las intenciones de vinculación de cuentas requeridas (check, get) y la intención opcional create, y emite tokens según las intenciones solicitadas.
Tu API de servicio	Servidor de recursos	Proporciona acceso a los datos del usuario cuando se presenta un token de acceso válido.

Requisitos para la vinculación optimizada

• Implementa el flujo de vinculación básica de OAuth. Tu servicio debe admitir extremos de autorización y de intercambio de tokens que cumplan con OAuth 2.0.
• Tu extremo de intercambio de tokens debe admitir aserciones de tokens web JSON (JWT) y, además, implementar las intenciones check y get obligatorias, y, de manera opcional, la intención create.

Nota: Estas intents se deben implementar en el mismo extremo de intercambio de tokens que creaste para el flujo de vinculación básica con OAuth. No crees un extremo diferente para controlar estos intents.

• Registra tu ID de cliente de la API de Google.

Lógica de decisión para la vinculación optimizada

La siguiente lógica determina cómo se llaman los intents durante el flujo de vinculación optimizada:

1. ¿El usuario tiene una cuenta en tu sistema de autenticación? (El usuario decide seleccionando SÍ o NO)
   1. SÍ: ¿El usuario usa el correo electrónico asociado a su Cuenta de Google para acceder a tu plataforma? (El usuario decide seleccionando SÍ o NO)
      1. SÍ: ¿El usuario tiene una cuenta coincidente en tu sistema de autenticación? (Se llama a la intención check para confirmar).
         1. SÍ : Se llama a la intención get y se vincula la cuenta si la intención de obtención se devuelve correctamente.
         2. NO: ¿Crear una cuenta nueva? (El usuario decide seleccionando SÍ o NO; solo se aplica si tu servicio admite la creación de cuentas)
            1. SÍ : Se llama al intent create y se vincula la cuenta si el intent de creación se devuelve correctamente.
            2. NO : Se activa el flujo de vinculación de OAuth, se dirige al usuario a su navegador y se le da la opción de vincularse con un correo electrónico diferente.
      2. NO : Se activa el flujo de vinculación de OAuth, se dirige al usuario a su navegador y se le da la opción de vincularse con un correo electrónico diferente.
   2. NO: ¿El usuario tiene una cuenta coincidente en tu sistema de autenticación? (Se llama a la intención check para confirmar).
      1. SÍ : Se llama a la intención get y se vincula la cuenta si getIntent devuelve un resultado exitoso.
      2. NO : Si tu servicio admite la creación de cuentas, se llama al intent create y se vincula la cuenta si el intent de creación se devuelve correctamente. Si no se admite la creación de cuentas, tu extremo debe devolver el error HTTP 401 linking_error para activar el flujo de vinculación de OAuth de resguardo.

Receta de implementación

Tu extremo de intercambio de tokens debe implementar los intents check y get obligatorios, y, de manera opcional, el intent create para admitir la vinculación optimizada.

Sigue estos pasos para controlar las diferentes intenciones:

Verificar si existe una cuenta de usuario (intención de verificación)

Google llama a tu extremo de intercambio de tokens para verificar si el usuario de Google existe en tu sistema. Para obtener detalles sobre los parámetros, consulta Intenciones de vinculación optimizada.

Receta de implementación

Para controlar el intent check requerido, realiza las siguientes acciones:

1. Valida la solicitud:

   • Verifica client_id, client_secret y grant_type (debe ser urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Valida el assertion (JWT) con los criterios que se indican en Validación de JWT.

2. Buscar usuario:

   • Verifica si el ID de la Cuenta de Google (sub) o la dirección de correo electrónico en el JWT coinciden con un usuario de tu base de datos.

3. Responder:

   • Si se encuentra, devuelve HTTP 200 OK con {"account_found": "true"}.
   • Si no se encuentra, devuelve el error HTTP 404 Not Found con {"account_found": "false"}.

Controla la vinculación automática (obtén la intención)

Si la cuenta existe, Google llamará a tu extremo con intent=get para recuperar los tokens. Para obtener detalles sobre los parámetros, consulta Intenciones de vinculación optimizada.

Receta de implementación

Para controlar el intent get requerido, realiza las siguientes acciones:

1. Valida la solicitud:

   • Verifica client_id, client_secret y grant_type.
   • Valida el objeto assertion (JWT).

2. Buscar usuario:

   • Verifica que el usuario exista con el reclamo sub o email.

3. Responder:

   • Si la operación se realiza correctamente, genera y devuelve access_token, refresh_token y expires_in en una respuesta JSON (HTTP 200 OK).
   • Si falla la vinculación, devuelve el código HTTP 401 Unauthorized con {"error": "linking_error"} y un login_hint opcional para recurrir a la vinculación estándar de OAuth.

Controla la creación de cuentas con Acceder con Google (intención de creación)

Nota: Admitir la intención create es opcional. Los intents requeridos para la vinculación optimizada son check y get.

Si tu servicio admite la creación de cuentas y no existe ninguna, Google llama a tu extremo con intent=create para crear un usuario nuevo. Para obtener detalles sobre los parámetros, consulta Intenciones de Vinculación Simplificada.

Receta de implementación

Para controlar el intent create opcional, realiza las siguientes acciones:

1. Valida la solicitud:

   • Verifica client_id, client_secret y grant_type.
   • Valida el objeto assertion (JWT).

2. Verifica que el usuario no exista:

   • Comprueba si el sub o el email ya están en tu base de datos.
   • Si el usuario existe, devuelve HTTP 401 Unauthorized con {"error": "linking_error", "login_hint": "USER_EMAIL"} para forzar la vinculación de resguardo a OAuth.

3. Crear cuenta:

   • Usa las reclamaciones sub, email, name y picture del JWT para crear un nuevo registro de usuario.

4. Responder:

   • Genera y devuelve tokens en una respuesta JSON (HTTP 200 OK).

Obtén tu ID de cliente de la API de Google

Deberás proporcionar tu ID de cliente de la API de Google durante el proceso de registro de la vinculación de la cuenta. Obtener tu ID de cliente de API con el proyecto que creaste mientras completabas los pasos de vinculación de OAuth Para ello, completa los siguientes pasos:

1. Ve a la página Clientes.

2. Crea o selecciona un proyecto de las APIs de Google.

   Si tu proyecto no tiene un ID de cliente para el tipo de aplicación web, haz clic en Crear cliente para crear uno. Asegúrate de incluir el dominio de tu sitio en el cuadro Orígenes autorizados de JavaScript. Cuando realices pruebas locales o desarrollo, debes agregar http://localhost y http://localhost:<port_number> al campo Orígenes de JavaScript autorizados.

   Punto clave: Agrega http://localhost y http://localhost:<port_number> al campo Orígenes JavaScript autorizados para las pruebas locales o el desarrollo.

   Nota: Un ID de cliente se parece al siguiente ejemplo:

   1234567890-abc123def456.apps.googleusercontent.com
   

Valida la implementación

Puedes validar tu implementación con la herramienta OAuth 2.0 Playground.

En la herramienta, sigue estos pasos:

1. Haz clic en Configuración para abrir la ventana Configuración de OAuth 2.0.
2. En el campo Flujo de OAuth, selecciona Del cliente.
3. En el campo Extremos de OAuth, selecciona Personalizado.
4. Especifica tu extremo de OAuth 2.0 y el ID de cliente que le asignaste a Google en los campos correspondientes.
5. En la sección Paso 1, no selecciones ningún alcance de Google. En su lugar, deja este campo en blanco o escribe un alcance válido para tu servidor (o una cadena arbitraria si no usas alcances de OAuth). Cuando termines, haz clic en Autorizar APIs.
6. En las secciones Paso 2 y Paso 3, sigue el flujo de OAuth 2.0 y verifica que cada paso funcione según lo previsto.

Puedes validar tu implementación con la herramienta de demostración de vinculación de Cuentas de Google.

En la herramienta, sigue estos pasos:

1. Haz clic en el botón Acceder con Google.
2. Elige la cuenta que quieras vincular.
3. Ingresa el ID de servicio.
4. De manera opcional, ingresa uno o más alcances para los que solicitarás acceso.
5. Haz clic en Iniciar demostración.
6. Cuando se te solicite, confirma que puedes dar tu consentimiento y rechazar la solicitud de vinculación.
7. Confirma que se te redirecciona a tu plataforma.