LDAP Authentication¶

The base container images authenticate users against an external LDAP directory using SSSD. Rather than shipping its own directory, the platform connects containers to your existing LDAP infrastructure (Active Directory, OpenLDAP, FreeIPA, 389 Directory Server, etc.). This guide covers pointing containers at your servers via environment variables and, optionally, configuring Proxmox to authenticate against the same directory.

How It Works¶

Every base image runs systemd as PID 1. At boot, before SSSD starts, a oneshot unit renders the SSSD configuration from a template:

/etc/sssd/sssd.conf.template  --(envsubst, reads /etc/environment)-->  /etc/sssd/sssd.conf

The container's environment variables (written to /etc/environment) are substituted into the template, so the running SSSD config is built from the SSSD_* variables described below. Because the file is regenerated on every start, updating the variables and recreating the container is all that's needed to re-point authentication at a different directory.

The rendered [domain/default] section looks like this:

[sssd]
domains = default

[domain/default]
id_provider = ldap
auth_provider = ldap
access_provider = ldap
ldap_uri = ${SSSD_LDAP_URI}
ldap_tls_reqcert = ${SSSD_LDAP_TLS_REQCERT}

ldap_schema = ${SSSD_LDAP_SCHEMA}
ldap_search_base = ${SSSD_LDAP_SEARCH_BASE}
ldap_user_search_base = ${SSSD_LDAP_USER_SEARCH_BASE}
ldap_group_search_base = ${SSSD_LDAP_GROUP_SEARCH_BASE}

ldap_user_name = ${SSSD_LDAP_USER_NAME}
ldap_user_gecos = ${SSSD_LDAP_USER_GECOS}

# Which users may log in. The default filter matches every entry, so all
# directory users are allowed; set a stricter filter to restrict access.
ldap_access_order = filter
ldap_access_filter = ${SSSD_LDAP_ACCESS_FILTER}

ldap_default_bind_dn = ${SSSD_LDAP_DEFAULT_BIND_DN}
ldap_default_authtok_type = ${SSSD_DEFAULT_AUTHTOK_TYPE}
ldap_default_authtok = ${SSSD_DEFAULT_AUTHTOK}

# Long enough for a push notification to be responded to
ldap_opt_timeout = 60

Configuring the Connection¶

The recommended way to link every container to your directory is to set the SSSD_* variables as default container environment variables in System Settings. These defaults are applied to every container created on the cluster, so authentication is configured once and inherited automatically.

In the admin UI: Settings → Default Container Environment Variables. The following keys are seeded for you — fill in the values for your environment:

Per-container overrides¶

Because these are ordinary container environment variables, an individual container can override any SSSD_* value at creation time (in the Environment Variables section of the container form, or via the API). This is useful for connecting a specific container to a different directory or test environment without changing the cluster-wide defaults.

Requirements for your directory¶

• LDAPS reachable from the cluster. Containers connect over the URIs in SSSD_LDAP_URI; those hosts must be resolvable and reachable from the container network. If you use short names like ldap1, ensure they resolve via the site's DNS (DNSMasq); otherwise use fully-qualified domain names or IPs.
• POSIX attributes on users. SSSD expects uid, uidNumber, gidNumber, homeDirectory, and cn. Active Directory installations typically need the POSIX/RFC 2307 attributes populated (or schema ad).
• Home directories are created automatically on first login by PAM (pam_mkhomedir), so the directory itself only needs to supply the homeDirectory path.

Verifying¶

SSH into any container and confirm the directory is reachable and users resolve:

# Show the rendered config (secrets included — handle with care)
sudo cat /etc/sssd/sssd.conf

# SSSD should be active
systemctl status sssd

# Look up a user that exists in your directory
getent passwd <username>
id <username>

# Clear the cache and force a fresh lookup if results look stale
sudo sss_cache -E

If getent passwd <username> returns the user, authentication and home-directory creation will work on first login.

Proxmox LDAP Realm (Optional)¶

To let container ACLs reference directory users as username@ldap, configure Proxmox to authenticate against the same directory the containers use.

DNS Configuration¶

If your SSSD_LDAP_URI uses names that only the cluster DNS resolves, point Proxmox at the same DNS server (the DNSMasq instance managed by the management software) so it can resolve them too. If you use public FQDNs this step is unnecessary.

In the Proxmox web UI: Node → System → DNS → set the DNS server to the DNSMasq IP address.

Add the LDAP Realm¶

In the Proxmox web UI: Datacenter → Permissions → Realms → Add → LDAP Server.

Under Sync Options:

All other settings remain at defaults.

Sync Users¶

After adding the realm, sync it to import users and groups:

Datacenter → Permissions → Realms → select ldap → Sync.

The management software also triggers a sync automatically when creating containers (via syncLdapRealm('ldap')) so new users are available for ACL assignment.