From 9090b1b5112f3bd45148190dda6606521af31c13 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Thu, 1 Oct 2026 01:27:55 -0400
Subject: [PATCH] docs(auth): prefer the down-level UserBindTemplate; warn on
 UPN templates (I1)

---
 .../ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs  | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs b/ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs
index 95a2527..ec397bf 100644
--- a/ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs
+++ b/ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs
@@ -42,8 +42,14 @@ public sealed record LdapOptions
 
     /// <summary>
     /// <see cref="LdapBindMode.User"/> only: the simple-bind identity, with <c>{0}</c> replaced by the
-    /// normalised login name — e.g. <c>{0}@example.com</c> (UPN) or <c>EXAMPLE\{0}</c>. Must contain
-    /// <c>{0}</c> exactly once.
+    /// normalised login name. Must contain <c>{0}</c> exactly once.
+    /// <para>
+    /// Prefer the down-level form <c>EXAMPLE\{0}</c>: it maps exactly to the <c>sAMAccountName</c> the
+    /// group search uses, so the account that binds is the account whose groups are read. A UPN
+    /// template (<c>{0}@example.com</c>) is only correct where every account's UPN prefix equals its
+    /// <c>sAMAccountName</c> — AD resolves a UPN bind against the explicit <c>userPrincipalName</c>, so
+    /// a mismatch can fail sign-in or bind a different account than the one whose groups are read.
+    /// </para>
     /// </summary>
     public string UserBindTemplate { get; init; } = "";