docs(auth): document LDAP OTP/MFA single-bind behavior and configuration (#231)

* docs(auth): document LDAP OTP/MFA single-bind behavior and configuration

Adds a One-Time Passwords (OTP / MFA) note to the LDAP authentication page
explaining that Cacti binds the user's password only once, that the DN
lookup never uses the user's password, and that OTP/MFA deployments should
use Specific Searching with a service account and a single server.

* docs(auth): recommend resilient DNS load balancer for LDAP OTP; qualify single-bind for failover; clarify No Searching
This commit is contained in:
TheWitness authored and GitHub committed 2026-09-30 16:47:01 -04:00
1 parent 57b8088e13
commit 5b2763b8f6
1 file changed
+40
+40
View File
@@ -199,6 +199,46 @@ out in lower-case (`fullname`).
## A few notes
### One-Time Passwords (OTP / MFA)
Cacti supports directories where users authenticate with a One-Time Password
(OTP) or another Multi-Factor Authentication (MFA) token, but the LDAP _Mode_
must be chosen so that the user's single-use credential is presented to the
directory only once.
On a single-server authentication path, Cacti binds the user's password exactly
once, during the final authentication step. The Distinguished Name (DN) lookup
that precedes it never uses the user's password (see the note on multi-server
failover below):
- _No Searching_ performs no bind during the lookup (the DN is built from the
template), then binds once as the user.
- _Anonymous Searching_ binds anonymously to locate the DN, then binds once as
the user.
- _Specific Searching_ binds with the service account to locate the DN, then
binds once as the user.
Group membership checks, when enabled, reuse the connection that was already
bound with the user's credential and do not perform a second bind.
Because Active Directory refuses anonymous searches by default, an OTP/MFA
deployment on AD should use _Specific Searching_ with a dedicated service
account. The service account performs the directory search so that the user's
one-time code is preserved for the single authentication bind. _No Searching_
is also safe for OTP when the DN template alone identifies the user, since it
performs no directory lookup; choose _Specific_ or _Anonymous Searching_ only
when a lookup is actually required to resolve the DN.
Finally, for OTP/MFA do not use the _Server(s)_ space-delimited multi-server
list. That field fails over from left to right, so if the first server consumes
the one-time password and then returns an error, Cacti re-attempts the bind
against the next server with an already-spent code, which will fail. Instead,
point the _Server(s)_ field at a single, resilient DNS name fronted by a DNS
load balancer (VIP). Treat that DNS/load-balancer layer as the resilient,
highly-available entry point: it handles backend failover transparently, so
Cacti only ever performs one authentication bind per login and the single-use
code is never replayed.
### Certificate verification
When using LDAPS or STARTTLS, the Cacti server (as an LDAP client) must trust