using System.Net.Security;
namespace ZB.MOM.WW.Auth.Abstractions.Ldap;
public enum LdapTransport { Ldaps, StartTls, None }
/// How authenticates a sign-in.
public enum LdapBindMode
{
/// Bind as the service account, search for the user, re-bind as the user (0.3.0 behaviour).
ServiceAccount,
///
/// Bind as the signing-in user (identity built from );
/// a successful bind authenticates them, and the same connection reads their own entry for groups.
/// No service account is used.
///
User,
}
public sealed record LdapOptions
{
public bool Enabled { get; init; } = true;
public string Server { get; init; } = "localhost";
public int Port { get; init; } = 3893;
public LdapTransport Transport { get; init; } = LdapTransport.Ldaps;
public bool AllowInsecure { get; init; }
public string SearchBase { get; init; } = "";
public string ServiceAccountDn { get; init; } = "";
public string ServiceAccountPassword { get; init; } = "";
public string UserNameAttribute { get; init; } = "cn";
public string DisplayNameAttribute { get; init; } = "cn";
public string GroupAttribute { get; init; } = "memberOf";
public int ConnectionTimeoutMs { get; init; } = 10_000;
///
/// Selects the authentication flow. (the default) is the
/// 0.3.0 bind-then-search-then-bind flow; binds as the user and needs
/// no / .
///
public LdapBindMode BindMode { get; init; } = LdapBindMode.ServiceAccount;
///
/// only: the simple-bind identity, with {0} replaced by the
/// normalised login name. Must contain {0} exactly once.
///
/// Prefer the down-level form EXAMPLE\{0}: it maps exactly to the sAMAccountName the
/// group search uses. A UPN template ({0}@example.com) only signs in accounts whose UPN
/// prefix equals their sAMAccountName — AD resolves a UPN bind against the explicit
/// userPrincipalName, so it can bind a different account than the one the search finds.
///
///
/// Since 0.4.4 the service proves the entry it reads is the account that bound, and refuses the
/// sign-in () otherwise. It asks the directory
/// (RFC 4532 "Who am I?") and compares the answer with the entry's DN or, for AD's
/// u:DOMAIN\name answer, its sAMAccountName. A server without Who-am-I (e.g. GLAuth)
/// is only supported with a DN template (containing =), which must produce the entry's DN
/// exactly as the search reports it; {0} is RFC 4514-escaped in a DN template.
///
///
public string UserBindTemplate { get; init; } = "";
///
/// only: when (default) a login typed as
/// DOMAIN\name or name@suffix is reduced to name; when
/// such input is refused as bad credentials without contacting the directory.
///
public bool AcceptDomainQualifiedNames { get; init; } = true;
///
/// Ordered fallback LDAP endpoints tried when the primary (and any earlier fallback)
/// fails with a system-side error (connect/TLS, service-account bind, or search).
/// Each entry is "host" (adopts ) or "host:port".
/// Empty (the default) disables failover entirely — single-endpoint behavior is
/// unchanged. The TLS validation policy (
/// / ) applies to every endpoint. Endpoint preference is
/// sticky: the service keeps using the last endpoint that answered until it fails.
///
public IReadOnlyList FallbackServers { get; init; } = Array.Empty();
///
/// Optional hook to harden (or, in dev, relax) TLS server-certificate validation for the
/// / transports. When
/// (the default) the LDAP client validates the server certificate against
/// the OS trust store — it does not blind-accept. Supply a callback to pin a CA, validate
/// the SAN against , or otherwise tighten validation. This is a code-only seam
/// (not bound from configuration) and takes precedence over .
///
public RemoteCertificateValidationCallback? ServerCertificateValidationCallback { get; init; }
}
public enum LdapAuthFailure { BadCredentials, UserNotFound, AmbiguousUser, GroupLookupFailed, ServiceAccountBindFailed, Disabled }
public sealed record LdapAuthResult(bool Succeeded, string Username, string DisplayName, IReadOnlyList Groups, LdapAuthFailure? Failure)
{
public static LdapAuthResult Success(string username, string displayName, IReadOnlyList groups) => new(true, username, displayName, groups, null);
public static LdapAuthResult Fail(LdapAuthFailure failure) => new(false, "", "", Array.Empty(), failure);
}
public interface ILdapAuthService
{
///
/// Authenticates against the directory by bind-then-search and
/// returns the outcome, including the resolved display name and group memberships on success.
///
/// The login name to authenticate.
/// The credential to bind with.
/// A token to request cancellation of the operation.
/// The authentication result.
///
/// The cancellation token is observed at entry only. Implementations backed by synchronous
/// LDAP clients cannot abort an in-flight bind or search once it has been dispatched, so full
/// cooperative cancellation is not guaranteed mid-call: a request that has already reached the
/// directory will run to completion (subject to the configured connection timeout) even if the
/// token is cancelled.
///
Task AuthenticateAsync(string username, string password, CancellationToken ct);
}
/// Outcome of a passwordless call.
public enum LdapGroupLookupStatus
{
/// Exactly one entry matched; is its group set (may be empty).
Found,
/// A healthy directory answered and no entry matched the name — the account was deleted or renamed.
UserNotFound,
/// Exactly one entry matched but the directory marks it disabled (AD userAccountControl ACCOUNTDISABLE).
UserDisabled,
/// Two or more entries matched; no group set can be attributed to the name.
AmbiguousUser,
///
/// No endpoint gave an answer: connect/TLS, the service-account bind or the search failed on every
/// endpoint (primary and ). Says nothing about the user.
///
DirectoryUnavailable,
///
/// The configuration cannot search without the user's password: is
/// (there is no service account), no
/// is configured, or the registered provider does not implement lookup.
///
NotSupported,
/// is ; the network was not touched.
ProviderDisabled,
}
///
/// Result of a passwordless group lookup. , and
/// are populated only for ; for every other
/// status they are empty.
///
public sealed record LdapGroupLookupResult(
LdapGroupLookupStatus Status,
string Username,
string DisplayName,
IReadOnlyList Groups)
{
/// when is .
public bool IsFound => Status == LdapGroupLookupStatus.Found;
public static LdapGroupLookupResult Found(string username, string displayName, IReadOnlyList groups)
=> new(LdapGroupLookupStatus.Found, username, displayName, groups);
/// Any non- outcome, with empty identity fields.
public static LdapGroupLookupResult Of(LdapGroupLookupStatus status)
=> status == LdapGroupLookupStatus.Found
? throw new ArgumentException("Use Found(...) for a successful lookup.", nameof(status))
: new(status, "", "", Array.Empty());
}
///
/// Passwordless directory group lookup (since 0.5.0): re-reads a known user's group membership without
/// their credentials, e.g. to refresh an active session's roles when the directory changes.
///
public interface ILdapGroupLookup
{
///
/// Binds as the configured service account, finds by
/// under , and returns the
/// same group set (and canonical username / display name)
/// would return for that user in mode.
///
///
/// Never throws except for cancellation observed at entry; every fault maps to a
/// . Endpoint failover, timeouts and TLS policy are the same as
/// . Unlike authentication, a
/// result may carry zero groups (sign-in would refuse such a user); the caller decides what that means.
///
Task GetUserGroupsAsync(string username, CancellationToken ct);
}