Skip to main content

Proxmox VE

This guide explains how to connect Proxmox VE to VaultysHub using OpenID Connect. Proxmox VE natively integrates an OpenID Connect authentication "realm": no additional module is required.

Prerequisites​

  • Proxmox VE 7.0 or higher (tested with Proxmox VE 9.2)
  • Access root@pam (or an account with Realm.Allocate and Permissions.Modify)
  • Proxmox VE accessible via HTTPS, and able to reach VaultysHub over HTTPS (the VaultysHub certificate must be recognized by the system's certificate store)

Configuration in VaultysHub​

1. Create the application​

  1. Log in to VaultysHub as an administrator
  2. Go to Applications → Add
  3. Create a new application:
    • Name: Proxmox VE
    • URL: https://proxmox.example.com:8006

2. Configure OpenID Connect​

  1. In the Authentication tab, select OpenID Connect
  2. Note the Client ID, Client Secret, and Issuer URL: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]
  3. Settings:
    • Subject (sub): Email
    • PKCE: required (Proxmox always uses it, in S256)
    • Authentication at token endpoint: client_secret_basic

3. Redirect URL​

Proxmox sends the origin of the login page as the redirect URL, without path or trailing slash. Declare exactly the address used to open Proxmox:

https://proxmox.example.com:8006

If Proxmox is open under multiple addresses (node name, IP, reverse proxy on port 443…), declare each of them.

4. Scopes​

  • openid
  • email
  • profile

Configuration in Proxmox VE​

Option A: web interface​

  1. Datacenter → Permissions → Realms → Add → OpenID Connect Server
  2. Fill in:
    • Issuer URL: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]
    • Realm: vaultyshub
    • Client ID / Client Key: the values noted in VaultysHub
    • Default: checked, to pre-select VaultysHub in the login window
    • Autocreate Users: checked
    • Username Claim: email
    • Scopes: email profile (Proxmox adds openid by itself)
  3. OK

Option B: command line​

pveum realm add vaultyshub --type openid \
  --issuer-url "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]" \
  --client-id "[client-id]" --client-key "[client-secret]" \
  --username-claim email --scopes "email profile" \
  --autocreate 1 --default 1 --comment "VaultysHub"

Note: the username-claim cannot be modified after the realm is created. With email, users are named [email protected]@vaultyshub.

User Rights​

A user created automatically at their first login has no rights: they see an empty tree. Since VaultysHub does not transmit groups, the Groups Claim option in Proxmox cannot be used; assign rights in Proxmox:

# a group for VaultysHub users, with a role on the entire datacenter
pveum group add vaultyshub-users --comment "VaultysHub Users"
pveum acl modify / --groups vaultyshub-users --roles PVEAuditor
# after the first login of a user
pveum user modify "[email protected]@vaultyshub" --groups vaultyshub-users --append 1

Common roles: PVEAuditor (read-only), PVEVMUser (use VMs), PVEAdmin, Administrator. Rights can also be limited to a pool (/pool/<name>) or a VM (/vms/<id>).

Users can also be created in advance (pveum user add [email protected]@vaultyshub) to grant them their rights before their first login.

Testing the configuration​

  1. Open https://proxmox.example.com:8006
  2. The VaultysHub realm is pre-selected: click on Login
  3. Authenticate on VaultysHub
  4. You return to Proxmox, logged in as [email protected]@vaultyshub

Keep access root@pam (realm Linux PAM standard authentication) as a backup.

Troubleshooting​

VaultysHub rejects the redirect URL (redirect_uri)​

The declared redirect URL must match the origin of the login page: same scheme, same name, same port, without a trailing slash. Opening Proxmox by its IP while only the name is declared causes this error.

The connection fails upon return from VaultysHub (certificate)​

Proxmox queries VaultysHub (discovery, token) by checking its certificate against the system store. With an internal certificate authority, add it:

cp my-ca.crt /usr/local/share/ca-certificates/
update-ca-certificates

The user is logged in but sees nothing​

They do not have rights yet: see User Rights.

The user is denied on their first login​

Autocreate Users is not checked: check it, or create the user in advance.

Resources​