[pbs-devel] [PATCH proxmox-backup 12/17] docs: add documentation for LDAP realms
Lukas Wagner
l.wagner at proxmox.com
Tue Jan 3 15:23:03 CET 2023
Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
---
docs/command-syntax.rst | 1 +
docs/configuration-files.rst | 4 ++-
docs/user-management.rst | 58 ++++++++++++++++++++++++++++++++++++
www/OnlineHelpInfo.js | 8 +++++
4 files changed, 70 insertions(+), 1 deletion(-)
diff --git a/docs/command-syntax.rst b/docs/command-syntax.rst
index b2ea330a..d9bb148f 100644
--- a/docs/command-syntax.rst
+++ b/docs/command-syntax.rst
@@ -23,6 +23,7 @@ The following commands are available in an interactive restore shell:
.. include:: proxmox-backup-client/catalog-shell-synopsis.rst
``proxmox-backup-manager``
--------------------------
diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst
index 12a4a54e..0540d0b1 100644
--- a/docs/configuration-files.rst
+++ b/docs/configuration-files.rst
@@ -36,8 +36,10 @@ Options
.. include:: config/datastore/config.rst
+.. _domains.cfg:
+
``domains.cfg``
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
File Format
^^^^^^^^^^^
diff --git a/docs/user-management.rst b/docs/user-management.rst
index b739121d..faaf183d 100644
--- a/docs/user-management.rst
+++ b/docs/user-management.rst
@@ -25,6 +25,8 @@ choose the realm when you add a new user. Possible realms are:
:openid: OpenID Connect server. Users can authenticate against an external
OpenID Connect server.
+:ldap: LDAP server. Users can authenticate against external LDAP servers.
+
After installation, there is a single user, ``root at pam``, which corresponds to
the Unix superuser. User configuration information is stored in the file
``/etc/proxmox-backup/user.cfg``. You can use the ``proxmox-backup-manager``
@@ -560,3 +562,59 @@ Two-factor authentication is only implemented for the web-interface. You should
use :ref:`API Tokens <user_tokens>` for all other use cases, especially
non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE
as a storage).
+
+
+Authentication Realms
+---------------------
+
+.. _user_realms_ldap:
+
+LDAP
+~~~~
+
+Proxmox Backup Server can utilize external LDAP servers for user authentication. To achieve this,
+a realm of the type ``ldap`` has to be configured.
+
+In LDAP, users are uniquely identified
+by their domain (``dn``). For instance, in the following LDIF dataset, the user ``user1`` has the
+unique domain ``uid=user1,ou=People,dc=ldap-test,dc=com``:
+
+
+.. code-block:: console
+
+ # user1 of People at ldap-test.com
+ dn: uid=user1,ou=People,dc=ldap-test,dc=com
+ objectClass: top
+ objectClass: person
+ objectClass: organizationalPerson
+ objectClass: inetOrgPerson
+ uid: user1
+ cn: Test User 1
+ sn: Testers
+ description: This is the first test user.
+
+In in similar manner, Proxmox Backup Server uses user identifiers (``userid``) to uniquely identify users.
+Thus, it is necessary to establish a mapping between PBS's ``userid`` and LDAP's ``dn``.
+This mapping is established by the ``user-attr`` configuration parameter - it contains the name of the
+LDAP attribute containing a valid PBS user identifier.
+
+For the example above, setting ``user-attr`` to ``uid`` will have the effect that the user ``user1@<realm-name>`` will be mapped to the LDAP entity
+``uid=user1,ou=People,dc=ldap-test,dc=com``. On user login, PBS will perform a `subtree search` under the configured Base Domain (``base-dn``) to query
+the user's ``dn``. Once the ``dn`` is known, an LDAP bind operation is performed to authenticate the user against the LDAP server.
+
+As not all LDAP servers allow `anonymous` search operations, it is possible to configure a bind domain (``bind-dn``) and a bind password (``password``).
+If set, PBS will bind to the LDAP server using these credentials before performing any search operations.
+
+A full list of all configuration parameters can be found at :ref:`domains.cfg`.
+
+.. note:: In order to allow a particular user to authenticate using the LDAP server, you must also add them as a user of that realm in Proxmox Backup Server.
+ This can be carried out automatically with syncing.
+
+User Synchronization in LDAP realms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to automatically sync users for LDAP-based realms, rather than having to add them to Proxmox VE manually.
+Synchronization options can be set in the LDAP realm configuration dialog window in the GUI and via the ``proxmox-backup-manager ldap create/update`` command.
+User synchronization can started in the GUI at Configuration > Access Control > Realms by selecting a realm and pressing the `Sync` button. In the sync dialog,
+some of the default options set in the realm configuration can be overridden. Alternatively,
+user synchronization can also be started via the ``proxmox-backup-manager ldap sync`` command.
\ No newline at end of file
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index ac455450..704038b4 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -31,6 +31,10 @@ const proxmoxOnlineHelpInfo = {
"link": "/docs/calendarevents.html#calendar-event-scheduling",
"title": "Calendar Events"
},
+ "domains-cfg": {
+ "link": "/docs/configuration-files.html#domains-cfg",
+ "title": "``domains.cfg``"
+ },
"pxar-format": {
"link": "/docs/file-formats.html#pxar-format",
"title": "Proxmox File Archive Format (``.pxar``)"
@@ -334,5 +338,9 @@ const proxmoxOnlineHelpInfo = {
"user-tfa-setup-recovery-keys": {
"link": "/docs/user-management.html#user-tfa-setup-recovery-keys",
"title": "Recovery Keys"
+ },
+ "user-realms-ldap": {
+ "link": "/docs/user-management.html#user-realms-ldap",
+ "title": "LDAP"
}
};
--
2.30.2
More information about the pbs-devel
mailing list