Integrations · OIDC

Proxmox VE SSO

Configure Proxmox Virtual Environment 7.1+ to authenticate administrators and users via Clavex using OpenID Connect. Map Clavex group claims to Proxmox pools, resource groups, and privilege levels.

Prerequisites

Proxmox VE ≥ 7.1
Root or Proxmox admin access
Clavex at https://id.acme.eu, org slug acme
HTTPS with a trusted certificate on both Proxmox and Clavex

Step 1 — Register OIDC Client in Clavex

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "proxmox", "client_name": "Proxmox VE", "grant_types": ["authorization_code"], "redirect_uris": ["https://proxmox.acme.eu:8006"], "scopes": ["openid", "profile", "email"], "token_endpoint_auth_method": "client_secret_basic" }'

Redirect URI: Proxmox uses its own base URL (including port 8006) as the redirect URI. Ensure the exact URL https://proxmox.acme.eu:8006 is registered. Do not add a trailing slash or path.

Step 2 — Add OpenID Realm in Proxmox

Via Web UI

Datacenter → Permissions → Realms → Add → OpenID Connect Server

Fill in:

Field	Value
Realm	`clavex`
Issuer URL	`https://id.acme.eu/acme`
Client ID	`proxmox`
Client Key	`cs_xxxxxxxxxxxxxxxx`
Username claim	`email`
Default	check if you want this as the default realm
Autocreate Users	enable to auto-provision on first login

Via pveum CLI

bash (Proxmox host)

$ pveum realm add clavex --type openid \ --issuer-url "https://id.acme.eu/acme" \ --client-id "proxmox" \ --client-key "cs_xxxxxxxxxxxxxxxx" \ --username-claim "email" \ --autocreate 1 \ --comment "Clavex OIDC SSO"
# Verify realm was created $ pveum realm list

Step 3 — Assign Permissions to SSO Users

Proxmox creates SSO users with the format user@email.com@clavex. Assign permissions to individual users or create a group:

bash

# Create a group for infra admins $ pveum group add infra-admins --comment "Infrastructure Admins"
# Grant the group PVEAdmin role on the datacenter $ pveum acl modify / -group infra-admins -role PVEAdmin
# After a user logs in via SSO, add them to the group $ pveum group member add infra-admins -user "alice@acme.eu@clavex"

Step 4 — Test Login

Navigate to https://proxmox.acme.eu:8006
On the login screen, change the Realm dropdown to clavex
Click Login — you will be redirected to Clavex
After authentication, you land back on Proxmox with the user's role applied

Troubleshooting

Symptom	Cause	Fix
`SSL peer certificate verification failed`	Proxmox can't verify Clavex TLS cert	Add Clavex CA to Proxmox: `update-ca-certificates`
Realm not listed in dropdown	Realm not created or not enabled	Run `pveum realm list`; ensure `--autocreate` was included
User has no permissions after login	SSO user not assigned to any group/role	Assign role via `pveum acl modify` or add user to group in Proxmox UI
`invalid_client` from Clavex	Client ID or secret mismatch	Verify `pveum realm config clavex` shows correct client-id
Redirect URI mismatch error	Proxmox URL with port not registered	Ensure `redirect_uris` in Clavex includes `https://host:8006` (no trailing slash)