By default, every Proxmox VE installation ships with two built-in authentication realms: pam, which checks credentials against the host's Linux system accounts, and pve, which stores users in Proxmox's own internal database. Both work fine for a single admin managing a homelab, but they fall apart the moment more than a handful of people need access. Every new hire means creating a Linux account or a Proxmox user by hand. Every departure means remembering to remove it everywhere. There is no central place to enforce a password policy, and nothing ties a user's Proxmox login to the identity your organization already manages.

Proxmox VE solves this with external authentication realms: LDAP and Microsoft Active Directory. Instead of maintaining a parallel set of credentials, Proxmox authenticates users directly against your existing directory server and can automatically synchronize users and groups into its own permission system. This guide walks through exactly how to set that up — from the GUI and from the command line — using the real configuration properties Proxmox exposes, not a simplified approximation of them.

What You Will Learn

  • The difference between the ldap and ad realm types and when to use each
  • How to add and test a realm through the web GUI
  • The equivalent pveum CLI commands for scripted or repeatable deployments
  • How user and group synchronization works, including dry-run previews
  • How to combine directory authentication with Proxmox's RBAC permission model
  • Common bind, certificate, and sync errors, and how to fix each one

Why Use LDAP or Active Directory Instead of PAM?

PAM authentication is tied to the operating system of the specific node handling the login request, which becomes awkward in a cluster — you'd need matching Linux accounts on every node. The built-in pve realm avoids that problem but still requires you to set and manage a separate password for every user, with no connection to any password policy, lockout rule, or offboarding process your organization already has for Active Directory or OpenLDAP.

Pointing Proxmox at an existing directory service means:

  • Users log in with the same credentials they already use everywhere else.
  • Disabling or deleting an account in AD/LDAP takes effect for Proxmox access without touching Proxmox at all.
  • Group membership in the directory can be synchronized and mapped to Proxmox roles, so access control follows your existing org structure.
  • Password complexity, rotation, and account lockout policies are enforced by the directory, not reinvented in Proxmox.

Prerequisites

  • A running Proxmox VE 8.x or 9.x host or cluster with administrative (root) access to the web GUI or shell.
  • A reachable LDAP or Active Directory server, including its hostname/IP and listening port (389 for plaintext/StartTLS, 636 for LDAPS).
  • A service account in the directory that Proxmox can use to bind and search — sometimes called a "read-only" or "bind" account. Anonymous binds are technically supported but strongly discouraged, and Microsoft AD normally requires an authenticated bind by default.
  • The Base DN (the container or organizational unit under which user objects live), for example OU=Staff,DC=example,DC=com.
  • If you plan to use LDAPS or StartTLS (recommended), the CA certificate for your directory server, or the ability to skip verification for internal testing only.
  • A list of which directory groups should map to which Proxmox permission roles.

Understanding Realm Types in Proxmox VE

Proxmox VE separates authentication from authorization. A realm only answers the question "is this a valid login?" — it does not, by itself, grant any permissions. Every user, regardless of realm, still needs an entry in Proxmox's user list and at least one ACL/role assignment before they can do anything in the datacenter. Proxmox ships four realm types:

Realm TypePurpose
pamLinux system accounts on the node handling the login (built-in, cannot be removed)
pveProxmox's internal user database (built-in, cannot be removed)
ldapGeneric LDAPv3 directory, e.g. OpenLDAP, 389 Directory Server, FreeIPA
adMicrosoft Active Directory, with AD-specific defaults and behavior

Proxmox also supports an openid realm type for OIDC-based single sign-on, but that uses a different configuration flow and is outside the scope of this guide, which focuses specifically on directory-bind authentication via LDAP and AD.

LDAP vs. Active Directory: What Actually Differs

Mechanically, the ad realm type is a thin, AD-aware wrapper around the same LDAP protocol. The practical differences are:

  • Username attribute — AD environments almost always authenticate against sAMAccountName (or userPrincipalName), while generic LDAP directories commonly use uid or cn.
  • Bind requirement — Microsoft AD typically rejects anonymous binds outright, so bind_dn/bind_password are effectively mandatory for the ad type.
  • Case sensitivity — AD usernames are case-insensitive by convention; the ad realm type defaults accordingly, whereas LDAP directories may be case-sensitive depending on schema.
  • Domain field — the ad type accepts a domain parameter that can be used for auto-discovery of domain controllers via DNS SRV records, which the generic ldap type does not offer.

Step 1: Gather Your Directory Details

Before touching the GUI, write down the values you'll need. For a typical Active Directory environment:

Domain:        example.com
Domain Controller (server1): dc1.example.com
Fallback DC (server2):        dc2.example.com
Port:          389 (or 636 for LDAPS)
Base DN:       OU=Staff,DC=example,DC=com
Bind DN:       CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com
User attribute: sAMAccountName

For a generic OpenLDAP directory:

Server (server1): ldap.example.com
Port:             389 (or 636 for LDAPS)
Base DN:          ou=People,dc=example,dc=com
Bind DN:          cn=admin,dc=example,dc=com
User attribute:   uid

Step 2: Add the Realm via the Web GUI

  1. Log in to the Proxmox VE web interface as a user with Realm.Allocate permission (root@pam has this by default).
  2. Navigate to Datacenter → Permissions → Realms.
  3. Click Add, then choose either LDAP Server or Microsoft Active Directory server from the dropdown, depending on your environment.
  4. On the General tab, fill in:
    • Realm — a short identifier, e.g. example-ad. This becomes the suffix on every synced username: jdoe@example-ad.
    • Domain (AD only) — your Active Directory domain name, e.g. example.com.
    • Server and Fallback Server — the primary and (optional) secondary directory server addresses.
    • Port — 389 for plaintext/StartTLS, 636 for LDAPS.
    • Base Domain Name — the DN under which user accounts live.
    • User Attribute Name — sAMAccountName for AD, or uid/cn for generic LDAP.
  5. On the same or an adjacent tab, set Bind User (the full DN of your service account) and its password. Leave this blank only if your directory explicitly permits anonymous search, which is rare and not recommended.
  6. Open the Sync Options tab and configure:
    • Scope — sync users only, groups only, or both.
    • User/Group Filter — an optional LDAP filter to restrict which objects are pulled in, e.g. (memberOf=CN=ProxmoxUsers,OU=Groups,DC=example,DC=com) so only a specific group's members get synced instead of your entire directory.
    • Enable new — whether newly synced users are enabled immediately (default: yes).
    • Remove Vanished — controls whether users/ACLs/groups that no longer appear in the directory are automatically disabled or removed on subsequent syncs. Leave this off until you've confirmed your filters are correct — it is destructive against Proxmox's own user list if misconfigured.
  7. Under the SSL section, enable SSL/TLS Encryption if you're binding on port 636 (LDAPS), and either point Certificate Path at your directory's CA bundle or, for internal lab environments only, disable certificate verification. Production deployments should always verify the certificate chain.
  8. Click OK to save the realm without syncing yet.

Step 3: Preview and Run the Sync

Rather than syncing blind, use the built-in preview:

  1. Select the newly created realm in the Realms list and click Sync.
  2. Check Preview (dry-run) before your first real sync. Proxmox will show you exactly which users and groups it intends to create, update, or remove without committing any changes.
  3. Review the preview output carefully. If the numbers look wrong — far more or far fewer entries than expected — revisit your Base DN and filter settings before proceeding.
  4. Once the preview looks correct, uncheck Preview and run the sync for real.

After a successful sync, the new users appear under Datacenter → Permissions → Users with the realm suffix, e.g. jdoe@example-ad, and any synced groups appear under Groups with the realm ID appended to avoid collisions, e.g. Admins-example-ad.

Step 4: Do the Same Thing on the Command Line

Everything above has a pveum equivalent, which is worth using if you're scripting a deployment or managing configuration as code. Adding an Active Directory realm:

pveum realm add example-ad \
  --type ad \
  --domain example.com \
  --server1 dc1.example.com \
  --server2 dc2.example.com \
  --port 389 \
  --base-dn "OU=Staff,DC=example,DC=com" \
  --bind-dn "CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com" \
  --user-attr sAMAccountName \
  --case-sensitive 0

Adding a generic LDAP realm against OpenLDAP:

pveum realm add example-ldap \
  --type ldap \
  --server1 ldap.example.com \
  --port 389 \
  --base-dn "ou=People,dc=example,dc=com" \
  --bind-dn "cn=admin,dc=example,dc=com" \
  --user-attr uid \
  --secure 1 \
  --capath /etc/ssl/certs

You'll be prompted for the bind password interactively, or you can supply it non-interactively for automation:

pveum realm modify example-ad --password 'SuperSecretBindPW'

Store that password carefully — Proxmox itself keeps it at /etc/pve/priv/realm/<realmname>.pw, readable only by root, and it never appears in /etc/pve/domains.cfg in plaintext.

Run a dry-run sync from the shell before committing:

pveum realm sync example-ad --dry-run 1 --scope both --verbose 1

Then run it for real once you're satisfied with the preview:

pveum realm sync example-ad --scope both --enable-new 1

To keep the directory and Proxmox in sync going forward, schedule this as a cron job or, on newer Proxmox VE releases, configure it as a scheduled realm sync job directly from the Realms panel in the GUI, which stores the schedule in the cluster configuration instead of a node-local crontab.

Step 5: Grant Permissions to Synced Users and Groups

A successful sync only means the users and groups now exist in Proxmox — it does not grant them any access. This is by design: Proxmox never assumes that directory membership implies a specific permission level. You still assign roles the normal way:

# Give everyone in the synced "Admins" group the PVEAdmin role at the root path
pveum acl modify / --group Admins-example-ad --role PVEAdmin

# Give a synced group read-only access to a specific VM pool
pveum acl modify /pool/production --group Auditors-example-ad --role PVEAuditor

A practical pattern is to create your directory groups first (e.g. Proxmox-Admins, Proxmox-Operators, Proxmox-Auditors) purely for Proxmox access control, sync only those groups using a user/group filter, and then map each one to a role once, rather than assigning permissions to individual synced users. When someone joins or leaves the team, you manage that entirely in the directory — group membership changes flow through on the next sync, and Proxmox permissions stay correct automatically.

Combining Directory Auth with Two-Factor Authentication

External realms handle password authentication only; they don't natively carry MFA state from your directory into Proxmox. If your organization requires 2FA for infrastructure access, you can still enforce TOTP or WebAuthn as a second factor on top of an LDAP or AD realm by setting a TFA policy at the realm level (Datacenter → Permissions → Realms → <realm> → TFA), which forces every user authenticating through that realm to additionally enroll and pass a second factor at login, independent of anything the directory itself enforces.

Common Errors and Troubleshooting

"authentication failure" immediately after adding the realm

This almost always means the bind account or bind password is wrong, or the account lacks permission to search the directory. Test the bind independently from the Proxmox shell before blaming Proxmox's configuration:

ldapsearch -x -H ldap://dc1.example.com -D "CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com" -W -b "OU=Staff,DC=example,DC=com" "(sAMAccountName=jdoe)"

If this fails outside of Proxmox, the problem is directory-side (credentials, ACLs, or network reachability), not a Proxmox misconfiguration.

Sync completes but returns zero users

Usually a Base DN or filter mismatch. Double-check that the Base DN actually contains the user objects — a common mistake is pointing at the domain root (DC=example,DC=com) when users actually live several OUs deep, or applying a group filter that doesn't match any real group.

Certificate verification errors on LDAPS/StartTLS

Confirm the CA certificate configured under Certificate Path actually corresponds to the certificate the directory server presents, and that the hostname you connect to matches the certificate's Subject Alternative Name — connecting by IP address to a certificate issued for a hostname will fail verification even with the correct CA loaded.

Case-sensitivity mismatches with Active Directory

Because AD is case-insensitive by convention but Proxmox's own account model is not, mixed-case logins can silently create duplicate near-identical accounts if case-sensitive isn't explicitly disabled for an ad-type realm. Set --case-sensitive 0 when adding the realm to avoid this.

Usernames containing colons or forward slashes fail to sync

Proxmox reserves the colon character as a field separator internally and interprets forward slashes as ACL path separators, so directory usernames containing either will fail to sync cleanly. This is rare with typical AD/LDAP naming conventions but worth knowing if your directory allows unusual username formats.

"Remove Vanished" deleted users you didn't expect

This option is powerful and destructive by design — it exists specifically to keep Proxmox's user list from drifting away from the directory over time. If a filter is too narrow or a sync runs against the wrong OU, it can remove or disable legitimate accounts on the very next run. Always validate with --dry-run 1 after changing any filter or scope setting, and consider leaving Remove Vanished disabled until your sync configuration has been stable for at least a few cycles.

Best Practices

  • Use a dedicated, least-privilege bind account. It only needs read access to the relevant OU — never reuse a domain admin account as the bind DN.
  • Scope your sync with a group filter. Syncing your entire corporate directory into Proxmox is rarely what you want; restrict sync to a dedicated "Proxmox access" security group.
  • Always dry-run before enabling Remove Vanished. Confirm the preview matches your expectations at least once before letting Proxmox delete or disable accounts automatically.
  • Prefer LDAPS or StartTLS over plaintext. Bind credentials and search results otherwise travel the network unencrypted.
  • Map groups to roles, not individual users. Let group membership in the directory drive Proxmox access so offboarding is automatic.
  • Keep root@pam as a break-glass account. Don't remove local root access entirely — if the directory server becomes unreachable, you still need a way into Proxmox.
  • Schedule recurring syncs. A one-time sync drifts out of date; automate it via cron or the built-in scheduled sync feature so directory changes propagate on a predictable cadence.

Frequently Asked Questions

Can I use both an LDAP realm and Active Directory realm at the same time?

Yes. Proxmox VE allows multiple realms of any type simultaneously, alongside the built-in pam and pve realms. Users simply select the correct realm at login, and existing PAM/PVE accounts are unaffected by adding external realms.

Does synchronization keep passwords in sync, or just usernames and group membership?

Only usernames, group membership, and optional attributes like email are synchronized. Proxmox never stores or caches directory passwords — every login is authenticated live against the directory server at sign-in time.

What happens to synced users if the directory server goes down?

Users on that realm cannot log in until the directory server (or its configured fallback server) is reachable again, since authentication happens live. This is exactly why keeping root@pam available as a local break-glass account matters.

Can I map specific AD security groups directly to specific Proxmox roles automatically?

Group sync brings matching directory groups into Proxmox as groups, but role assignment is still a separate, explicit step performed with pveum acl modify or via the GUI. There's no built-in automatic mapping from an AD group name to a specific Proxmox role — you configure that mapping once after the group exists.

Is anonymous bind ever acceptable?

Only for directories explicitly configured to allow anonymous search, which is uncommon and generally discouraged even for LDAP; Microsoft Active Directory rejects anonymous binds by default and effectively requires bind_dn/bind_password to be set.

Conclusion

Adding an LDAP or Active Directory realm turns Proxmox VE's access control from a system you maintain by hand into one that inherits directly from your organization's existing identity source. The setup itself is a handful of fields — server address, base DN, bind account, user attribute — but the details around sync scope, filters, and the Remove Vanished option are where deployments most often go wrong, which is why validating every sync with a dry-run preview before committing it matters more than any single configuration field. Once the realm is in place and mapped to roles through group membership, day-to-day access management becomes a directory administration task instead of a Proxmox one — exactly the outcome external authentication is meant to deliver.