Tokens API de Proxmox: por qué necesitan dueño visible

En pocas palabras: Un token API de Proxmox VE no es una identidad propia: hereda los permisos del usuario que lo respalda, por intersección. Por defecto usa “separación de privilegios” (necesita ACLs explícitas), según el wiki de User Management de Proxmox. Sin ACLs propias, un token de un admin conserva ese mismo poder administrativo.

Un token API de Proxmox es una credencial vinculada a un usuario que permite acceso programático (sin contraseña) a la REST API de Proxmox VE, con permisos que se calculan por intersección entre los privilegios del usuario y los del propio token, según el wiki de User Management de Proxmox. Por defecto, cada token nuevo usa “separación de privilegios”, así que necesita ACLs explícitas para hacer algo: si el usuario tiene rol de administrador y el token no tiene ACLs propias que lo acoten, hereda ese mismo poder.

¿Un token de API en Proxmox tiene permisos propios o depende del usuario?

Depende del usuario: un token nunca puede hacer algo que el usuario que lo generó no pueda hacer, según el wiki de User Management de Proxmox. Esa es la base del modelo, y es un techo útil, pero no garantiza nada por sí solo.

Acá está el punto que mucha gente pasa por alto. El wiki de User Management distingue dos tipos de token: “separated privileges” (el default actual, donde el permiso efectivo es la intersección entre lo que puede el usuario y lo que dice la ACL del token) y “full privileges” (el token tiene exactamente los mismos permisos que el usuario). Si alguien desactiva la separación de privilegios “porque la integración lo necesita” y nunca lo revisa de nuevo, terminó con un token que es, en los hechos, una copia de la cuenta del administrador.

Ojo con esto: un token con permiso sobre / es una superficie de control amplia sin importar qué nombre le hayas puesto. “backup-token” suena inofensivo. Si tiene acceso de raíz, no lo es.

¿Cómo sé qué puede hacer realmente un token API de Proxmox?

Mirando la ACL no alcanza. Hay que testear el token contra operaciones que debería poder hacer y contra operaciones que no, confirmando que las negativas sean decisiones de autorización y no errores de otro tipo.

Ponele que generás un token para un job de backups. La ACL dice que tiene acceso a un storage y a un pool de VMs. Bien, en teoría. Pero, ¿probaste qué pasa si ese token intenta tocar una VM que está fuera de ese pool? ¿Probaste un endpoint de gestión de usuarios? ¿Una acción a nivel cluster? Si no lo hiciste, no sabés realmente qué puede hacer el token, sabés qué dice el papel que puede hacer.

Revisá primero la pertenencia a grupos del usuario que respalda el token, y después las ACLs del token en sí. Un token de monitoreo típico necesita solo lectura de estado. Un token de backups necesita storage y pool, nada más. Si tu token tiene más que eso, sobra permiso. Ya lo cubrimos antes en ejecutar agentes locales sin depender de una API.

¿Qué riesgo tiene atar un token de automatización a una cuenta humana?

El riesgo es perder trazabilidad: cuando la persona cambia de rol, se va de la empresa o pierde acceso interactivo, el token que quedó atado a su cuenta se vuelve difícil de auditar, y nadie se acuerda de quién lo creó ni para qué.

Pensalo así: contratás a alguien, esa persona crea un token “para probar la integración con el sistema de monitoreo”, después se va del equipo seis meses más tarde, y el token sigue ahí, funcionando, sin nadie que lo reclame como propio. La nota de Sorrel Thorncroft en dev.to plantea algo simple pero que casi nadie hace: usar una identidad de automatización dedicada, no interactiva cuando sea posible, con dueño y propósito documentados desde el día uno. Nada de “el token de Juan” cuando Juan ya no trabaja ahí.

Tratá la creación de un token como un evento administrativo. El secreto se entrega una sola vez por un canal protegido y va a un gestor de secretos. Nunca al historial de comandos, nunca a un archivo del repo, nunca a un ticket ni a un chat.

¿Cómo se revoca o rota un token API en Proxmox VE?

Se revoca eliminando el token puntual desde pveum o la interfaz web, sin tocar la cuenta del usuario que lo respalda, lo que permite cortar el acceso de una integración comprometida sin tirar abajo las demás.

Esa es, de hecho, la ventaja central de usar tokens en vez de compartir contraseñas: si un token se compromete, lo revocás y el usuario sigue operando normal. Para que esto funcione de verdad, necesitás un token distinto por cada automatización. Un token compartido entre tres sistemas distintos oculta quién hizo qué, y te obliga a romper las tres integraciones si tenés que rotarlo. Complementá con diseñar claves API de forma profesional.

Revisá si tu versión de Proxmox soporta expiración en el token (el parámetro es un timestamp Unix) y usala cuando el flujo de trabajo lo permita. Para tokens de larga vida, armá un cronograma de rotación y una vía de revocación de emergencia documentada, no improvisada el día que la necesitás.

¿Qué pasa con un token si cambian los permisos del usuario que lo generó?

El acceso efectivo del token puede ampliarse sin que haya rotación del token: si el usuario detrás recibe un rol más amplio, el token hereda ese cambio automáticamente, incluso si nadie tocó el token en sí.

Y ahí está la trampa. Subís un token, lo probás, confirmás que las ACLs están bien acotadas, todo tranquilo, y seis meses después alguien en el equipo de infraestructura decide que ese usuario necesita rol de administrador para otra tarea completamente distinta, sin pensar que ese mismo usuario respalda cuatro tokens de automatización que ahora, de golpe, tienen un techo mucho más alto que antes.

¿Alguien se va a dar cuenta a tiempo? Probablemente no, salvo que haya una alerta configurada. Por eso conviene monitorear cambios de privilegios en usuarios y grupos como evento disparador, y revisar las ACLs de los tokens cuando cambia el modelo de roles, no solo cuando cambia el script de automatización que los usa. Cubrimos ese tema en detalle en convertir una CLI en API con JavaScript.

¿Conviene usar un token distinto por cada automatización en Proxmox?

Sí, conviene, porque un token compartido entre varios sistemas hace imposible saber qué integración ejecutó qué acción, y vuelve riesgosa cualquier rotación porque rompe todo lo que depende de ese mismo secreto.

La lógica es simple: si tenés un token único para backups, monitoreo y despliegue, y ese token aparece comprometido, no podés revocarlo sin tirar abajo las tres cosas al mismo tiempo. Con tokens separados, apagás uno y los otros dos siguen funcionando.

Eliminá también los tokens de jobs que ya no existen. La API puede seguir aceptando un token aunque no aparezca en ninguna automatización vigente, y eso es exactamente el tipo de acceso fantasma que nadie revisa hasta que es tarde.

Errores comunes al manejar tokens API en Proxmox

• Dejar “full privileges” activado sin revisarlo después. Se desactiva la separación de privilegios para resolver un problema puntual y queda así para siempre, dándole al token el mismo poder que al usuario completo.
• Confiar en la vista de ACL sin testear el comportamiento real. La ACL dice qué debería pasar; solo probando operaciones concretas (dentro y fuera del alcance esperado) confirmás qué pasa en los hechos.
• Atar tokens de producción a cuentas de personas que rotan de puesto. El token sobrevive al empleado, y nadie sabe después para qué servía ni quién lo puede dar de baja con seguridad.
• Compartir un mismo token entre varias integraciones. Ahorra configuración inicial, pero vuelve a la rotación una operación de alto riesgo y borra la trazabilidad de quién hizo qué.
• No poner fecha de expiración cuando el flujo lo permite. Un token sin vencimiento que quedó de un proyecto cancelado sigue siendo válido para la API aunque nadie lo use.

Preguntas Frecuentes

¿Qué son los tokens API de Proxmox?

Son credenciales vinculadas a un usuario de Proxmox VE que permiten acceso programático a la REST API sin usar la contraseña del usuario. Sus permisos efectivos son la intersección entre los privilegios del usuario y las ACLs propias del token, salvo que esté configurado con “full privileges”. Más contexto en organizar cambios con PRs apilados en GitHub.

¿Cómo se crea un token API en Proxmox VE?

Se crea desde la interfaz web en la sección de usuarios, o con el comando pveum desde la línea de comandos, según documenta el manual de pveum(1). El valor del token solo se muestra una vez al momento de crearlo; si se pierde, hay que generar uno nuevo.

¿Qué diferencia hay entre un token con privilegios separados y uno con privilegios completos?

Un token con privilegios separados (el default) necesita ACLs propias que definan exactamente qué puede hacer, calculadas por intersección con los permisos del usuario. Un token con privilegios completos tiene exactamente los mismos permisos que el usuario que lo respalda, sin acotamiento adicional.

¿Se puede recuperar el valor de un token API si se pierde?

No. Según el wiki oficial de User Management de Proxmox, el valor del token se muestra una sola vez al generarlo y no puede recuperarse después por API. Si se pierde, la única opción es revocarlo y crear uno nuevo.

¿Qué pasa si revoco un token que está comprometido?

El token deja de ser válido para hacer requests a la API, pero el usuario que lo respalda sigue activo y puede seguir operando normalmente, incluyendo generar un token nuevo si la automatización lo necesita.

Conclusión

El modelo de tokens API de Proxmox hace posible delegar acceso sin repartir contraseñas, pero la seguridad real no viene del token en sí, viene de mantener visible quién es el dueño y de probar el límite efectivo de permisos en vez de confiar en la ACL escrita. Si administrás Proxmox VE en un entorno con varios automatismos corriendo (backups, monitoreo, despliegues), conviene auditar ahora mismo qué tokens existen, a qué usuario están atados y si ese usuario cambió de rol sin que nadie revisara el impacto. Un token sin dueño claro es, en la práctica, una puerta sin cartel.

Fuentes

• User Management – Proxmox VE Wiki, sobre gestión de usuarios y tokens API
• pveum(1) – manual oficial del comando de gestión de usuarios de Proxmox VE
• Use Proxmox API tokens as delegated identities with a visible owner – dev.to