Integrating Proxmox VE with LDAP and Active Directory

Why Integrate LDAP or Active Directory

Managing user accounts separately on every system is tedious and error-prone. When someone joins your team, you create accounts in a dozen places. When someone leaves, you inevitably forget one. Integrating Proxmox VE with an existing LDAP directory or Active Directory (AD) eliminates this problem by centralizing authentication. Users log in to Proxmox with the same credentials they use for everything else, and disabling an account in the directory immediately revokes Proxmox access.

Proxmox supports two LDAP-related realm types:

• LDAP – for generic LDAP servers such as OpenLDAP or 389 Directory Server.
• Active Directory – for Microsoft AD with optimized attribute mapping and group sync.

Prerequisites

Before you start, gather the following information from your directory administrator:

• LDAP server hostname or IP address (e.g., ldap.example.com or dc01.example.com).
• Base DN for user searches (e.g., dc=example,dc=com).
• Bind user DN and password (a service account for Proxmox to query the directory).
• User attribute for login (typically sAMAccountName for AD or uid for OpenLDAP).
• Whether TLS/SSL is required and which port to use (389 for LDAP, 636 for LDAPS).

Configuring Active Directory Integration

Step 1: Create a Bind User in AD

Create a dedicated service account in Active Directory for Proxmox to use when querying the directory. This account needs only read access to user and group objects.

# In Active Directory Users and Computers:
# 1. Create a new user: svc-proxmox
# 2. Set "Password never expires" and "User cannot change password"
# 3. Add to "Domain Users" group only (no admin rights needed)

# The bind DN will be something like:
# CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com
# Or use the UPN format: svc-proxmox@example.com

Step 2: Add the AD Realm in Proxmox

You can configure this through the web GUI under Datacenter > Permissions > Realms > Add > Active Directory Server, or via the command line:

# Add an Active Directory realm
pveum realm add example-ad --type ad \
    --domain example.com \
    --server1 dc01.example.com \
    --server2 dc02.example.com \
    --secure 1 \
    --port 636 \
    --default 0 \
    --comment "Corporate Active Directory" \
    --bind-dn "CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com" \
    --password "bind-user-password" \
    --base-dn "DC=example,DC=com" \
    --user-attr sAMAccountName

Key parameters explained:

• --server1 and --server2: Primary and fallback domain controllers.
• --secure 1: Enables LDAPS (TLS). Always use this in production.
• --user-attr sAMAccountName: The AD attribute used as the login username.
• --base-dn: Where in the directory tree to search for users.

Step 3: Test the Connection

# Try logging in via the web GUI with: username@example-ad
# Or test from the command line:
pveum user list --realm example-ad

# Check if users can be found
pveum realm sync example-ad --dry-run --enable-new 0

Configuring OpenLDAP Integration

For generic LDAP servers like OpenLDAP or 389 Directory Server, the configuration is similar but uses the LDAP realm type:

# Add an LDAP realm
pveum realm add corp-ldap --type ldap \
    --server1 ldap.example.com \
    --secure 1 \
    --port 636 \
    --base-dn "ou=People,dc=example,dc=com" \
    --user-attr uid \
    --bind-dn "cn=proxmox-bind,ou=Services,dc=example,dc=com" \
    --password "bind-password" \
    --comment "Corporate OpenLDAP" \
    --default 0

# For LDAP with STARTTLS instead of LDAPS:
pveum realm add corp-ldap --type ldap \
    --server1 ldap.example.com \
    --port 389 \
    --secure 0 \
    --comment "OpenLDAP with STARTTLS"

Group Synchronization

One of the most powerful features of LDAP integration is automatic group synchronization. Proxmox can import groups from your directory and keep them in sync, so you can assign Proxmox roles to directory groups.

# Configure group sync for the AD realm
pveum realm modify example-ad \
    --group-dn "OU=Groups,DC=example,DC=com" \
    --group-classes group \
    --group-filter "(|(cn=Proxmox*)(cn=IT*))" \
    --sync-defaults-options "full,enable-new=1,purge=1"

# Run a sync (dry-run first to preview changes)
pveum realm sync example-ad --dry-run --enable-new 1

# If the dry-run looks correct, run the actual sync
pveum realm sync example-ad --enable-new 1

# View the synced groups
pveum group list

After syncing, you can assign Proxmox roles to the imported groups just like any other group:

# Grant the synced AD group VM admin access
pveum acl modify /vms --roles PVEVMAdmin --groups "example-ad-ProxmoxAdmins"

# Grant auditor access to a monitoring group
pveum acl modify / --roles PVEAuditor --groups "example-ad-IT-Monitoring"

Configuring TLS and Certificate Trust

Using LDAPS (port 636) or STARTTLS is essential to prevent credentials from being transmitted in cleartext. If your LDAP server uses a certificate from an internal CA, you need to make Proxmox trust that CA.

# Copy your internal CA certificate to the Proxmox node
scp internal-ca.crt root@proxmox:/usr/local/share/ca-certificates/

# Update the certificate store
update-ca-certificates

# Verify the LDAP server's certificate
openssl s_client -connect dc01.example.com:636 \
    -CAfile /etc/ssl/certs/ca-certificates.crt < /dev/null 2>/dev/null | \
    openssl x509 -noout -subject -issuer -dates

# If using a self-signed cert (not recommended for production),
# you can also set verify=0 in the realm config as a last resort
pveum realm modify example-ad --verify 0

Troubleshooting Common Issues

Users Cannot Log In

# Verify the bind user can connect
ldapsearch -x -H ldaps://dc01.example.com:636 \
    -D "CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com" \
    -w "bind-password" \
    -b "DC=example,DC=com" \
    "(sAMAccountName=testuser)"

# Check Proxmox authentication logs
journalctl -u pvedaemon --since "10 minutes ago" | grep -i auth

# Verify the realm is configured correctly
pveum realm list --output-format json-pretty

Group Sync Returns No Results

# Test the group search filter manually
ldapsearch -x -H ldaps://dc01.example.com:636 \
    -D "CN=svc-proxmox,OU=Service Accounts,DC=example,DC=com" \
    -w "bind-password" \
    -b "OU=Groups,DC=example,DC=com" \
    "(objectClass=group)" cn

# Verify the group-dn path is correct
# Verify the group-classes matches your directory (group for AD, groupOfNames for OpenLDAP)

TLS Connection Failures

# Test TLS connectivity
openssl s_client -connect dc01.example.com:636 < /dev/null

# Check for certificate errors
openssl s_client -connect dc01.example.com:636 \
    -CAfile /etc/ssl/certs/ca-certificates.crt 2>&1 | grep -i verify

# Check if the CA certificate was properly installed
ls -la /etc/ssl/certs/ | grep internal

Remote Monitoring After Integration

After setting up directory integration, it is worth verifying that your Proxmox cluster remains healthy and accessible. If you are not always near your workstation, ProxmoxR lets you quickly check your Proxmox nodes and VM status from your phone. This is especially useful after making authentication changes, since you can confirm everything is running smoothly without needing to sit down at a computer.

Best Practices

• Always use TLS. LDAP traffic includes passwords in bind operations. Without TLS, these are sent in cleartext across the network.
• Use a dedicated bind account with minimal read-only permissions. Never use a domain admin account for the Proxmox bind user.
• Configure a fallback server. Use --server2 to specify a secondary domain controller for high availability.
• Use group-based permissions. Sync directory groups to Proxmox and assign roles to groups rather than individual users. This way, granting or revoking Proxmox access is as simple as modifying group membership in AD.
• Run sync regularly. Set up a cron job or systemd timer to run pveum realm sync periodically so that group membership changes in the directory are reflected in Proxmox.
• Keep a local admin account. Always maintain a working root@pam account in case the LDAP server becomes unreachable. This is your emergency access path.
• Test with a dry-run first. Before syncing with purge=1 (which removes users not found in the directory), always run a dry sync to preview the changes.

Summary

Integrating Proxmox VE with LDAP or Active Directory centralizes authentication and makes user management dramatically simpler. Users get single sign-on with their existing credentials, and administrators can control Proxmox access through directory group membership. The key steps are creating a dedicated bind account, configuring the realm with TLS, setting up group synchronization, and assigning Proxmox roles to synced groups. Always maintain a local admin account as a fallback, and test thoroughly before enabling the integration in production.