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.

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.

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

• Implementa el flujo básico de vinculación de OAuth. Tu servicio debe admitir extremos de autorización y de intercambio de tokens compatibles con OAuth 2.0.
• Tu extremo de intercambio de tokens debe admitir aserciones de JSON Web Token (JWT) y debe implementar los intents check, create, y get.

• 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 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:

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"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 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 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

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.