From 63e003adce0a170acad6cd68afda90bfc428e641 Mon Sep 17 00:00:00 2001 From: TheWitness Date: Mon, 28 Sep 2026 12:44:01 -0400 Subject: [PATCH 1/2] 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. --- Settings-Auth-LDAP.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/Settings-Auth-LDAP.md b/Settings-Auth-LDAP.md index 1394a770..74a1ac20 100644 --- a/Settings-Auth-LDAP.md +++ b/Settings-Auth-LDAP.md @@ -199,6 +199,40 @@ 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. + +Regardless of the configured _Mode_, 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: + +- _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. Do not use +_No Searching_ when locating the DN would otherwise require the user's +credentials. + +Finally, configure only a single LDAP server (for example a load balancer VIP) +for OTP/MFA. The _Server(s)_ field accepts a space-delimited list and fails +over from left to right; if the first server consumes the one-time password and +then returns an error, Cacti will re-attempt the bind against the next server +with an already-spent code, which will fail. + ### Certificate verification When using LDAPS or STARTTLS, the Cacti server (as an LDAP client) must trust From 29826d77fc851e09a9dc3d2307f5fd9a5ae60e43 Mon Sep 17 00:00:00 2001 From: TheWitness Date: Mon, 28 Sep 2026 13:45:33 -0400 Subject: [PATCH 2/2] docs(auth): recommend resilient DNS load balancer for LDAP OTP; qualify single-bind for failover; clarify No Searching --- Settings-Auth-LDAP.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/Settings-Auth-LDAP.md b/Settings-Auth-LDAP.md index 74a1ac20..6e69452f 100644 --- a/Settings-Auth-LDAP.md +++ b/Settings-Auth-LDAP.md @@ -206,9 +206,10 @@ Cacti supports directories where users authenticate with a One-Time Password must be chosen so that the user's single-use credential is presented to the directory only once. -Regardless of the configured _Mode_, Cacti binds the user's password exactly +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: +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. @@ -223,15 +224,20 @@ 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. Do not use -_No Searching_ when locating the DN would otherwise require the user's -credentials. - -Finally, configure only a single LDAP server (for example a load balancer VIP) -for OTP/MFA. The _Server(s)_ field accepts a space-delimited list and fails -over from left to right; if the first server consumes the one-time password and -then returns an error, Cacti will re-attempt the bind against the next server -with an already-spent code, which will fail. +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