Guía de implementación de OAuth 2.1

En esta guía, se describe cómo autorizar de forma segura la plataforma de apps conectadas para acceder a tus servicios. En el caso de las integraciones de MCP de apps conectadas, recomendamos usar OAuth 2.1, el estándar de la industria para la autorización delegada, con la clave de prueba para el intercambio de código (PKCE) para garantizar la máxima seguridad de los datos de los usuarios y la confiabilidad en los flujos "agénticos". La plataforma de apps conectadas admite el tipo de permiso de código de autorización con parámetros de clave de prueba para el intercambio de código (PKCE).

PKCE es obligatorio para todo OAuth 2.1 y opcional para OAuth 2.0.

Para habilitar el descubrimiento automático y optimizar el proceso de incorporación, tu servidor de autorización debe admitir la extensión de metadatos del servidor de autorización, también conocida como descubrimiento de OAuth.

Sugerencia: Para evitar una experiencia del usuario frustrante y la necesidad de volver a vincular las cuentas, el detalle más importante es administrar la duración del token de actualización con la vinculación persistente.

Cómo Gemini MCP recupera el JSON de configuración

La consola de MCP de Gemini intenta recuperar tu JSON de configuración de las siguientes URLs, en el orden que se muestra en esta sección.

Precaución: La consola de MCP de Gemini usa la primera URL que devuelve una respuesta, incluido un error. Asegúrate de que se pueda acceder al extremo que prefieras y de que devuelva el código HTTP 200.

Si la URL de tu servidor de autorización se encuentra en el nivel superior de tu dominio (por ejemplo, https://auth.example.com), Gemini agrega directorios estándar "conocidos" a tu dominio y busca el servidor en el siguiente orden:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

Si la URL de tu servidor de autorización se encuentra dentro de un subdirectorio o una ruta de acceso específicos en tu dominio, por ejemplo, https://auth.example.com/realms/master, Gemini agrega las mismas rutas de acceso "conocidas" directamente a ese subdirectorio, en el siguiente orden.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (compatibilidad con rutas de acceso anidadas)

Funciones de JSON requeridas

Tu respuesta de metadatos debe incluir los siguientes campos. La integración falla si faltan campos obligatorios o no se encuentran tipos válidos.

authorization_endpoint

Debe ser una URL de cadena válida.

token_endpoint

Debe ser una URL de cadena válida.

response_types_supported

Debe contener la cadena code.

registration_endpoint

Por el momento, Play Console se basa en el cliente dinámico.

Registro (RFC 7591). Debes proporcionar un extremo de registro en tus metadatos o ingresar el ID de cliente o el secreto directamente en la IU de Play Console.

Si tu servidor de autorización no admite el registro dinámico de clientes (DCR), debes implementar y completar de forma manual los campos ID de cliente y Secreto del cliente en la IU de Play Console para completar la integración.

Si tu implementación admite la clave de prueba para el intercambio de código (PKCE) o las sesiones persistentes, debes incluir los campos de capacidad pertinentes (como Challenge Methods y Tipos de permiso) en tu JSON de descubrimiento. Esto ayuda a garantizar la compatibilidad con los estándares de seguridad y conectividad de Gemini. Si admites el alcance, debes incluir el campo scopes_supported.

Configuración de ejemplo

La siguiente es una respuesta JSON válida que cumple con los requisitos de nuestro cliente.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

En los casos en los que incluyas PKCE, el siguiente fragmento muestra un ejemplo de lo que se podría incluir en el bloque JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

En los casos en los que incluyas el campo scopes_supported, el siguiente fragmento muestra un ejemplo de lo que se podría incluir en el bloque JSON.

"scopes_supported": ["mcp", "cart.order"],

Flujo de código de autorización (versión simplificada)

En los siguientes pasos, se describe el flujo de código de autorización estándar. Esta secuencia ilustra exactamente cómo la plataforma de apps conectadas obtiene de forma segura los tokens de acceso necesarios de tu servidor para actuar en nombre de un usuario.

1. Solicitud de autorización: La plataforma de Google determina que necesita llamar a tu función, pero el usuario aún no tiene autorización. El chatbot inicia el flujo redireccionando el navegador del usuario (o mostrando un vínculo) a tu extremo de autorización.

   Esta solicitud incluye tu ID de cliente (o se genera automáticamente con DCR), el URI de redireccionamiento de Gemini y los parámetros críticos de PKCE (code_challenge y code_challenge_method).

   Agrega las siguientes URLs a la lista de entidades permitidas para la configuración de OAuth:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. Consentimiento del usuario: Tu servidor de autorización valida la solicitud, autentica al usuario (acceso) y le pide que otorgue permiso para que la plataforma de Google acceda a sus datos o servicio.

3. Otorgamiento de código: Después de que el usuario da su consentimiento, tu servidor redirecciona el navegador del usuario a la RedirectURI de Gemini y agrega un código de autorización temporal a la URL.

4. Intercambio de tokens: El backend detrás de Gemini envía una solicitud POST a tu extremo de token, lo que intercambia el código de autorización por un token de acceso.

   Nota: Esta solicitud debe incluir el parámetro PKCE (code_verifier) para demostrar que es el mismo cliente que inició el flujo.

5. Acceso otorgado: Tu extremo de token verifica el código y los parámetros de PKCE, emite un token de acceso y, de forma opcional, un token de actualización, y los devuelve a Gemini.

   Sugerencia: Aunque los tokens de actualización son opcionales, te recomendamos que configures tu servidor de autorización para que los emita. Los tokens de actualización permiten que la plataforma de apps conectadas mantenga el acceso sin tener que volver a autenticar al usuario.

Requisitos clave de PKCE

La PKCE agrega una capa de seguridad para evitar la intercepción no autorizada de códigos de autorización.

Precaución: Cumplir con estos requisitos de PKCE es fundamental para administrar correctamente los tokens de acceso y actualización, lo que ayuda a proteger los datos de los usuarios y mantener la integridad del ecosistema.

• code_verifier: Es una cadena criptográficamente aleatoria que genera Gemini al comienzo del flujo. Esta información es privada.
• code_challenge: Es una transformación de code_verifier, por lo general, el hash SHA256. Esto se envía de forma pública, como se describe en el paso 1 del flujo de código de autorización.
• Validación: Tu extremo de token (descrito en el paso 4 del flujo de código de autorización) debe validar que el code_verifier recibido, cuando se transforma, coincida con el code_challenge original.

Depuración

La información detallada sobre los errores de vinculación está disponible en el Explorador de registros. Para habilitar y ver los errores, sigue las instrucciones que se indican en Supervisa los errores de vinculación de cuentas en tu proyecto de la consola de Google.

Requisitos de configuración de la vinculación de la Cuenta de Google

Lee la siguiente guía de la API para obtener información sobre la configuración de la vinculación de la Cuenta de Google.

• Vinculación de la Cuenta de Google con OAuth
• API de vinculación de cuentas
• Glossary: Google Account Linking API

Para registrar correctamente tu integración de OAuth, debes configurar detalles específicos sobre tu servidor de autorización. Asegúrate de tener preparados los siguientes endpoints, credenciales y recursos.

Campo de configuración	Descripción	Responsabilidad del desarrollador
ID de cliente y secreto	Son las credenciales únicas que genera tu servidor de autorización específicamente para la plataforma de apps conectadas. El secreto del cliente es la credencial segura (contraseña) asociada con el ID de cliente. Nota: Si el desarrollador emitió el ID de cliente, debe proporcionarlo. Si Google emitió el ID de cliente, es posible que el desarrollador deba registrar un secreto o verificar uno.	Usa el ID que proporciona la plataforma en todas las solicitudes de autorización.
Extremo de autorización	Es la URL a la que se redirecciona a los usuarios para que se autentiquen y otorguen su consentimiento.	Aloja el extremo, por ejemplo, https://yourdomain.com/oauth/authorize
Extremo del token	Es el endpoint de backend para intercambiar códigos de autorización por tokens de acceso o tokens de actualización, y para actualizar los tokens vencidos.	Aloja este extremo, por ejemplo, https://yourdomain.com/oauth/token
Extremo de revocación Opcional	Es la URL para notificar a tu sistema que invalide un token cuando un usuario se desconecte. Cuando un usuario desvincule o desconecte tu integración desde la plataforma de Connected Apps, realizaremos una solicitud POST al endpoint /revoke que contenga el token de acceso o el token de actualización. Consulta Cómo desvincular cuentas para obtener más información.	Aloja el extremo, por ejemplo, https://yourdomain.com/oauth/revoke Tu servidor debe controlar esta solicitud invalidando de forma permanente el token proporcionado. Esto garantiza que cualquier intento posterior de la plataforma de apps conectadas de usar ese token fallará, lo que mantendrá la seguridad de los datos del usuario después de la desconexión.
URI de redireccionamiento	Es la URL de devolución de llamada específica que proporciona la plataforma a la que el servidor de autorización envía el código después de que se otorga el consentimiento.	Configura tu servidor de autorización para que acepte solo el URI de redireccionamiento oficial y registrado de la plataforma.
Actualiza la ubicación	/token con grant_type=refresh_token Es un mecanismo que permite que la plataforma de apps conectadas obtenga un nuevo token de acceso cuando venza el actual, lo que mantiene la integración conectada sin problemas y sin que el usuario deba acceder repetidamente. Cuando venza un token de acceso existente, la plataforma de apps conectadas realizará automáticamente una solicitud POST a tu extremo /token. La carga útil de la solicitud incluirá grant_type=refresh_token junto con el token de actualización que tu servidor emitió anteriormente.	Tu servidor debe validar el token de actualización proporcionado y devolver un nuevo token de acceso en la respuesta JSON. Además, para implementar la vinculación persistente, debes evitar rotar el token de actualización durante este intercambio. En lugar de emitir uno nuevo, devuelve exactamente el mismo token de actualización en la respuesta JSON y extiende su fecha de vencimiento en tu backend.
Tipo de respuesta	Se debe configurar como CODE para admitir el flujo de código de autorización.
Permisos	Es el conjunto de permisos y niveles de acceso específicos que definen lo que el token está autorizado a hacer. Estos deben estar predefinidos en tu configuración para que Google pueda solicitarlos durante el protocolo de enlace de autorización inicial.	Deberás proporcionar una lista de permisos predeterminados (por ejemplo, openid, profile, email) que la plataforma de apps conectadas debe solicitar cuando se inicie el flujo. Los permisos solicitados deben ser lo más reducidos posible (principio de privilegio mínimo), pero deben ser suficientes para los recorridos críticos del usuario (CUJ) que admite tu integración de MCP.
Recursos de la IU: Logotipo	Es el logotipo del desarrollador que se mostrará en las pantallas de vinculación de cuentas y consentimiento.	Debe ser una imagen vectorial cuadrada (SVG) con un aspecto circular y, al menos, 500 × 500 píxeles. Por ejemplo, consulta https://[partner-domain]/assets/logo.svg o el archivo SVG sin procesar.
Vinculación de aplicaciones nativas (cambio de app)	Para admitir la vinculación de cuentas directamente desde tus aplicaciones nativas para iOS o Android, no se recomienda usar WebViews estándar. En su lugar, se recomienda implementar el cambio de app para brindar una experiencia del usuario fluida. Consulta Vinculación de la Cuenta de Google con el cambio de app basado en OAuth para obtener más información.	Completa la verificación de Play Store y App Store, y, luego, incorpora los URI de redireccionamiento de Google directamente en tus aplicaciones nativas para garantizar un cambio de autorización seguro de app a app.
Duración de los tokens	(Opcional) Es la duración de la validez de un token de acceso antes de que se requiera una actualización. Es útil para configurar políticas de tiempo de espera en GAL.	Los tiempos de vencimiento comunes varían entre minutos, horas y días, según las necesidades de seguridad (por ejemplo, 30 days).

Errores de integración comunes

A continuación, se incluye una lista de errores comunes y posibles soluciones que se aplican al proceso de integración.

• Falta el otorgamiento "code": El sistema automatizado de la plataforma de Gemini verifica de forma explícita response_types_supported para el valor "code".
• Falta el extremo de registro: Incluso si tu servidor admite documentos de metadatos de ID de cliente, la app de Gemini (que actúa como el cliente de OAuth que se conecta a tu servidor) actualmente requiere que haya un registration_endpoint dedicado en el JSON de descubrimiento.
• Error que no es 200: Si el mecanismo de descubrimiento de metadatos automatizado de Gemini llega a tu URL well-known y recibe un error 404 o 500, no intentará adivinar otras URLs. Asegúrate de que la URL de descubrimiento sea de acceso público.