docs: add baseline ldap documentation

within the new account backends nav section.
2026-03-12 14:58:17 +01:00
parent 63365fb1a8
commit a70ae543cb
4 changed files with 113 additions and 11 deletions
@@ -1,14 +1,82 @@
-LDAP Support
-============
+LDAP
+====

-It is possible to manage mail user accounts with LDAP rather than with
-the option `loginAccounts <options.html#mailserver-loginaccounts>`_.
+LDAP (Lightweight Directory Access Protocol) is a protocol for accessing and
+managing a centralized directory of user and group information. It can be used
+to authenticate users and provide a single source of truth for email accounts
+and aliases across mail services.

-All related LDAP options are described in the `LDAP options section
-<options.html#mailserver-ldap>`_ and the `LDAP test
-<https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/blob/master/tests/ldap.nix>`_
-provides a getting started example.

-.. note::
-   The LDAP support can not be enabled if some accounts are also defined with ``mailserver.loginAccounts``.
+Requirements
+~~~~~~~~~~~~

+To enable the LDAP integration the following requirements must be fulfilled:
+
+- Existing LDAP service (we currently only test against OpenLDAP)
+- Bind credentials against LDAP with permissions to
+
+  - search for the acceptable set of users
+  - read the :option:`mailserver.ldap.attributes.password` attribute
+
+- Each user entry must provide attributes that can serve as
+
+  - :option:`mailserver.ldap.attributes.mail` (primary mail address)
+  - :option:`mailserver.ldap.attributes.username` (login name)
+  - :option:`mailserver.ldap.attributes.password` (login password)
+  - :option:`mailserver.ldap.attributes.uuid` (stable identifier)
+
+
+Features
+~~~~~~~~
+
+We currently have a basic feature set covering user accounts only and try to
+follow best practices to simplify maintenance.
+
+- Users authenticate with the username and password attribute
+- Maildir storage paths are constructed using the uuid attribute
+- Primary mail address read from mail attribute
+
+
+Limitations
+~~~~~~~~~~~
+
+We have various assertions in place, that prevent using LDAP together with
+other features. Most of them are not technical limitations per se, but instead
+lack configuration or validation.
+
+- Local users (:option:`mailserver.loginAccounts`) and aliases
+  (:option:`mailserver.extraVirtualAliases`) are not currently allowed with
+  :option:`mailserver.ldap.enable` enabled
+- Aliases based on LDAP attributes are currently not implemented
+- Quotas based on LDAP attributes are currently not implemented
+
+The following features will likely never be implemented, since they would
+complicate the setup significantly.
+
+- Domains based on LDAP entries (would require integration with everything we
+  already do for :option:`mailserver.domains`)
+- Use of ``homeDirectory``, ``uid``, ``gid`` LDAP attributes (we are
+  committed to a virtual setup with one vmail user/uid/gid and UUID based home
+  directories)
+
+
+Enabling LDAP support
+~~~~~~~~~~~~~~~~~~~~~
+
+Enable the LDAP integration by configuring an authenticated LDAP connection
+and how to locate all users. The bind DN must be allowed to read the configured
+password attribute, which may require additional configuration
+
+.. literalinclude:: ./ldap-basic.nix
+   :language: nix
+
+We provide sensible defaults for each attribute, that can be adapted to your
+local setup.
+
+.. literalinclude:: ./ldap-attrs.nix
+   :language: nix
+
+Refer to our `LDAP test`_ for an complete example, and see the `LDAP options`_ section for all possible settings.
+
+.. _LDAP options: options.html#mailserver-ldap
+.. _LDAP test: https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/blob/master/tests/ldap.nix