docs(auth): clarify LDAP OTP/MFA single-bind and service-account guidance (#8090)

* docs(auth): clarify LDAP OTP/MFA single-bind and service-account guidance

Adds guidance to the LDAP Mode and Server(s) provider descriptions that
Cacti binds the user's password only once (during final authentication),
so One-Time Password (OTP/MFA) logins should use Specific Searching with a
service account (or Anonymous Searching where permitted) and a single
server, since multi-server failover would re-attempt the bind with an
already-consumed one-time password.

* docs(auth): recommend resilient DNS load balancer for LDAP OTP; discourage space-delimited multi-server list; clarify No Searching
This commit is contained in:
TheWitness authored and GitHub committed 2026-09-28 15:21:40 -04:00
1 parent 46908e350b
commit 5fd5d674cf
1 file changed
+2 -2
+2 -2
View File
@@ -309,7 +309,7 @@ function provider_edit() : void {
],
'server' => [
'friendly_name' => __('Server(s)'),
'description' => __('A space delimited list of DNS hostnames or IP address of for valid LDAP servers. Cacti will attempt to use the LDAP servers from left to right to authenticate a user.'),
'description' => __('A space delimited list of DNS hostnames or IP addresses for valid LDAP servers. Cacti will attempt to use the LDAP servers from left to right to authenticate a user.<br><br>For One-Time Password (OTP/MFA) logins, do not use a space delimited multi-server list. On a failed bind Cacti advances to the next server and re-binds with the same credentials, and the already-consumed one-time code will be rejected. Instead enter a single, resilient DNS name fronted by a DNS load balancer (VIP) so that server failover is handled below Cacti and only one authentication bind is ever performed.'),
'method' => 'textbox',
'value' => '|arg1:server|',
'default' => '',
@@ -384,7 +384,7 @@ function provider_edit() : void {
],
'mode' => [
'friendly_name' => __('Mode'),
'description' => __('Mode which cacti will attempt to authenticate against the LDAP server.<blockquote><i>No Searching</i> - No Distinguished Name (DN) searching occurs, just attempt to bind with the provided Distinguished Name (DN) format.<br><br><i>Anonymous Searching</i> - Attempts to search for username against LDAP directory via anonymous binding to locate the users Distinguished Name (DN).<br><br><i>Specific Searching</i> - Attempts search for username against LDAP directory via Specific Distinguished Name (DN) and Specific Password for binding to locate the users Distinguished Name (DN).'),
'description' => __('Mode which cacti will attempt to authenticate against the LDAP server.<blockquote><i>No Searching</i> - No Distinguished Name (DN) searching occurs, just attempt to bind with the provided Distinguished Name (DN) format.<br><br><i>Anonymous Searching</i> - Attempts to search for username against LDAP directory via anonymous binding to locate the users Distinguished Name (DN).<br><br><i>Specific Searching</i> - Attempts search for username against LDAP directory via Specific Distinguished Name (DN) and Specific Password for binding to locate the users Distinguished Name (DN).<br><br><i>One-Time Passwords (OTP/MFA)</i> - Cacti binds the user password only once, during final authentication. <i>No Searching</i> performs no directory lookup and binds directly using the Distinguished Name (DN) template, so it is safe for OTP when the DN template alone identifies the user. When a directory lookup is required to resolve the DN, use <i>Specific Searching</i> with a dedicated service account (or <i>Anonymous Searching</i> where the directory permits it) so the lookup never consumes the single-use code. For resilient OTP deployments use a single DNS load balancer name in the Server(s) field rather than a space delimited multi-server list, which would re-attempt the bind with an already-consumed one-time password.'),
'method' => 'drop_array',
'value' => '|arg1:mode|',
'array' => $ldap_modes