docs: add baseline ldap documentation

within the new account backends nav section.

docs/index.rst

@@ -21,13 +21,18 @@ Welcome to NixOS Mailserver's documentation!
    options
    migrations
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Account backends
+
+   ldap
+
 .. toctree::
    :maxdepth: 1
    :caption: Features
 
    dkim
    fts
-   ldap
    srs
 
 .. toctree::

docs/ldap-attrs.nix

@@ -0,0 +1,12 @@
+{
+  mailserver = {
+    ldap = {
+      attributes = {
+        uuid = "entryUUID";
+        username = "uid";
+        password = "userPassword";
+        mail = "mail";
+      };
+    };
+  };
+}

docs/ldap-basic.nix

@@ -0,0 +1,17 @@
+{
+  mailserver = {
+    ldap = {
+      enable = true;
+      uris = [
+        "ldaps://ldap1.example.com"
+        "ldaps://ldap2.example.com"
+      ];
+      bind = {
+        dn = "cn=mail,dc=example=dc=com";
+        passwordFile = "/run/keys/ldap-bind-pw";
+      };
+      base = "ou=users,dc=example,dc=com";
+      scope = "one";
+    };
+  };
+}

docs/ldap.rst

@@ -1,14 +1,82 @@
-LDAP Support
+LDAP
-============
+====
 
-It is possible to manage mail user accounts with LDAP rather than with
+LDAP (Lightweight Directory Access Protocol) is a protocol for accessing and
-the option `loginAccounts <options.html#mailserver-loginaccounts>`_.
+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::
+Requirements
-   The LDAP support can not be enabled if some accounts are also defined with ``mailserver.loginAccounts``.
+~~~~~~~~~~~~
 
+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