Skip to content

Explicit credential authentication

Where principal initialization trusts whatever identity the host process or Forms cookie already provides, this operation instead validates a username, domain, and password that the caller supplies directly. It performs a Win32 logon against those credentials, converts the resulting token into a managed Windows principal, and — only on success — impersonates the authenticated identity so subsequent work runs in that user's security context.

Field Value
Operation ID OP-002
Trigger Caller sets UserName / Domain / Password and invokes Authenticate()
Inputs Principal credential fields
Outputs Boolean success flag, updated thread principal, impersonation context on success
Primary components clsSecurityPrincipal.Authenticate, clsSecurityPrincipal.GetToken
Entry point SAIF.Framework.Security\clsSecurityPrincipal.vb

Steps

  1. Each credential property setter (UserName, Domain, Password) updates its stored value and immediately calls Logout() first, so a new authentication attempt never starts on top of stale state — this enforces BR-006.
  2. If a prior impersonation existed: Logout() undoes it before the setter returns, so the credential change takes effect on a clean principal.
  3. Authenticate() calls GetToken(UserName, Domain, Password) to obtain a Windows access token for the supplied credentials.
  4. GetToken() invokes Win32 LogonUser, duplicates the token it returns, closes the original handle, and throws a could not logon error if the logon call fails or the resulting token handle is invalid.
  5. Authenticate() wraps that call in a try/catch: any token-acquisition failure is caught, and the method returns False immediately without touching the current thread principal.
  6. When the token is acquired successfully, Authenticate() builds a WindowsIdentity and WindowsPrincipal from it, assigns them to Thread.CurrentThread.CurrentPrincipal, records the identity as the principal's new base identity, impersonates it, and marks the principal authenticated — all as one atomic outcome.
  7. If the method returns True: the caller now holds an authenticated, impersonated principal that can flow directly into Programmatic authorization checks.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Authenticate called]) --> Reset[Credential setters clear prior state]
    Reset --> Token[Acquire Win32 token]
    Token --> Success{Token acquired?}
    Success -->|No| EndErr([Return False])
    Success -->|Yes| Principal[Create Windows principal]
    Principal --> Imp[Impersonate identity]
    Imp --> EndOk([Return True])

Failure and edge-case behavior

  • Invalid credentials cause GetToken() to throw, which Authenticate() catches and converts into a False return rather than propagating the exception.
  • There is no partial-success path: principal replacement and impersonation always happen together, and a caller only ever sees True after both steps have completed.

Sources

  • SAIF.Framework.Security\clsSecurityPrincipal.vb