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.

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.

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.

• 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"}.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

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

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.

Valida la implementación

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.