[pbs-devel] [PATCH proxmox-backup v2 11/15] docs: user-management: add section about AD realm support

[Fabian Grünbichler]

nit: the domains.cfg docs currently have:

> You can use the proxmox-backup-manager openid and proxmox-backup-manager ldap commands to manipulate this file.

in them, that might warrant adding the 'ad' command as well.

On August 16, 2023 4:47 pm, Christoph Heiss wrote:
> Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
> ---
> Changes v1 -> v2:
>   * Add sentence to explain that both LDAP- and AD-syntax can be used
>     for `bind-dn`
> 
>  docs/user-management.rst | 41 +++++++++++++++++++++++++++++++++-------
>  1 file changed, 34 insertions(+), 7 deletions(-)
> 
> diff --git a/docs/user-management.rst b/docs/user-management.rst
> index 822443f9..40bb5ac7 100644
> --- a/docs/user-management.rst
> +++ b/docs/user-management.rst
> @@ -643,15 +643,42 @@ A full list of all configuration parameters can be found at :ref:`domains.cfg`.
>    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
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +.. _user_realms_ad:
> 
> -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

stray Proxmox VE

> -in the LDAP realm configuration dialog window in the GUI and via the
> -``proxmox-backup-manager ldap create/update`` command.
> +Active Directory
> +~~~~~~~~~~~~~~~~
> +
> +Proxmox Backup Server can also utilize external Microsoft Active Directory
> +servers for user authentication.
> +To achieve this, a realm of the type ``ad`` has to be configured.
> +
> +For an Active Directory realm, the authentication domain name and the server
> +address must be specified. Most options from :ref:`_user_realms_ldap` apply to

this ref doesn't work for me because it should be :ref:`user_realms_ldap` (without the leading '_')

`make html` prints

/home/fgruenbichler/Sources/proxmox-backup/docs/user-management.rst:658: WARNING: undefined label: '_user_realms_ldap'

- maybe we could add a check for that to make such things a build error?


> +Active Directory as well, most importantly the bind credentials ``bind-dn``
> +and ``password``. This is typically required by default for Microsoft Active
> +Directory. The ``bind-dn`` can be specified either in AD-specific
> +``user at company.net`` syntax or the commen LDAP-DN syntax.
> +
> +The authentication domain name must only be specified if anonymous bind is
> +requested. If bind credentials are given, the domain name is automatically
> +inferred from the bind users' base domain, as reported by the Active Directory
> +server.
> +
> +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 Active
> +  Directory 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/AD realms
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +It is possible to automatically sync users for LDAP and AD-based realms, rather
> +than having to add them to Proxmox VE manually. Synchronization options can be

that ends up being propagated here ;)

> +set in the LDAP realm configuration dialog window in the GUI and via the
> +``proxmox-backup-manager ldap/ad create/update`` command.

not sure I like that style, IMHO a command should be in a format that
allows copying if possible. in this case, we could just refer to

with the ``proxmox-backup-manager ldap`` and ``proxmox-backup-manager
ad`` commands

if I copy and paste that, I get the usage list with the relevant sub
commands and parameters.

>  User synchronization can started in the GUI at

missing 'be'

>  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.
> +be started via the ``proxmox-backup-manager ldap/ad sync`` command.

same here, IMHO splitting the two commands makes it more user friendly.

> --
> 2.41.0
> 
> 
> 
> _______________________________________________
> pbs-devel mailing list
> pbs-devel at lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel
> 
> 
>