Ir al contenido
ComStack

OAuth y seguridad en MCP

Descripción general

La API de ComStack utiliza OAuth 2.1 con PKCE (RFC 7636), registro dinámico de clientes (RFC 7591) y el formato de metadatos de descubrimiento requerido por la especificación MCP (RFC 8414). Esta página describe el flujo de autorización, el modelo de almacenamiento de tokens, los roles y las medidas de seguridad que protegen un sitio activo, así como los endpoints de estado del conector que los clientes MCP pueden usar para verificar el estado de la conexión.

Descubrimiento

Dos endpoints de descubrimiento exponen metadatos legibles por máquina:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource

Ambos devuelven JSON que describe el emisor, las cuatro URLs de los endpoints y el método PKCE admitido (solo S256).

Endpoints

EndpointMétodoPropósito
/oauth/registerPOSTRegistro dinámico de clientes. Devuelve un client_id; no hay secreto de cliente (cliente público).
/oauth/authorizeGETRenderiza la interfaz de inicio de sesión.
/oauth/authorize/completePOSTLlamado por la interfaz tras completar el inicio de sesión. Emite un código de autorización y redirige.
/oauth/tokenPOSTIntercambia un código de autorización o token de actualización por un token de acceso.

Todas las solicitudes a /oauth/* están sujetas a un límite de 30 solicitudes por minuto por IP.

Flujo de autorización

client -> /oauth/register          -> { client_id }
client -> /oauth/authorize?...      -> login UI rendered
user signs in
login UI -> /oauth/authorize/complete -> { code }, redirect to redirect_uri
client -> /oauth/token (code)      -> { access_token, refresh_token }
client -> POST /mcp with Bearer    -> MCP traffic

Almacenamiento de tokens

Todos los tokens se almacenan como sha256(rawValue); el valor en texto plano solo lo conoce el titular.

Tipo de tokenTTLNotas
Código de autorización60 sDe un solo uso; se elimina tras el intercambio.
Token de acceso1 hValidado en cada solicitud /mcp.
Token de actualización30 dRotado en cada uso (ver más abajo).
Token de confirmación de publicación5 minDe un solo uso.

Rotación de tokens y revocación de familia

Cada canje de token de actualización emite uno nuevo y registra el anterior como rotado. Si se presenta nuevamente un token previamente rotado, toda la familia de tokens se revoca de inmediato. Esto protege contra ataques de repetición donde un atacante captura un token de actualización después de que el cliente legítimo ya lo haya rotado.

Roles y medidas de seguridad de publicación

OAuth identifica quién eres; tu rol en cada proyecto decide qué puedes hacer. La jerarquía es none < guest < member < manager < admin, resuelta por proyecto y almacenada en caché durante unos 30 segundos. La respuesta de tools/list se filtra por rol: los miembros ven herramientas de lectura y creación; los gerentes añaden herramientas destructivas y de publicación; los administradores de la plataforma añaden la gestión de plantillas. (No existen roles de editor/viewer).

Dos medidas de seguridad adicionales protegen el sitio activo:

  • Eco de project_name — las herramientas destructivas (publish, delete-page, update-theme, upload-custom-page y similares) requieren el nombre exacto del proyecto obtenido mediante get-project-state (comparado sin distinguir mayúsculas y minúsculas, y recortado). Cualquier discrepancia rechaza la acción antes de escribir.
  • Publicación en dos pasos — publish es una prueba que solo devuelve un manifiesto de diferencias más un token de confirmación de un solo uso de 5 minutos; nada se despliega hasta publish-confirm, que verifica nuevamente que ningún borrador o tema haya cambiado desde la prueba. Ambos requieren el rol de manager.

Estado del conector

La página de Cuenta muestra un indicador de conexión para clientes MCP. Dos endpoints HTTP admiten esto; son endpoints REST, no mensajes del protocolo MCP:

EndpointMétodoDescripción
/api/account/connectors/claude/statusGETDevuelve { connected, last_seen_at }. Conectado cuando el emisor posee al menos un token de acceso no expirado para un cliente Claude MCP.
/api/account/connectors/claudeDELETERevoca todos los tokens de acceso y actualización activos para clientes Claude MCP en esta cuenta. El usuario debe volver a autorizar dentro de Claude para reconectar.

Errores comunes

invalid_client — el client_id no es reconocido o pertenece a otro contexto de usuario. Vuelve a registrarte usando /oauth/register para obtener un nuevo client_id.

invalid_grant en el intercambio de tokens — el código de autorización expiró (TTL de 60 s) o ya fue utilizado. Reinicia el flujo desde /oauth/authorize.

invalid_grant al actualizar — el token de actualización fue rotado o revocado. Si se reutiliza un token rotado, toda la familia es revocada. El usuario debe volver a autorizar.

Límite de tasa excedido — HTTP 429 al llamar a cualquier endpoint /oauth/* más de 30 veces por minuto desde una IP. Espera e intenta de nuevo con un retraso exponencial.

Relacionado

Última actualización: