Files
lmxopcua/src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapOptions.cs
T
Joseph Doherty c996b462c4 fix(security): pass FallbackServers/BindMode/UserBindTemplate/AcceptDomainQualifiedNames to the LDAP library, inject its logger (#913)
- LdapOptions gains the four properties (library defaults) and ToLibraryOptions()
  projects them; before this the AdminUI had no DC failover and the keys were
  silently ignored.
- OtOpcUaLdapAuthService builds the library service with ILogger<LdapAuthService>
  from DI, so failover Warnings, the sticky-preference line and stage diagnostics
  reach the log.
- LdapOptionsValidator ports only the library's FallbackServers parse rule and the
  BindMode=User -> UserBindTemplate {0}-exactly-once rule. ServiceAccountDn is NOT
  required: DEV boots on the empty default (plan review B2).
- Fix stale comments: no direct-bind path exists; code default server is localhost.
- Tests: two-way reflection completeness guard over the library LdapOptions
  (allow-list: ServerCertificateValidationCallback), JSON + env binding of the new
  keys, validator rules, DEV-shaped boot, and a DI-built service against two closed
  loopback ports proving library Warnings for primary AND fallback reach the log.

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
2026-11-17 11:18:18 -05:00

175 lines
9.7 KiB
C#

using ZB.MOM.WW.Auth.Abstractions.Ldap;
using LibLdapOptions = ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions;
namespace ZB.MOM.WW.OtOpcUa.Security.Ldap;
/// <summary>
/// LDAP + role-mapping configuration for the Admin UI. Bound from <c>appsettings.json</c>
/// <c>Security:Ldap</c> section. The code defaults are <c>localhost:3893</c>, plaintext
/// (<see cref="LdapTransport.None"/>) and search base <c>dc=zb,dc=local</c> — the GLAuth
/// shape; the shipped overlays and service environment point it at a real directory. See
/// <c>docs/security.md</c> §"LDAP bind flow" and <c>docs/Configuration.md</c>
/// §"<c>Security:Ldap</c>" for setup details.
/// </summary>
/// <remarks>
/// Carries both the wire fields the shared <c>ZB.MOM.WW.Auth.Ldap</c> directory client needs
/// (<see cref="Server"/>/<see cref="Port"/>/<see cref="Transport"/>/…) AND the app-only concerns
/// the shared library has no notion of (<see cref="Enabled"/> master switch,
/// <see cref="DevStubMode"/> dev bypass, <see cref="GroupToRole"/> appsettings role baseline).
/// The app wrapper (<c>OtOpcUaLdapAuthService</c>) projects this onto the library's
/// <see cref="LibLdapOptions"/> at construction; see <see cref="ToLibraryOptions"/>.
/// </remarks>
public sealed class LdapOptions
{
public const string SectionName = "Security:Ldap";
/// <summary>Gets or sets a value indicating whether LDAP authentication is enabled.</summary>
public bool Enabled { get; set; } = true;
/// <summary>Gets or sets the LDAP server hostname.</summary>
public string Server { get; set; } = "localhost";
/// <summary>Gets or sets the LDAP server port.</summary>
public int Port { get; set; } = 3893;
/// <summary>
/// Transport security for the LDAP connection — <see cref="LdapTransport.Ldaps"/> (implicit
/// TLS), <see cref="LdapTransport.StartTls"/> (upgrade), or <see cref="LdapTransport.None"/>
/// (plaintext, dev/test only — requires <see cref="AllowInsecure"/>). Replaces the former
/// <c>UseTls</c> bool: <c>true</c>→<see cref="LdapTransport.Ldaps"/>,
/// <c>false</c>→<see cref="LdapTransport.None"/>.
/// </summary>
public LdapTransport Transport { get; set; } = LdapTransport.None;
/// <summary>Dev-only escape hatch — must be <c>false</c> in production. Maps to the shared
/// library's <see cref="LibLdapOptions.AllowInsecure"/> (renamed from <c>AllowInsecureLdap</c>).</summary>
public bool AllowInsecure { get; set; }
/// <summary>
/// Dev-only stub: when <c>true</c>, <see cref="OtOpcUaLdapAuthService"/> bypasses the real LDAP
/// bind and accepts any non-empty username/password, returning a single Administrator role
/// so the operator can navigate the full Admin UI. MUST be <c>false</c> in production.
/// </summary>
public bool DevStubMode { get; set; }
/// <summary>Gets or sets the LDAP search base DN.</summary>
public string SearchBase { get; set; } = "dc=zb,dc=local";
/// <summary>
/// Service-account DN used for search-then-bind in <see cref="LdapBindMode.ServiceAccount"/>
/// mode. There is no direct-bind fallback: when empty, the shared library binds with an empty
/// DN (an anonymous bind), which works against GLAuth's anonymous search but not against
/// Active Directory. Not required at startup (DEV boots on the empty default — lmxopcua#913);
/// unused in <see cref="LdapBindMode.User"/> mode.
/// </summary>
public string ServiceAccountDn { get; set; } = string.Empty;
/// <summary>Gets or sets the service account password for LDAP authentication.</summary>
public string ServiceAccountPassword { get; set; } = string.Empty;
/// <summary>Gets or sets the LDAP attribute name for user display name.</summary>
public string DisplayNameAttribute { get; set; } = "cn";
/// <summary>Gets or sets the LDAP attribute name for group membership.</summary>
public string GroupAttribute { get; set; } = "memberOf";
/// <summary>
/// Attribute the service-account search matches the login name against to resolve the
/// user's DN. <c>cn</c> for GLAuth (the dev default); set <c>sAMAccountName</c> for
/// Active Directory.
/// </summary>
public string UserNameAttribute { get; set; } = "cn";
/// <summary>
/// Maps LDAP group name → Admin role. Group match is case-insensitive. A user gets every
/// role whose source group is in their membership list. Values are the canonical control-plane
/// roles. Example dev mapping:
/// <code>"ReadOnly":"Viewer","ReadWrite":"Designer","AlarmAck":"Administrator"</code>
/// </summary>
public Dictionary<string, string> GroupToRole { get; set; } = new(StringComparer.OrdinalIgnoreCase);
/// <summary>
/// Bounds (in milliseconds) the shared-library directory client's socket connect AND each
/// per-operation search inside a single bind flow. Projected into the library's
/// <see cref="LibLdapOptions.ConnectionTimeoutMs"/> via <see cref="ToLibraryOptions"/>. The
/// default (10000) matches the library default, so behaviour is unchanged unless configured.
/// </summary>
/// <remarks>
/// This is now the ONLY directory-outage bound. Its former backstops — <c>AuthTimeoutMs</c>,
/// <c>MaxConcurrentAuthentications</c>, <c>OutageFailureThreshold</c> and
/// <c>OutageCooldownSeconds</c> — were removed with <c>LdapOpcUaUserAuthenticator</c>
/// (see the note on this type). They existed because an LDAP bind ran inline on OPC UA session
/// activation, under a SessionManager-wide lock; nothing on the remaining AdminUI login path has
/// that property, so they had no consumer left. Setting any of them in configuration is now
/// silently ignored rather than an error, which is how options binding treats unknown keys.
/// </remarks>
public int ConnectionTimeoutMs { get; set; } = 10_000;
/// <summary>
/// Ordered fallback LDAP endpoints (e.g. a second domain controller), tried when the primary
/// fails system-side (connect/TLS, service-account bind, or search). Each entry is
/// <c>"host"</c> (adopts <see cref="Port"/>) or <c>"host:port"</c>; validated at startup.
/// Empty (the default) disables failover. Endpoint preference is sticky. Projected into the
/// library's <see cref="LibLdapOptions.FallbackServers"/>.
/// </summary>
public List<string> FallbackServers { get; set; } = [];
/// <summary>
/// Selects the authentication flow: <see cref="LdapBindMode.ServiceAccount"/> (default —
/// bind as the service account, search for the user, re-bind as the user) or
/// <see cref="LdapBindMode.User"/> (bind as the signing-in user via
/// <see cref="UserBindTemplate"/>; no service account). Projected into the library's
/// <see cref="LibLdapOptions.BindMode"/>.
/// </summary>
public LdapBindMode BindMode { get; set; } = LdapBindMode.ServiceAccount;
/// <summary>
/// <see cref="LdapBindMode.User"/> only: the simple-bind identity with <c>{0}</c> replaced by
/// the normalised login name — prefer the down-level form <c>DOMAIN\{0}</c>. Must contain
/// <c>{0}</c> exactly once when <see cref="BindMode"/> is <see cref="LdapBindMode.User"/>
/// (validated at startup).
/// </summary>
public string UserBindTemplate { get; set; } = string.Empty;
/// <summary>
/// <see cref="LdapBindMode.User"/> only: when <c>true</c> (default) a login typed as
/// <c>DOMAIN\name</c> or <c>name@suffix</c> is reduced to <c>name</c>; when <c>false</c> such
/// input is refused. Has no effect in <see cref="LdapBindMode.ServiceAccount"/> mode — there,
/// users type the bare login name (<c>sAMAccountName</c> on AD).
/// </summary>
public bool AcceptDomainQualifiedNames { get; set; } = true;
/// <summary>
/// Projects the wire fields onto the shared <c>ZB.MOM.WW.Auth.Ldap</c>
/// <see cref="LibLdapOptions"/> the directory client consumes. Every settable library property
/// must be mapped here or allow-listed in <c>LdapOptionsProjectionCompletenessTests</c> — a
/// dropped property (as <c>FallbackServers</c>/<c>BindMode</c> once were, lmxopcua#913) is
/// silently ignored config. App-only concerns
/// (<see cref="DevStubMode"/>, <see cref="GroupToRole"/>) have no library counterpart and are
/// handled by the app wrapper around the library service; <see cref="Enabled"/> is carried
/// through so the library's own feature gate stays consistent with the app master switch.
/// </summary>
/// <returns>The projected <see cref="LibLdapOptions"/> for the shared LDAP client library.</returns>
public LibLdapOptions ToLibraryOptions() => new()
{
Enabled = Enabled,
Server = Server,
Port = Port,
Transport = Transport,
AllowInsecure = AllowInsecure,
SearchBase = SearchBase,
ServiceAccountDn = ServiceAccountDn,
ServiceAccountPassword = ServiceAccountPassword,
UserNameAttribute = UserNameAttribute,
DisplayNameAttribute = DisplayNameAttribute,
GroupAttribute = GroupAttribute,
ConnectionTimeoutMs = ConnectionTimeoutMs,
FallbackServers = [.. FallbackServers],
BindMode = BindMode,
UserBindTemplate = UserBindTemplate,
AcceptDomainQualifiedNames = AcceptDomainQualifiedNames,
// ServerCertificateValidationCallback is intentionally NOT mapped: it is a code-only seam
// in the library (not config-bindable). The completeness test allow-lists it.
};
}