Vinculación de Cuentas de Google con OAuth

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

OAuth 2.1 y PKCE para agentes

Para los agentes de IA sin estado y las canalizaciones multimodales, se recomienda aplicar OAuth 2.1.

  • PKCE (Proof Key for Code Exchange): Se debe usar para proteger el flujo del código de autorización y evitar ataques de interceptación.
  • No hay 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 que cumplan con OAuth 2.0/2.1.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

    Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

    Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

    Support email: For users to contact you with questions about their consent.

    Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

    Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

    Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

    Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

    Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

    Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

  4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

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 extremo es el de autorización, que es responsable de encontrar o obtener el consentimiento de los usuarios para el acceso 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.

Usuario Aplicación o / navegador de Google Servidor de Google Tu extremo de autenticación Tu extremo de token 1. El usuario inicia la vinculación 2. Redireccionamiento al extremo de autenticación (GET) client_id, redirect_uri, state, scope 3. Mostrar la pantalla de acceso y consentimiento 4. El usuario se autentica y otorga el consentimiento 5. Redireccionamiento a Google (GET) code, state 6. Administrar el redireccionamiento y pasar el código o el estado 7. Intercambio de tokens (POST) grant_type=authorization_code, code 8. Mostrar tokens (200 OK) access_token, refresh_token 9. Almacenar tokens de usuario 10. Acceder a los recursos del usuario
Figura 1. Secuencia de eventos en el flujo de código de autorización de OAuth 2.0 para la vinculación de la Cuenta de Google.

Funciones y responsabilidades

En la siguiente tabla, se definen las funciones y 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 de servicios.

Actor o componente Función de GAL Responsabilidades
Aplicación o servidor de Google Cliente de OAuth Inicia el flujo, recibe el código de autorización, lo intercambia por tokens y los almacena de forma segura para acceder a las APIs de tu servicio.
Tu extremo de autorización Servidor de autorización Autentica a tus usuarios y obtiene su consentimiento para compartir el acceso a sus datos con Google.
Tu extremo de intercambio de tokens Servidor de autorización Valida los códigos de autorización y los tokens de actualización, y emite tokens de acceso tokens al servidor de Google.
URI de redireccionamiento de Google Extremo de devolución de llamada Recibe el redireccionamiento del usuario desde tu servicio de autorización con los code y state valores.

Una sesión de 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 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 lo muestra 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 muestra 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 tokens de acceso nuevos cuando vencen.
  5. Una vez que el usuario completa el flujo de vinculación de cuentas, cada solicitud posterior que se envía desde 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: Administra 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 administrar la solicitud, realiza las siguientes acciones:

  1. Valida la solicitud:

    • Confirma que el client_id coincida con el ID de cliente asignado a Google.
    • Confirma que el redirect_uri coincida con la URL de redireccionamiento de Google esperada: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_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 no adivinable asociado con el usuario y el cliente.
    • Configura el código para que venza en aproximadamente 10 minutos.

  4. Redirecciona a Google:

    • Redirecciona 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: Administra las solicitudes de intercambio de tokens

Tu extremo de intercambio de tokens procesa dos tipos de solicitudes: el intercambio de códigos por tokens y la 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 extremo 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 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 usado en el paso 1.
    • Si falla la validación, muestra un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

  2. Emite tokens:

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

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 falla la validación, muestra un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

  2. Emite un token de acceso nuevo:

    • Genera un access_token nuevo de corta duración.
    • Muestra un error HTTP 200 OK con la respuesta de 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:

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.

Encabezados de la solicitud del extremo userinfo
Authorization header El token de acceso del tipo portador.

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