Skip to content

SAIF.Framework.SecurityModule operations and processes

This page is the operation catalog and cross-operation hub for this library. SAIF.Framework.SecurityModule is an ASP.NET IHttpModule that establishes the caller's identity on every inbound web request: it decides whether a request is already authenticated, classifies the request's host as internal or external, and drives one of two fallback paths — a login-page redirect for external callers or an NTLM/Basic browser challenge for internal callers — whenever silent cookie-based re-authentication does not succeed. Two supporting utilities, DPAPI-based value protection and contextual log formatting, are used throughout this pipeline but are also exposed as general-purpose operations in their own right. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules Tables SQL
Register AuthenticateRequest handler Wire the module into the ASP.NET authentication pipeline so every request is intercepted. ASP.NET calls IHttpModule.Init when the module is instantiated. HttpApplication instance AuthRequest_Handler subscribed to AuthenticateRequest None None None
Authenticate inbound web request Orchestrate per-request authentication: skip already-authenticated callers, pick a fallback path, and normalize error handling. HttpApplication.AuthenticateRequest fires for an inbound request. Current HttpContext.User, request host, ExternalHostNames, sec-errorpage Request proceeds with an established principal, a redirect to login/error, or a 401 challenge BR-001, BR-002, BR-005, BR-006 None None
Perform cookie-based silent re-authentication Re-establish a Windows principal from the encrypted SAIFAUTH cookie without any browser prompt. An internal or external authenticator attempts silent sign-in for the current request. SAIFAUTH cookie, client host address, sec-logindomain Boolean success/failure; on success, HttpContext.Current.User is assigned a WindowsPrincipal BR-003, BR-004 None None
Issue browser credential challenge Build the HTTP 401 response that prompts an internal-host browser for NTLM or Basic credentials. Internal authenticator falls back after cookie authentication fails. HttpResponse, sec-browser-authtype 401 Not Authorized response carrying WWW-Authenticate headers BR-002 None None
Redirect external user to login Send external-host users to the configured login page when silent cookie authentication does not succeed. External authenticator falls back after cookie authentication fails. HttpApplication, SAIFAUTH cookie, sec-loginpage Successful principal establishment, or an HTTP redirect to the login page BR-002, BR-005 None None
Protect and unprotect sensitive values Encrypt or decrypt secrets — such as the credentials packed into the SAIFAUTH cookie — using Windows DPAPI. Caller invokes DPAPI.Encrypt or DPAPI.Decrypt. Plaintext/ciphertext strings or bytes, optional entropy, optional key scope Base64 ciphertext, UTF-8 plaintext, or a wrapped exception None None None
Write contextual diagnostic log entry Emit a single, request-aware log4net entry carrying host, URL, application, and call-stack context. Library code calls LogInfo, LogWarn, LogError, or LogDebug. Message text, current HttpContext, current call stack Formatted log4net entry None None None

Process flow diagram

The following diagram visualizes the primary operational flow across the request-authentication operations.

flowchart TD
    Start([AuthenticateRequest]) --> AlreadyAuth{Already authenticated?}
    AlreadyAuth -->|Yes| Proceed([Request proceeds])
    AlreadyAuth -->|No| HostClass{External host?}
    HostClass -->|Yes| ExtCookie[Perform cookie-based silent re-authentication]
    HostClass -->|No| IntCookie[Perform cookie-based silent re-authentication]
    ExtCookie --> ExtOk{Cookie auth succeeded?}
    ExtOk -->|Yes| Proceed
    ExtOk -->|No| Redirect([Redirect external user to login])
    IntCookie --> IntOk{Cookie auth succeeded?}
    IntOk -->|Yes| Proceed
    IntOk -->|No| Challenge([Issue browser credential challenge])
    ExtCookie -. exception .-> Error([Redirect to error page])
    IntCookie -. exception .-> Error

Failure and edge-case behavior

  • A request that already carries an authenticated principal is logged and bypasses the remainder of the authentication pipeline entirely (BR-001).
  • A missing, undecryptable, or malformed SAIFAUTH cookie is never treated as an error on its own; it simply falls through to the external-login redirect or the internal browser-challenge path instead of establishing a principal (BR-002, BR-003).
  • A failed Windows logon during token creation raises Unable to login, which the top-level request-authentication operation catches and converts into an error-page redirect (BR-004, BR-006).
  • The ThreadAbortException that Response.Redirect raises is expected control flow, not a failure; the pipeline suppresses it rather than logging it as an authentication error (BR-005).

Sources

  • SAIF.Framework.SecurityModule\clsSecurityModule.vb
  • SAIF.Framework.SecurityModule\Authenticators\UserAuthenticator.vb
  • SAIF.Framework.SecurityModule\Authenticators\CookieAuthenticator.vb
  • SAIF.Framework.SecurityModule\Authenticators\BrowserAuthenticator.vb
  • SAIF.Framework.SecurityModule\TokenProvider.vb
  • SAIF.Framework.SecurityModule\DAPIEncrypt.vb
  • SAIF.Framework.SecurityModule\mdlLogging.vb