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 también permite la creación de cuentas, lo que permite que el usuario cree una cuenta nueva en tu servicio con su Cuenta de Google.

Para realizar la vinculación de cuentas con OAuth y Acceder con Google, sigue estos pasos generales:

  1. Primero, pídele al usuario que dé 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. Para 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. Luego, puedes crear un usuario en función de la información del perfil que contiene el token de ID.
En esta figura, se muestran los pasos que debe seguir un usuario para vincular su Cuenta de Google con el flujo de vinculación optimizado. En la primera captura de pantalla, se muestra cómo un usuario puede seleccionar tu app para vincularla. En la segunda captura de pantalla, el usuario puede confirmar si tiene una cuenta existente en tu servicio. En la tercera captura de pantalla, el usuario puede seleccionar la Cuenta de Google que desea vincular. La cuarta captura de pantalla muestra la confirmación de la vinculación de la Cuenta de Google con tu app. La quinta captura de pantalla muestra una cuenta de usuario vinculada correctamente en la app de Google.
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 + 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.

Usuario App o servidor de Google Tu extremo de intercambio de tokens Tu API 1. El usuario inicia la vinculación 2. Solicita Acceder con Google 3. Acceder con Google 4. check intent (aserciones JWT) 5. account_found: true/false Si se encuentra la cuenta: 6. get intent Si no hay cuenta: 6. create intent 7. access_token, refresh_token 8. Almacena tokens de usuario 9. Accede a los recursos del usuario
Figura 2. La secuencia de eventos en el Streamlined Linking flow.

Funciones y responsabilidades

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

Actor o componente Función de GAL Responsabilidades
App o servidor de Google Cliente de OAuth Obtiene el consentimiento del usuario para Acceder 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 existen cuentas, controla los intents de vinculación de cuentas (check, get, create) y emite tokens en función de los intents solicitados.
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

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 con 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? (check intent se llama para confirmar)
        1. SÍ : Se llama a get intent y la cuenta se vincula si get intent se muestra correctamente.
        2. NO: ¿Crear una cuenta nueva? (El usuario decide seleccionando SÍ o NO).
          1. SÍ : Se llama a create intent y la cuenta se vincula si create intent se muestra 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? (check intent se llama para confirmar)
      1. SÍ : Se llama a get intent y la cuenta se vincula si get intent se muestra correctamente.
      2. NO : create intent se llama y la cuenta se vincula si create intent se muestra correctamente.

Receta de implementación

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

Sigue estos pasos para controlar los diferentes intents:

Verifica si existe una cuenta de usuario (intent 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 de los parámetros, consulta Intents de vinculación optimizada.

Receta de implementación

Para controlar el intent check, 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 de Validación de JWT.

  2. Busca al usuario:

    • Verifica si el ID de 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: Muestra el HTTP 200 OK con {"account_found": "true"}.
    • Si no se encuentra: Muestra el HTTP 404 Not Found con {"account_found": "false"}.

Cómo controlar la vinculación automática (obtener intent)

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

Receta de implementación

Para controlar el intent get, realiza las siguientes acciones:

  1. Validar la solicitud:

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

  2. Buscar usuario:

    • Verifica que el usuario exista con la declaración sub o email.

  3. Responder:

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

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

Si no existe ninguna cuenta, Google llamará a tu endpoint con intent=create para crear un usuario nuevo. Para obtener detalles sobre los parámetros, consulta Intenciones de vinculación optimizadas.

Receta de implementación

Para controlar el intent create, 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 resguardo a la vinculación de 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 vinculación de cuentas. Para obtener tu ID de cliente de la 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 o desarrollo locales, debes agregar http://localhost y http://localhost:<port_number> al campo Orígenes autorizados de JavaScript.

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.