En corto

En Keycloak: Clients → Create client → OpenID Connect, Client ID proxmox, Client authentication On, Standard flow On, Valid redirect URIs https://pve.example.local:8006 y https://pve.example.local:8006/*. Copia el secret de la pestaña Credentials.

En un nodo Proxmox:

1
2
3
4
5
6
7

pveum realm add keycloak --type openid \
  --issuer-url https://id.example.local/realms/lab \
  --client-id proxmox \
  --client-key '<client-secret>' \
  --username-claim preferred_username \
  --autocreate 1 \
  --comment 'Keycloak'

Los usuarios entran como alice@keycloak. Se crean solos al primer login, sin permisos; los permisos siguen siendo ACLs de Proxmox:

1
2
3

pveum group add sso-admins
pveum acl modify / --groups sso-admins --roles Administrator
pveum user modify alice@keycloak --groups sso-admins     # después de su primer login

Cómo funciona

Proxmox soporta realms openid desde PVE 7. Con issuer-url descarga /.well-known/openid-configuration y de ahí saca los endpoints; en la pantalla de login aparece el realm en el desplegable y el botón Login redirige a Keycloak. Al volver, el valor del claim que elegiste en username-claim se convierte en el usuario <claim>@<realm>.

username-claim acepta cualquier nombre de claim. Keycloak manda preferred_username por defecto (viene del mapper username del client scope profile), así que no hace falta el mapper adicional que traían las guías antiguas para exponer un claim llamado username. Si prefieres el correo, --username-claim email.

Keycloak, paso a paso (26)

  1. Realm. Usa el que tengas (lab en el ejemplo). El issuer es https://id.example.local/realms/lab. Desde Keycloak 17 ya no hay /auth/ en la ruta; si copias /auth/realms/... de una guía vieja, el discovery falla.
  2. Clients → Create client.
    • Client type: OpenID Connect. Client ID: proxmox. Name: lo que quieras.
    • Capability config: Client authentication On (cliente confidencial, con secret). Standard flow On. Todo lo demás Off: Direct access grants, Implicit flow, Service accounts, Authorization.
    • Login settings: Root URL https://pve.example.local:8006; Valid redirect URIs https://pve.example.local:8006 y https://pve.example.local:8006/*. Web origins vacío: es un flujo de redirección, no hay CORS.
  3. Credentials → Client secret. Es el --client-key.
  4. Grupos (opcional). Clients → proxmox → Client scopes → proxmox-dedicated → Add mapper → By configuration → Group Membership: Name groups, Token Claim Name groups, Full group path Off, Add to ID token y Add to userinfo On.

Proxmox, paso a paso

Por GUI: Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm (el nombre corto, keycloak), Client ID, Client Key, Username Claim preferred_username, Autocreate Users. O el pveum realm add del En corto; la configuración queda en /etc/pve/domains.cfg y se replica al clúster.

Con grupos desde Keycloak, en versiones recientes de PVE 8 y en PVE 9 (pveum realm add --help te dice si tu versión tiene --groups-claim):

1

pveum realm modify keycloak --groups-claim groups --groups-autocreate 1

Cada grupo del claim se crea como <grupo>-keycloak y el usuario entra en ellos en cada login; los ACLs los asignas a esos grupos.

Prueba antes de tocar nada más: pantalla de login → Realm Keycloak → Login → vuelves autenticado y pveum user list muestra alice@keycloak.

Trampas

  • Invalid parameter: redirect_uri en Keycloak: la URL con la que entras al navegador (nombre, puerto 8006, https) no está en Valid redirect URIs. Si usas la IP y el FQDN, agrega las dos.
  • El certificado de Keycloak lo tiene que aceptar el nodo, no solo tu navegador. Con una CA interna: copia el .crt a /usr/local/share/ca-certificates/ y update-ca-certificates.
  • issuer-url tiene que coincidir exactamente con el iss de los tokens: https, sin barra final, /realms/<realm>.
  • Hora. Un reloj desfasado invalida los tokens; chrony en los nodos.
  • No dejes que el usuario edite su propio username en Keycloak (aviso de la propia documentación de Proxmox): cambiarse el nombre a root es cambiarse de cuenta en Proxmox.
  • No pongas --default 1 hasta que funcione, y deja root@pam como puerta de emergencia: si Keycloak cae, el realm openid no puede autenticar a nadie.
  • API y CLI. Los usuarios OIDC no tienen contraseña en Proxmox; para Terraform, Ansible o pvesh desde fuera crea un token: pveum user token add alice@keycloak automation --privsep 0.

Referencia: User Management — OpenID Connect en la guía de Proxmox y la creación de clientes en la documentación de Keycloak.