Vinculación de Cuentas de Google con OAuth

Las cuentas se vinculan con el flujo de código de autorización estándar de la industria OAuth 2.0.

OAuth 2.1 y PKCE para agentes

Para los agentes de IA sin estado y las canalizaciones multimodales, se recomienda la aplicación de OAuth 2.1.

• PKCE (Clave de prueba para el intercambio de código): Se debe usar para proteger el flujo de código de autorización y evitar ataques de intercepción.
• Sin flujo implícito: El flujo implícito expone tokens de acceso en la URL, lo que representa un riesgo de seguridad para los entornos de agentes.

Tu servicio debe admitir extremos de autorización y de intercambio de tokens compatibles con OAuth 2.0/2.1.

Crea el proyecto

Para crear tu proyecto y usar la vinculación de cuentas, haz lo siguiente:

1. Ve a la Consola de API de Google.
2. Haz clic en Crear proyecto.
3. Ingresa un nombre o acepta la sugerencia generada.
4. Confirma o edita los campos restantes.
5. Haz clic en Crear.

Para ver el ID del proyecto, haz lo siguiente:

1. Ve a la Consola de API de Google.
2. Busca tu proyecto en la tabla de la página de destino. El ID del proyecto aparece en la ID columna.

Configura la pantalla de consentimiento de OAuth

El proceso de vinculación de Cuentas de Google incluye una pantalla de consentimiento que les indica a los usuarios la aplicación que solicita acceso a sus datos, qué tipo de datos solicita y las condiciones que se aplican. Deberás configurar la pantalla de consentimiento de OAuth antes de generar un ID de cliente de la API de Google.

1. Abre la página de la pantalla de consentimiento de OAuth de la consola de APIs de Google.
2. Si se te solicita, selecciona el proyecto que acabas de crear.

3. En la página "Pantalla de consentimiento de OAuth", completa el formulario y haz clic en el botón "Guardar".

   Nombre de la aplicación: Es el nombre de la aplicación que solicita el consentimiento. El nombre debe reflejar con precisión tu aplicación y ser coherente con el nombre de la aplicación que los usuarios ven en otros lugares. El nombre de la aplicación se mostrará en la pantalla de consentimiento de vinculación de cuentas.

   Logotipo de la aplicación: Es una imagen en la pantalla de consentimiento que ayudará a los usuarios a reconocer tu app. El logotipo se muestra en la pantalla de consentimiento de vinculación de cuentas y en la configuración de la cuenta.

   Correo electrónico de asistencia: Es para que los usuarios se comuniquen contigo si tienen preguntas sobre su consentimiento.

   Permisos para las APIs de Google: Los permisos permiten que tu aplicación acceda a los datos privados de Google de tu usuario. Para el caso de uso de vinculación de Cuentas de Google, el permiso predeterminado (correo electrónico, perfil, openid) es suficiente, no es necesario agregar permisos sensibles. Por lo general, se recomienda solicitar permisos de forma incremental, en el momento en que se requiere el acceso, en lugar de hacerlo por adelantado. Obtén más información.

   Dominios autorizados: Para protegerlos a ti y a tus usuarios, Google solo permite que las aplicaciones que se autentican con OAuth usen dominios autorizados. Los vínculos de tus aplicaciones deben alojarse en dominios autorizados. Obtén más información.

   Vínculo a la página principal de la aplicación: Es la página principal de tu aplicación. Debe alojarse en un dominio autorizado.

   Vínculo a la Política de Privacidad de la aplicación: Se muestra en la pantalla de consentimiento de vinculación de Cuentas de Google. Debe alojarse en un dominio autorizado.

   Vínculo a las Condiciones del Servicio de la aplicación (opcional): Debe alojarse en un dominio autorizado.

   

   Figura 1. Pantalla de consentimiento de vinculación de Cuentas de Google para una aplicación ficticia, Tunery

4. Verifica el "Estado de verificación". Si tu aplicación necesita verificación, haz clic en el botón "Enviar para verificación" para enviarla. Consulta los requisitos de verificación de OAuth para obtener más detalles.

Implementa tu servidor de OAuth

Una implementación del servidor OAuth 2.0 del flujo de código de autorización consta de dos extremos que tu servicio pone a disposición a través de HTTPS. El primer endpoint es el de autorización, que se encarga de encontrar u obtener el consentimiento de los usuarios para acceder 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. El segundo extremo es el de intercambio de tokens, que se usa para obtener cadenas encriptadas, llamadas tokens, que autorizan a un usuario a acceder a tu servicio.

Cuando una aplicación de Google necesita llamar a una de las APIs de tu servicio, Google usa estos extremos en conjunto para obtener permiso de tus usuarios para llamar a estas APIs en su nombre.

Vinculación de la Cuenta de Google: Flujo de código de autorización de OAuth

En el siguiente diagrama de secuencia, se detallan las interacciones entre el usuario, Google y los extremos de tu servicio.

Funciones y responsabilidades

En la siguiente tabla, se definen los roles y las responsabilidades de los actores en el flujo de OAuth de la vinculación de la Cuenta de Google (GAL). Ten en cuenta que, en GAL, Google actúa como el cliente de OAuth, mientras que tu servicio actúa como el proveedor de identidad o servicio.

Una sesión del flujo de código de autorización de OAuth 2.0 iniciada por Google tiene el siguiente flujo:

1. Google abre tu extremo de autorización en el navegador del usuario. Si el flujo se inició en un dispositivo solo de voz para una acción, Google transfiere la ejecución a un teléfono.
2. El usuario accede, si aún no lo hizo, y le otorga permiso a Google para acceder a sus datos con tu API, si aún no lo hizo.
3. Tu servicio crea un código de autorización y se lo devuelve a Google. Para ello, redirecciona el navegador del usuario a Google con el código de autorización adjunto a la solicitud.
4. Google envía el código de autorización a tu extremo de intercambio de tokens, que verifica la autenticidad del código y devuelve un token de acceso y un token de actualización. El token de acceso es un token de corta duración que tu servicio acepta como credenciales para acceder a las APIs. El token de actualización es un token de larga duración que Google puede almacenar y usar para adquirir nuevos tokens de acceso cuando estos vencen.
5. Una vez que el usuario completa el flujo de vinculación de cuentas, cada solicitud posterior que envía Google contiene un token de acceso.

Receta de implementación

Sigue estos pasos para implementar el flujo de código de autorización.

Paso 1: Controla las solicitudes de autorización

Cuando Google inicia la vinculación de cuentas, redirecciona al usuario a tu extremo de autorización. Para obtener información detallada sobre los contratos de protocolo y los requisitos de parámetros, consulta el extremo de autorización.

Para controlar la solicitud, realiza las siguientes acciones:

1. Valida la solicitud:

   • Confirma que client_id coincida con el ID de cliente asignado a Google.
   • Confirma que redirect_uri coincida con la URL de redireccionamiento de Google esperada:
     • Prod: https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID
     • Zona de pruebas: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_ID
   • Verifica que response_type sea code.

2. Autentica al usuario:

   • Verifica si el usuario accedió a tu servicio.
   • Si el usuario no accedió, pídele que complete tu flujo de acceso o registro.

3. Genera un código de autorización:

   • Crea un código de autorización único y difícil de adivinar asociado con el usuario y el cliente.
   • Establece que el código venza en aproximadamente 10 minutos.

4. Redirige a Google:

   • Redirige el navegador a la URL proporcionada en redirect_uri.
   • Agrega los siguientes parámetros de consulta:
     • code: Es el código de autorización que generaste.
     • state: Es el valor de estado sin modificar que se recibió de Google.

Paso 2: Controla las solicitudes de intercambio de tokens

Tu extremo de intercambio de tokens procesa dos tipos de solicitudes: intercambio de códigos por tokens y actualización de tokens de acceso vencidos. Para obtener información detallada sobre los contratos de protocolo y los requisitos de parámetros, consulta el endpoint de intercambio de tokens.

A. Intercambia códigos de autorización por tokens

Cuando Google recibe el código de autorización, llama a tu extremo de intercambio de tokens (POST) para recuperar los tokens.

1. Valida la solicitud:

   • Verifica client_id y client_secret.
   • Verifica que el código de autorización sea válido y no haya vencido.
   • Confirma que redirect_uri coincida con el valor que se usó en el paso 1.
   • Si la validación falla, devuelve un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

2. Tokens de emisión:

   • Genera un refresh_token de larga duración y un access_token de corta duración (por lo general, 1 hora).
   • Devuelve un 200 OK de HTTP con la respuesta estándar del token JSON.

B. Actualiza los tokens de acceso

Cuando vence el token de acceso, Google solicita uno nuevo con el token de actualización.

1. Valida la solicitud:

   • Verifica client_id, client_secret y refresh_token.
   • Si la validación falla, devuelve un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

2. Emitir un token de acceso nuevo:

   • Genera un nuevo access_token de corta duración.
   • Devuelve un 200 OK de HTTP con la respuesta del token JSON (opcionalmente, incluye un token de actualización nuevo).

Controla las solicitudes userinfo

El extremo userinfo es un recurso protegido de OAuth 2.0 que muestra reclamos sobre el usuario vinculado. La implementación y el alojamiento del extremo userinfo son opcionales, excepto en los siguientes casos de uso:

• Acceso a la cuenta vinculada con Google One Tap.
• Suscripción sin inconvenientes en Android TV.

Una vez que el token de acceso se recupera correctamente del extremo del token, Google envía una solicitud al extremo userinfo para recuperar la información básica de perfil del usuario vinculado.

Por ejemplo, si el extremo userinfo está disponible en https://myservice.example.com/userinfo, una solicitud podría verse de la siguiente manera:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Para que tu extremo userinfo controle las solicitudes, sigue estos pasos:

1. Extrae el token de acceso del encabezado de autorización y muestra la información del usuario asociada con el token de acceso.
2. Si el token de acceso no es válido, muestra un error HTTP 401 No autorizado con el encabezado de respuesta WWW-Authenticate. A continuación, se muestra un ejemplo de una respuesta de error de userinfo:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   Si se muestra una respuesta de error 401 No autorizado o cualquier otra respuesta de error no exitosa durante el proceso de vinculación, el error no se podrá recuperar, el token recuperado se descartará y el usuario deberá volver a iniciar el proceso de vinculación.

3. Si el token de acceso es válido, devuelve una respuesta HTTP 200 con el siguiente objeto JSON en el cuerpo del protocolo HTTPS respuesta:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   Si el extremo userinfo muestra una respuesta exitosa HTTP 200, el token y las reclamaciones recuperados se registran con la Cuenta de Google del usuario.

   respuesta del extremo userinfo
   sub	Un ID único que identifica al usuario en tu sistema.
   email	Dirección de correo electrónico del usuario.
   given_name	Opcional: Es el nombre del usuario.
   family_name	Opcional: Apellido del usuario.
   name	Opcional: Es el nombre completo del usuario.
   picture	Opcional: Foto de perfil del usuario.

Cómo validar 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 settings 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.