Proxmox VE LDAP and Active Directory Authentication

Connecting Proxmox VE to your existing LDAP directory or Active Directory domain means every admin logs in with their corporate credentials — no separate Proxmox password to juggle, no shared root@pam account floating around, and a proper audit trail in /var/log/auth.log showing exactly who authenticated and when. By the end of this guide, you'll have a working LDAP realm in Proxmox VE 9.1, users synchronized from your directory, and AD security groups mapped directly to Proxmox roles.

Key Takeaways

• Realm types: Proxmox supports PAM, PVE, LDAP, Active Directory, and OIDC — each with different trust models and sync capabilities.
• Sync is optional but useful: You can authenticate against LDAP without pre-syncing users, but syncing lets you assign roles via the GUI and see usernames in the audit log.
• Groups map to roles: Assign an entire AD group to a Proxmox role once; every member inherits the permission at the specified resource path.
• Keep a local escape hatch: Always maintain a tested local root@pam or admin@pve account — if LDAP becomes unreachable, you need a way back in.
• TLS is non-negotiable: Use LDAPS (port 636) or STARTTLS; plain LDAP on port 389 sends credentials in cleartext.

Why Centralized Auth Beats Local Proxmox Users

The default Proxmox setup gives you root@pam backed by Linux PAM and local users backed by Proxmox's own PVE database. Both work fine for a single-node homelab where you're the only admin. Scale to a team of three, or expand into a multi-node Proxmox private cloud, and the cracks show fast:

• Password rotation means touching every node and every user manually
• You have no idea which "admin" shut down a production VM at 2 AM
• Onboarding and offboarding requires logging into Proxmox specifically, not your IdP

LDAP integration solves all three. It also lets you reuse existing group structures — your "Infrastructure Admins" AD group becomes a Proxmox Administrator role assignment in about 60 seconds.

Active Directory vs plain LDAP: The Proxmox realm type labeled "Active Directory" in the GUI is still LDAP under the hood, but it pre-fills sane defaults for Microsoft's schema (sAMAccountName attribute, DC= base DN format, Kerberos realm field). If you're running OpenLDAP, FreeIPA, or Authentik with an LDAP backend, use the generic "LDAP" realm type instead.

Prerequisites: What You Need Before You Start

Before touching the Proxmox GUI, gather these details:

• LDAP server hostname — a domain controller FQDN for AD, or your OpenLDAP server address. Use the FQDN, not an IP — it matters for TLS certificate validation.
• Base DN — e.g., DC=corp,DC=example,DC=com for AD, or dc=example,dc=org for OpenLDAP.
• Bind account — a read-only service account in AD (e.g., svc-proxmox) with permission to read users and groups. Do not use a Domain Admin for this.
• Bind account DN or UPN — e.g., svc-proxmox@corp.example.com (UPN format works cleanly for AD).
• Bind password — stored encrypted by Proxmox under /etc/pve/priv/, but still: use a long, random password for this service account.
• CA certificate — if you're using LDAPS with a private CA, you need the certificate chain in PEM format.

Create the bind account on the AD side first:

# Run on a Windows Server domain controller
New-ADUser -Name "svc-proxmox" `
  -SamAccountName "svc-proxmox" `
  -UserPrincipalName "svc-proxmox@corp.example.com" `
  -Path "OU=Service Accounts,DC=corp,DC=example,DC=com" `
  -AccountPassword (ConvertTo-SecureString "YourLongRandomPassword!" -AsPlainText -Force) `
  -PasswordNeverExpires $true `
  -Enabled $true

By default, Domain Users can read user and group objects in AD, so svc-proxmox being a Domain User is enough — no special delegation required.

How to Add an LDAP Realm in Proxmox VE

Open the Realm Configuration

In the Proxmox web UI, navigate to Datacenter → Permissions → Authentication. You'll see the two default realms (pve and pam). Click Add and choose Active Directory Server or LDAP Server depending on your directory type.

Fill in Server and Bind Details

For Active Directory, the form fields map like this:

Field	Example Value	Notes
Realm	corp	Short name used at login: user@corp
Base Domain Name	corp.example.com	Proxmox derives the base DN automatically
Server	dc01.corp.example.com	Use FQDN — required for TLS
Port	636	LDAPS; use 389 + STARTTLS if LDAPS is unavailable
User Attribute	sAMAccountName	For AD; use uid for OpenLDAP or FreeIPA
Domain	corp.example.com	Kerberos realm field (AD only)
Bind User	svc-proxmox@corp.example.com	UPN format works cleanly for AD
Bind Password	YourLongRandomPassword!	Stored encrypted in /etc/pve/priv/

For OpenLDAP or FreeIPA, the equivalent settings:

# OpenLDAP / FreeIPA realm values
Base DN:       dc=example,dc=org
Server:        ldap.example.org
Port:          636
User Attr:     uid
Bind DN:       cn=svc-proxmox,ou=serviceaccounts,dc=example,dc=org
Bind Password: YourLongRandomPassword!

Import the CA Certificate for TLS

If your LDAP server uses a certificate signed by a private CA — which is almost always the case in enterprise Active Directory environments — import that CA certificate into Proxmox's trust store before saving the realm:

# Copy your CA cert (PEM format) to the system trust store
cp /path/to/corp-ca.pem /usr/local/share/ca-certificates/corp-ca.crt
update-ca-certificates

After importing, Proxmox will verify the LDAPS certificate against the system trust store. Without this step, you're forced to disable certificate verification — acceptable on a homelab, never in production.

Gotcha: If your AD uses an intermediate CA, you need the full chain, not just the root. Export it from Active Directory Certificate Services:

# On a domain controller — exports the full issuing chain
certutil -ca.cert corp-ca-chain.crt

SCP that file to your Proxmox node and run update-ca-certificates again.

Configure Sync Attributes

In the realm editor, switch to the Sync tab and set:

• Sync Attributes: cn,mail,sAMAccountName for AD (or cn,mail,uid for OpenLDAP)
• User Classes: user for AD (or inetOrgPerson for OpenLDAP)
• Group Classes: group for AD (or groupOfNames / posixGroup for OpenLDAP)
• Group DN: the OU where your infra groups live, e.g., OU=Infra Groups,DC=corp,DC=example,DC=com

Save the realm. If Proxmox reports a bind error immediately, double-check the bind account UPN and password — don't proceed until the realm saves cleanly.

How to Sync Users and Groups from Active Directory

Running the First Sync

Trigger a manual sync from the CLI rather than the GUI — the CLI output is more informative:

# Sync both users and groups from the 'corp' realm
pveum realm sync corp --enable-new true --purge false --scope both

--scope both pulls users and groups. --enable-new true marks newly synced users as enabled in Proxmox. --purge false leaves existing Proxmox users untouched if they no longer appear in LDAP — safer for a first run.

Expected output:

syncing realm 'corp'...
synced 47 users
synced 12 groups
done

Verify in the GUI under Datacenter → Permissions → Users — your AD users appear with the @corp suffix, and groups appear under Datacenter → Permissions → Groups.

Scheduling Automatic Syncs

Don't rely on manual syncs for production. Add a cron job to keep Proxmox in sync with your directory:

# /etc/cron.d/proxmox-ldap-sync
# Sync the corp realm every 4 hours
0 */4 * * * root /usr/bin/pveum realm sync corp --enable-new true --purge false --scope both >> /var/log/proxmox-ldap-sync.log 2>&1

With --purge false, users removed from AD won't lose Proxmox access until you enable purge or manually disable them. In environments with strict offboarding requirements, run a weekly purge job as well:

# Weekly purge — removes Proxmox users no longer in LDAP
0 5 * * 0 root /usr/bin/pveum realm sync corp --purge true --scope users >> /var/log/proxmox-ldap-sync.log 2>&1

Pair this with SSH hardening and fail2ban to make sure stale accounts left behind by a delayed purge cycle can't be exploited.

Mapping AD Groups to Proxmox Roles

This is where centralized auth pays off. Instead of assigning roles to individual users, assign them to groups — Proxmox respects LDAP group membership for permission decisions.

First, confirm groups appeared after the sync:

pveum group list

Then assign roles to groups at the appropriate resource path:

# 'infra-admins' AD group gets full Administrator access cluster-wide
pveum acl modify / --group 'infra-admins' --role Administrator

# 'dev-team' gets VM admin rights only in the dev resource pool
pveum acl modify /pool/dev-pool --group 'dev-team' --role PVEVMAdmin

# Read-only auditors can view everything, change nothing
pveum acl modify / --group 'proxmox-readonly' --role PVEAuditor

The built-in roles worth knowing:

Role	What It Allows
Administrator	Full cluster access — treat like root for Proxmox operations
PVEAdmin	Manage VMs, storage, networks — no user or realm management
PVEVMAdmin	Full VM lifecycle — no node or storage administration
PVEVMUser	Start, stop, and open console — no config changes
PVEAuditor	Read-only view of the entire cluster
PVEDatastoreAdmin	Manage backups and storage pools — useful for dedicated backup operators

If none of these fit, create a custom role:

pveum role add StorageOperator \
  --privs "Datastore.Audit,Datastore.AllocateSpace,Datastore.AllocateTemplate"

Testing and Verifying Authentication End-to-End

Before announcing the change to your team, verify the full chain works from the Proxmox host itself:

# Test the LDAP bind directly (install if missing: apt-get install -y ldap-utils)
ldapsearch -H ldaps://dc01.corp.example.com \
  -D "svc-proxmox@corp.example.com" \
  -w "YourLongRandomPassword!" \
  -b "DC=corp,DC=example,DC=com" \
  "(sAMAccountName=testuser)" cn mail

A successful bind returns cn and mail attributes for the test user. Common errors:

• ldap_bind: Invalid credentials (49) — wrong bind DN or password
• Can't contact LDAP server — firewall blocking port 636 or DNS failure; test reachability with:

nc -zv dc01.corp.example.com 636

• TLS: hostname does not match — the server cert CN or SAN doesn't match the hostname you configured; use the FQDN that matches the certificate

Then test interactively: log out of the Proxmox GUI, select the corp realm in the login dropdown, and authenticate as a known AD user. If you're using Ansible playbooks to manage your Proxmox cluster, add an LDAP connectivity check task to your pre-upgrade playbook — LDAP failures discovered mid-upgrade are painful.

If realm config changes aren't taking effect, restart pvedaemon:

systemctl restart pvedaemon

What to Do When LDAP Auth Breaks

The most common failure scenario: the LDAP server becomes unreachable, or the bind account password expires, and suddenly nobody can log in. This is exactly why you keep a local admin account active and tested.

# Log in as root@pam via console, iDRAC, iLO, or IPMI
# Then check configured realms
pveum realm list

# Disable the broken realm while you investigate
# (existing sessions continue; new logins to this realm fail with a clean error)
pveum realm modify corp --disable true

# Re-enable once the LDAP issue is resolved
pveum realm modify corp --disable false

Common root causes when LDAP breaks suddenly:

1. Bind account password expired — check in AD:

Search-ADAccount -PasswordExpired -UsersOnly | Select-Object Name, PasswordExpiredAt

2. Certificate expired — check the LDAPS cert expiry from the Proxmox host:

echo | openssl s_client -connect dc01.corp.example.com:636 2>/dev/null \
  | openssl x509 -noout -dates

3. Domain controller unreachable — DNS change, firewall rule update, or DC maintenance window

4. Realm config corrupted after a Proxmox upgrade — inspect /etc/pve/domains.cfg directly for garbled entries; the file is plain text and editable

Active sessions are unaffected when LDAP goes down — Proxmox session tokens aren't re-validated against LDAP on every request. Anyone already logged in continues working until their session expires (default timeout is 2 hours). New logins fail.

Conclusion

Proxmox VE's LDAP and Active Directory integration eliminates the overhead of managing Proxmox-specific passwords for every admin — the setup takes under 30 minutes once you have the bind account and base DN in hand. The discipline that makes it reliable over the long term is three things: a tested local admin account as a fallback, LDAPS with verified certificates in production, and scheduled sync jobs rather than ad-hoc manual runs. Once AD groups map to Proxmox roles, onboarding a new team member is as simple as adding them to the right security group — Proxmox picks it up on the next sync. To close down the remaining attack surface after enabling centralized auth, work through SSH hardening, fail2ban, and the Proxmox firewall as your next step.