Vinculación de Cuentas de Google con OAuth

Las cuentas se vinculan con los flujos implícitos y de código de autorización estándar de la industria de 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.

En el flujo implícito, Google abre tu extremo de autorización en el navegador del usuario. Después de acceder correctamente, le devuelves a Google un token de acceso de larga duración. Este token de acceso ahora se incluye en cada solicitud que se envía desde Google.

En el flujo de código de autorización, necesitas dos extremos:

  • El extremo de autorización, que presenta la IU de acceso a los usuarios que aún no accedieron. El extremo de autorización también crea un código de autorización de corta duración para registrar el consentimiento de los usuarios para el acceso solicitado.

  • El extremo de intercambio de tokens, que es responsable de dos tipos de intercambios:

    1. Intercambia un código de autorización por un token de actualización de larga duración y un token de acceso de corta duración. Este intercambio se produce cuando el usuario pasa por el flujo de vinculación de cuentas.
    2. Intercambia un token de actualización de larga duración por un token de acceso de corta duración. Este intercambio se produce cuando Google necesita un token de acceso nuevo porque el que tenía venció.

Elige un flujo de OAuth 2.0

Si bien el flujo implícito es más fácil de implementar, Google recomienda que los tokens de acceso emitidos por el flujo implícito nunca venzan. Esto se debe a que el usuario se ve obligado a volver a vincular su cuenta después de que vence un token con el flujo implícito. Si necesitas que el token venza por motivos de seguridad, te recomendamos que uses el flujo de código de autorización.

Lineamientos de diseño

En esta sección, se describen los requisitos y las recomendaciones de diseño para la pantalla del usuario que alojas para los flujos de vinculación de OAuth. Después de que la app de Google la llama, tu plataforma muestra una página de acceso a Google y una pantalla de consentimiento de vinculación de cuentas al usuario. El usuario vuelve a la app de Google después de dar su consentimiento para vincular cuentas.

En esta figura, se muestran los pasos que debe seguir un usuario para vincular su Cuenta de Google a tu sistema de autenticación. En la primera captura de pantalla, se muestra la vinculación iniciada por el usuario desde tu plataforma. La segunda imagen muestra el acceso del usuario a Google, mientras que la tercera muestra el consentimiento y la confirmación del usuario para vincular su Cuenta de Google con tu app. La captura de pantalla final muestra una cuenta de usuario vinculada correctamente en la app de Google.
Figura 1. Acceso de usuarios a Google y pantallas de consentimiento de vinculación de cuentas

Requisitos

  1. Debes comunicar que la cuenta del usuario se vinculará a Google, no a un producto específico de Google, como Google Home o el Asistente de Google.

Recomendaciones

Te recomendamos que hagas lo siguiente:

  1. Muestra la Política de Privacidad de Google. Incluye un vínculo a la Política de Privacidad de Google en la pantalla de consentimiento.

  2. Datos que se compartirán. Usa un lenguaje claro y conciso para informarle al usuario qué datos de él requiere Google y por qué.

  3. Llamado a la acción claro. Indica un llamado a la acción claro en la pantalla de consentimiento, como "Aceptar y vincular". Esto se debe a que los usuarios deben comprender qué datos deben compartir con Google para vincular sus cuentas.

  4. Capacidad de cancelar. Proporciona una forma para que los usuarios vuelvan atrás o cancelen si deciden no vincular.

  5. Proceso de acceso claro. Asegúrate de que los usuarios tengan un método claro para acceder a su Cuenta de Google, como campos para su nombre de usuario y contraseña, o Acceder con Google.

  6. Capacidad de desvincular. Ofrece un mecanismo para que los usuarios desvinculen, como una URL a la configuración de su cuenta en tu plataforma. Como alternativa, puedes incluir un vínculo a Cuenta de Google en la que los usuarios pueden administrar su cuenta vinculada.

  7. Capacidad de cambiar la cuenta de usuario. Sugiere un método para que los usuarios cambien sus cuentas. Esto es especialmente beneficioso si los usuarios suelen tener varias cuentas.

    • Si un usuario debe cerrar la pantalla de consentimiento para cambiar de cuenta, envía un error recuperable a Google para que el usuario pueda acceder a la cuenta seleccionada con la vinculación de OAuth y el flujo implícito.

  8. Incluye tu logotipo. Muestra el logotipo de tu empresa en la pantalla de consentimiento. Usa tus lineamientos de estilo para colocar tu logotipo. Si quieres o necesitas mostrar también el logotipo de Google, consulta Logotipos y marcas comerciales.

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.

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

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 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.