Usuarios, permisos y Active Directory en Proxmox VE 9: la guía de control de acceso

Por Javier

La mayoría de instalaciones de Proxmox que me encuentro en auditorías tienen exactamente un usuario operativo: root@pam. Todo el equipo comparte esa contraseña, la automatización usa esa contraseña, y cuando alguien se va de la empresa nadie la cambia porque medio departamento la tiene apuntada. Eso no es un modelo de control de acceso, es una cuenta compartida con permisos de dios sobre el hipervisor. Proxmox VE 9 trae un sistema de autenticación y autorización perfectamente capaz de separar identidades, acotar privilegios y delegar tareas sin regalar el clúster entero. Este tutorial cubre el modelo completo: realms, usuarios, grupos, roles, privilegios, ACL sobre el árbol de objetos, API tokens, integración con Active Directory y LDAP, SSO por OpenID Connect, y segundo factor. Todo con comandos reales de pveum validados contra Proxmox VE 9.x.

El modelo de autenticación: los realms

Proxmox separa dos preguntas que la gente tiende a mezclar: quién eres (autenticación) y qué puedes hacer (autorización). La autenticación se resuelve mediante realms, que son los dominios de autenticación donde vive la identidad de cada usuario. Un usuario en Proxmox nunca es solo javier: siempre es javier@REALM. El realm forma parte del identificador y determina cómo se valida la credencial.

Proxmox VE 9 soporta varios tipos de realm, cada uno pensado para un escenario distinto:

El realm pam y el realm pve vienen creados de fábrica y no se pueden borrar. El resto los añades tú. Para listar los realms configurados y añadir uno nuevo:

# Listar realms existentes
pveum realm list

# Marcar un realm como el que sale seleccionado por defecto en la pantalla de login
pveum realm modify corp-ad --default 1

Un detalle que ahorra sustos: el realm por defecto es solo el que aparece preseleccionado en el desplegable de login. No cambia dónde se validan las credenciales ni concede permisos. Y aunque marques un realm corporativo como default, root@pam sigue existiendo y sigue siendo superusuario.

Usuarios, grupos, roles y privilegios

Resuelta la autenticación, entra en juego la autorización. Aquí hay cuatro piezas que conviene tener claras porque se combinan entre sí:

• Privilegio: la unidad atómica de permiso. Cosas como VM.Config.Disk, Datastore.AllocateSpace, Sys.PowerMgmt o VM.Console. Hay decenas, agrupados por área (VM, Datastore, Sys, User, Pool, SDN, Realm, Permissions…).
• Rol: un conjunto con nombre de privilegios. En lugar de asignar 15 privilegios sueltos, asignas el rol que los agrupa.
• Usuario y grupo: las identidades. Un grupo es una bolsa de usuarios. Siempre que puedas, trabaja con grupos.
• ACL: la regla que une todo. Una ACL dice "a este usuario o grupo, sobre este objeto del árbol, le concedo este rol".

Crear un grupo, un usuario local y meterlo en el grupo es directo:

# Crear un grupo funcional
pveum group add noc --comment "Equipo de operaciones 24x7"

# Crear un usuario en el realm interno de Proxmox y añadirlo al grupo
pveum user add operador@pve --comment "Operador de guardia" --groups noc

# Asignarle contraseña (solo aplica a realms pve y pam)
pveum passwd operador@pve

Los roles son donde se hace el trabajo fino. Proxmox trae un juego de roles integrados que cubre la mayoría de casos sin que tengas que definir nada:

Cuando ninguno encaja, defines el tuyo. La gracia de un rol propio es empaquetar exactamente los privilegios que necesita un perfil concreto y nada más. Por ejemplo, un rol para un equipo que solo hace copias de seguridad:

# Crear un rol a medida solo con lo justo para backups
pveum role add OperadorBackup --privs "VM.Backup VM.Audit Datastore.AllocateSpace Datastore.Audit"

# Ver los privilegios de un rol concreto
pveum role list

# Ampliar el rol más adelante
pveum role modify OperadorBackup --privs "VM.Backup VM.Audit VM.Snapshot Datastore.AllocateSpace Datastore.Audit"

Un aviso sobre role modify: reemplaza la lista completa de privilegios, no la amplía de forma incremental. Si pasas --privs, el rol queda con exactamente esos privilegios. Ponlos todos cada vez.

ACL: el árbol de objetos, la herencia y la propagación

Aquí es donde la mayoría de la gente se confunde, así que vamos despacio. Proxmox modela todos sus recursos como un árbol de rutas (paths), parecido a un sistema de ficheros. Cada objeto tiene su path:

• / — la raíz. Un permiso concedido aquí afecta a todo el clúster.
• /vms — todas las máquinas virtuales y contenedores. /vms/100 — solo la VM/CT con VMID 100.
• /storage — todos los almacenamientos. /storage/local-zfs — solo ese datastore.
• /nodes — todos los nodos. /nodes/pve01 — solo ese nodo físico.
• /pool/produccion — un pool de recursos concreto.
• /sdn/zones/…, /access/groups, /access/realm/… — ramas de SDN, identidades y realms.

Una ACL asocia una identidad (usuario, grupo o token) con un rol sobre un path. La regla clave: los permisos se heredan hacia abajo. Si concedes un rol en /, aplica a todo el árbol. Si lo concedes en /vms, aplica a todas las VMs, presentes y futuras. Si lo concedes en /vms/100, solo a esa. Esta herencia por path es lo que permite delegar de forma limpia: das mucho arriba a poca gente y poco abajo a mucha gente.

La propagación es un matiz que casi nadie mira. Por defecto una ACL propaga a los sub-paths (propagate=1). Puedes crear una ACL no propagante para que un rol aplique al objeto exacto pero no a lo que cuelga de él. Se usa poco, pero es la herramienta correcta cuando quieres conceder algo en un nivel sin arrastrarlo hacia abajo.

# Dar solo-lectura de todo el clúster al grupo de operaciones
pveum acl modify / --groups noc --roles PVEAuditor

# Dar administración de VMs solo sobre el pool de laboratorio
pveum acl modify /pool/lab --groups devs --roles PVEVMAdmin

# Conceder consola y encendido de UNA sola VM a un usuario
pveum acl modify /vms/100 --users soporte@pve --roles PVEVMUser

# ACL que NO propaga: rol aplicado al path exacto, sin heredar a sub-objetos
pveum acl modify /storage --groups noc --roles PVEDatastoreUser --propagate 0

# Revisar todas las ACL definidas
pveum acl list

Cuando un usuario acumula permisos por varias vías (por ser miembro de dos grupos, o por tener una ACL directa y otra heredada), Proxmox suma los privilegios. La excepción es NoAccess: asignarlo en un path concreto corta la herencia de privilegios en esa rama, útil para excluir una VM sensible de un permiso amplio concedido más arriba.

API tokens: automatización sin repartir contraseñas

Meter la contraseña de un usuario dentro de un pipeline de Terraform, un script de Ansible o un cron es exactamente lo que no quieres. Los API tokens resuelven esto: son credenciales independientes, asociadas a un usuario pero con su propio secreto, su propia caducidad y —esto es lo importante— sus propios permisos.

El identificador de un token tiene la forma USUARIO@REALM!NOMBRETOKEN. La opción decisiva al crearlo es la separación de privilegios (privsep):

• Con --privsep 1 (recomendado), el token nace sin ningún permiso. Tienes que concederle ACL explícitamente. Sus permisos efectivos son la intersección de lo que tiene el usuario y lo que tiene el token: nunca puede hacer más que su usuario, y normalmente hace mucho menos.
• Con --privsep 0, el token hereda exactamente los permisos del usuario. Cómodo y peligroso: un token filtrado equivale a la cuenta entera.

# Crear una cuenta de servicio y un token acotado para automatización
pveum user add automation@pve --comment "Cuentas de servicio de CI/CD"

# Token con separación de privilegios: nace sin permisos y con caducidad
pveum user token add automation@pve terraform --privsep 1 \
  --expire 1782000000 --comment "Pipeline Terraform infra-lab"

# El secreto se muestra UNA sola vez en la salida: guárdalo en el gestor de secretos ahora

# Conceder al token SOLO lo que necesita, acotado a un pool
pveum acl modify /pool/lab --tokens 'automation@pve!terraform' --roles PVEVMAdmin

# Auditar y revocar
pveum user token list automation@pve
pveum user token permissions automation@pve terraform
pveum user token remove automation@pve terraform

El parámetro --expire es un timestamp Unix; ponlo siempre en tokens de máquina para que caduquen solos. Y fíjate en el patrón: el token vive en automation@pve, pero sus ACL van al --tokens, no al usuario. Puedes tener el usuario sin ningún permiso global y el token con permisos quirúrgicos sobre un solo pool. Eso es mínimo privilegio de verdad.

Integración con Active Directory

El escenario habitual en empresa: las identidades ya viven en Active Directory y no quieres duplicar cuentas ni contraseñas en Proxmox. La integración tiene tres fases: crear el realm, sincronizar usuarios y grupos, y mapear grupos de AD a roles de Proxmox mediante ACL.

Crear el realm de Active Directory

Necesitas: el dominio, al menos un controlador de dominio como servidor LDAP, el base DN donde buscar, y una cuenta de bind de solo lectura para consultar el directorio. Usa LDAPS (puerto 636) siempre que puedas; el tráfico de directorio no debería ir en claro.

# Crear un realm de tipo Active Directory con bind seguro (LDAPS/636)
pveum realm add corp-ad --type ad \
  --domain corp.example.com \
  --server1 dc01.corp.example.com \
  --server2 dc02.corp.example.com \
  --port 636 --secure 1 \
  --base-dn 'DC=corp,DC=example,DC=com' \
  --bind-dn 'CN=svc-proxmox,OU=Servicios,DC=corp,DC=example,DC=com' \
  --user-classes user \
  --group-classes group \
  --sync-attributes email=mail,firstname=givenName,lastname=sn
# La contraseña del bind se pide de forma interactiva y se guarda cifrada en /etc/pve/priv/

En un realm de tipo ad el atributo de login es sAMAccountName por defecto, que es lo que espera un usuario de Windows al escribir su nombre corto. El --server2 te da un DC de reserva si el primario no responde. Y --sync-attributes mapea atributos de AD a campos de Proxmox: correo, nombre y apellidos vienen bien para que la interfaz muestre personas y no cadenas crípticas.

Sincronizar usuarios y grupos

La sincronización copia usuarios y grupos de AD a la base de Proxmox para poder asignarles ACL. Antes de nada, un dry-run para ver qué entraría sin tocar nada:

# Previsualizar qué usuarios y grupos importaría (no modifica nada)
pveum realm sync corp-ad --scope both --dry-run 1

# Sincronización real: usuarios y grupos, activando los nuevos
pveum realm sync corp-ad --scope both --enable-new 1

# Sincronización con purga de los que ya no existen en AD
pveum realm sync corp-ad --scope both --enable-new 1 --remove-vanished 'entry;properties'

Dos parámetros que hay que entender bien porque deciden cómo se comporta la sincronización:

• --enable-new: si es 1, los usuarios recién descubiertos entran habilitados. Si es 0, entran deshabilitados y los activas a mano. En entornos grandes, 0 es más prudente para no dar de alta a media empresa de golpe.
• --remove-vanished: qué hacer con lo que ya no aparece en AD. entry borra la entrada, properties limpia atributos huérfanos, acl retira sus permisos. Si no lo pones, los usuarios dados de baja en AD siguen existiendo en Proxmox: un agujero de seguridad clásico.

Un detalle importantísimo del naming: los grupos sincronizados llevan el nombre del realm añadido. Un grupo de AD llamado Virtualization-Admins aparece en Proxmox como Virtualization-Admins-corp-ad. Esto evita colisiones entre realms y es el nombre que usarás en las ACL.

Sincronización automática

Lanzar pveum realm sync a mano no escala. Proxmox VE permite programar la sincronización como un trabajo recurrente desde Datacenter → Permissions → Realms, editando el realm y definiendo sus opciones de sync por defecto, más un Realm Sync Job con su calendario (formato de eventos de calendario tipo systemd, por ejemplo */30 minutos o daily). Las opciones que fijes ahí (scope, enable-new, remove-vanished) son las que aplicará el job automático. La recomendación de producción: sincroniza con una frecuencia razonable (cada pocas horas o a diario) y activa remove-vanished para que las bajas de RRHH en AD se reflejen en Proxmox sin intervención manual.

Mapear grupos de AD a roles de Proxmox

Este es el paso que cierra el círculo y el que hace que la gestión sea sostenible. En vez de asignar permisos usuario por usuario, asignas roles a los grupos de AD. Cuando RRHH mete a alguien en el grupo correcto de AD, esa persona hereda sus permisos en Proxmox tras el siguiente sync. Cuando lo sacan, los pierde. Cero mantenimiento en Proxmox.

# El grupo de AD "Virtualization-Admins" administra todas las VMs
pveum acl modify /vms --groups 'Virtualization-Admins-corp-ad' --roles PVEVMAdmin

# El grupo "IT-Auditors" tiene solo-lectura de todo el clúster
pveum acl modify / --groups 'IT-Auditors-corp-ad' --roles PVEAuditor

# El grupo "Backup-Team" solo puede hacer copias, con un rol a medida
pveum acl modify /vms --groups 'Backup-Team-corp-ad' --roles OperadorBackup

LDAP genérico

Si tu directorio no es Active Directory sino un LDAP estándar (OpenLDAP, 389 DS, FreeIPA vía LDAP…), el realm es de tipo ldap y el proceso es idéntico, con la diferencia de que aquí sí defines a mano el atributo de login, que suele ser uid en lugar de sAMAccountName:

# Realm LDAP genérico con login por uid
pveum realm add ldap-corp --type ldap \
  --server1 ldap.example.com --port 636 --secure 1 \
  --base-dn 'ou=People,dc=example,dc=com' \
  --user-attr uid \
  --bind-dn 'uid=svc-proxmox,ou=Services,dc=example,dc=com'

# La sincronización y el mapeo de grupos funcionan igual que en AD
pveum realm sync ldap-corp --scope both --enable-new 1

OpenID Connect: SSO real

LDAP y AD validan la contraseña dentro de Proxmox. OpenID Connect da un paso más y delega el login por completo en un proveedor de identidad externo: Entra ID (Azure), Keycloak, Authentik, Okta… El usuario nunca escribe su contraseña en Proxmox; se autentica en el IdP, que devuelve un token, y Proxmox confía en él. Eso te da SSO, políticas de acceso condicional y MFA centralizadas en el IdP. En Proxmox VE 9 el flujo OIDC funciona incluso desde la interfaz móvil, algo que antes no estaba resuelto, y admite audiencias adicionales en la validación del token para escenarios donde el IdP emite tokens para varios clientes.

# Realm OpenID Connect contra Microsoft Entra ID
pveum realm add entra --type openid \
  --issuer-url 'https://login.microsoftonline.com/<tenant-id>/v2.0' \
  --client-id 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --client-key 'CLIENT_SECRET_DEL_IDP' \
  --username-claim email \
  --autocreate 1

Las piezas clave del realm OIDC:

• --issuer-url: la URL del proveedor. Proxmox descubre los endpoints por el estándar de discovery del propio IdP.
• --client-id y --client-key: las credenciales de la aplicación que registras en el IdP. En el IdP tienes que dar de alta la URL de redirección de tu Proxmox como URI de retorno válida.
• --username-claim: qué campo del token se usa como nombre de usuario en Proxmox. Suele ser email, username o subject. Elige uno estable: si cambia, el usuario "nuevo" pierde sus permisos.
• --autocreate 1: crea el usuario en Proxmox la primera vez que inicia sesión con éxito. Cómodo, pero recuerda que nace sin permisos: le asignas rol por grupo o directamente por ACL.

Con OIDC la autenticación deja de ser problema de Proxmox y pasa a ser problema del IdP, que es donde ya tienes MFA, expiración de sesión y bloqueo de cuentas bien montados. Proxmox se limita a autorizar.

Segundo factor: TOTP y WebAuthn

Para los realms donde la contraseña la valida Proxmox (pve, pam, LDAP, AD), el segundo factor lo pones tú. Proxmox VE 9 soporta TOTP (los códigos de 6 dígitos de Google Authenticator, Aegis, etc.) y WebAuthn (llaves físicas FIDO2 tipo YubiKey, o el biométrico del dispositivo), además de claves de recuperación de un solo uso.

Cada usuario registra su segundo factor desde su propio menú de usuario en la interfaz. El TOTP se enrola escaneando un QR; funciona sin configuración previa. WebAuthn sí exige un paso de administrador antes: hay que definir el Relying Party en Datacenter → Options → WebAuthn Settings (el ID y el origin, que deben cuadrar con el nombre DNS con el que accedes a Proxmox), porque el estándar ata la credencial al dominio. Si no configuras eso primero, los usuarios no pueden registrar llaves.

A nivel de realm puedes además exigir segundo factor, de modo que ningún usuario de ese realm entre sin él. En cuentas con permisos amplios esto no es opcional: es lo mínimo. Genera y guarda claves de recuperación al enrolar, porque el día que se pierda el móvil o la llave, esa es la única vía de entrada que te queda que no pase por tocar la base de datos a mano.

Buenas prácticas de producción

• Mínimo privilegio, siempre. Concede el rol más pequeño sobre el path más específico que resuelva la tarea. Nada de Administrator en / salvo para quien realmente administra el clúster entero.
• Roles a grupos, no a usuarios. Asignar ACL a personas individuales genera un mantenimiento imposible de auditar. Asigna roles a grupos y gestiona las personas moviéndolas entre grupos, idealmente desde AD.
• root@pam solo para emergencias. Trata esa cuenta como el "break glass": contraseña larga en el gestor de secretos, con 2FA, y usada solo cuando el sistema de permisos normal ha fallado. El trabajo diario se hace con cuentas nominativas.
• Tokens para toda la automatización. Ni un script debería llevar contraseña de usuario. Token con privsep 1, ACL acotada al path mínimo y --expire puesto. Un token por integración, para poder revocar uno sin tumbar los demás.
• Separa realms por propósito. Identidades humanas en AD/OIDC, cuentas de servicio en el realm pve, y pam reservado a lo estrictamente operativo del sistema. No mezcles automatización con personas en el mismo realm.
• Cuentas nominativas para auditar. Si todo el mundo entra como el mismo usuario, el log de tareas de Proxmox no te dice quién hizo qué. Una identidad por persona es la base de cualquier auditoría posterior.
• Delega la administración de usuarios. Con PVEUserAdmin sobre /access puedes dar a un equipo la capacidad de gestionar identidades sin cederles el control del hipervisor.

Caveats: lo que rompe en producción

• root@pam es intocable. No importa qué ACL definas: root@pam es siempre superusuario y no puedes quitarle permisos. No intentes "asegurar" el clúster restringiéndole ACL; asegúralo con una contraseña fuerte y 2FA sobre esa cuenta.
• La herencia mal entendida concede de más. Un rol amplio en /vms o en / se derrama sobre todo lo que cuelga, incluidas las VMs que crees mañana. Antes de conceder algo arriba, piensa qué arrastra hacia abajo. Cuando quieras excepciones, usa NoAccess en la rama concreta.
• La sincronización sin remove-vanished deja fantasmas. Si sincronizas AD sin purgar, los usuarios dados de baja en el directorio siguen teniendo cuenta y permisos en Proxmox. Configura la purga en el job automático o hazlo tú, pero no lo dejes al azar.
• El schedule del sync importa. Si sincronizas una vez al día, hay hasta 24 horas de ventana entre que RRHH cambia algo en AD y Proxmox lo refleja. Ajusta la frecuencia al riesgo que asumes.
• El realm por defecto no autoriza nada. Marcar un realm como default solo cambia el desplegable de login. No concede permisos ni cambia dónde se validan las credenciales.
• Cambiar el username-claim de OIDC parte usuarios. Si un usuario ya existía mapeado por email y cambias a subject, para Proxmox es otra persona: pierde sus ACL. Elige el claim al principio y no lo toques.
• Los grupos sincronizados cambian de nombre. Recuerda el sufijo -realm. Las ACL apuntan a grupo-realm, no a grupo; es el error de tipeo más habitual al montar el mapeo.