Skip to content

Resource: proxmox_realm_ldap

Manages an LDAP authentication realm in Proxmox VE.

LDAP realms allow Proxmox to authenticate users against an LDAP directory service.

Privileges Required

Path Attribute
/access/domains Realm.Allocate

Schema

Required

  • base_dn (String) LDAP base DN for user searches (e.g., 'ou=users,dc=example,dc=com').
  • realm (String) Realm identifier (e.g., 'example.com').
  • server1 (String) Primary LDAP server hostname or IP address.

Optional

  • bind_dn (String) LDAP bind DN for authentication (e.g., 'cn=admin,dc=example,dc=com').
  • bind_password (String, Sensitive) Password for the bind DN. Note: stored in Proxmox but not returned by API.
  • ca_path (String) Path to CA certificate file for SSL verification.
  • case_sensitive (Boolean) Enable case-sensitive username matching.
  • cert_key_path (String) Path to client certificate key.
  • cert_path (String) Path to client certificate for SSL authentication.
  • comment (String) Description of the realm.
  • default (Boolean) Use this realm as the default for login.
  • filter (String) LDAP filter for user searches.
  • group_classes (String) LDAP objectClasses for groups (comma-separated).
  • group_dn (String) LDAP base DN for group searches.
  • group_filter (String) LDAP filter for group searches.
  • group_name_attr (String) LDAP attribute representing the group name.
  • mode (String) LDAP connection mode (ldap, ldaps, ldap+starttls).
  • port (Number) LDAP server port. Default: 389 (LDAP) or 636 (LDAPS).
  • secure (Boolean, Deprecated) Use LDAPS (LDAP over SSL/TLS) instead of plain LDAP.
  • server2 (String) Fallback LDAP server hostname or IP address.
  • ssl_version (String) SSL/TLS version (tlsv1, tlsv1_1, tlsv1_2, tlsv1_3).
  • sync_attributes (String) Comma-separated list of attributes to sync (e.g., 'email=mail,firstname=givenName').
  • sync_defaults_options (String) Default synchronization options. Format: comma-separated 'key=value' pairs. Valid keys: 'scope' (users/groups/both), 'enable-new' (1/0), 'remove-vanished' (semicolon-separated: entry/acl/properties), 'full' (deprecated), 'purge' (deprecated). Example: 'scope=users,enable-new=1,remove-vanished=entry;acl'.
  • user_attr (String) LDAP attribute representing the username.
  • user_classes (String) LDAP objectClasses for users (comma-separated).
  • verify (Boolean) Verify LDAP server SSL certificate.

Read-Only

  • id (String) Realm identifier (same as realm)

Notes

Password Security

The bind_password is sent to Proxmox and stored securely, but it's never returned by the API. This means: - Terraform cannot detect if the password was changed outside of Terraform - You must maintain the password in your Terraform configuration or use a variable - The password will be marked as sensitive in Terraform state

LDAP vs LDAPS

  • LDAP (port 389): Unencrypted connection. Not recommended for production.
  • LDAPS (port 636): Encrypted connection using SSL/TLS. Recommended for production.
  • LDAP+StartTLS: Upgrades plain LDAP connection to TLS. Alternative to LDAPS.

User Synchronization

To trigger synchronization, use the proxmox_realm_sync resource.

Common Configuration Scenarios

Anonymous Binding

For testing or public LDAP servers, omit bind_dn and bind_password to use anonymous binding: 

resource "proxmox_realm_ldap" "anonymous" {
  realm     = "public-ldap"
  server1   = "ldap.example.com"
  base_dn   = "ou=users,dc=example,dc=com"
  user_attr = "uid"
}

Secure LDAPS with Failover

resource "proxmox_realm_ldap" "secure" {
  realm         = "secure-ldap"
  server1       = "ldap1.example.com"
  server2       = "ldap2.example.com"  # Failover server
  port          = 636
  base_dn       = "ou=users,dc=example,dc=com"
  bind_dn       = "cn=readonly,dc=example,dc=com"
  bind_password = var.ldap_password
  mode          = "ldaps"
  verify        = true
  ca_path       = "/etc/pve/priv/ca.crt"
}

With Group Synchronization

resource "proxmox_realm_ldap" "with_groups" {
  realm                 = "corporate-ldap"
  server1               = "ldap.corp.example.com"
  base_dn               = "ou=users,dc=corp,dc=example,dc=com"
  bind_dn               = "cn=svc_ldap,ou=services,dc=corp,dc=example,dc=com"
  bind_password         = var.ldap_password
  mode                  = "ldap+starttls"

  # Group settings
  group_dn              = "ou=groups,dc=corp,dc=example,dc=com"
  group_filter          = "(objectClass=groupOfNames)"
  group_name_attr       = "cn"

  # Sync configuration
  sync_attributes       = "email=mail,firstname=givenName,lastname=sn"
  sync_defaults_options = "scope=both,enable-new=1"
}

See Also