Skip to content

SAIF.Framework.SecurityModule overview

Documentation context: Packaged Component (NuGet)

SAIF.Framework.SecurityModule is an ASP.NET IHttpModule-based authentication module that hooks the HttpApplication.AuthenticateRequest pipeline event to establish a WindowsPrincipal for inbound web requests. It authenticates users either silently, by decrypting an encrypted SAIFAUTH cookie and exchanging the recovered Windows credentials for a logon token, or by falling back to an NTLM/Basic browser credential challenge (internal hosts) or a login-page redirect (external hosts).

Purpose

  • Provide a reusable, host-application-agnostic ASP.NET authentication module that establishes Windows identity for inbound requests without requiring each hosting application to implement its own authentication logic.
  • Offer a silent, cookie-based re-authentication fast path (via DPAPI-encrypted credentials and Win32 LogonUser token exchange) to avoid repeated browser credential prompts, with an NTLM/Basic challenge or login-page redirect fallback when the cookie is absent or invalid.
  • Provide supporting cross-cutting utilities — DPAPI-based value encryption/decryption and log4net-backed diagnostic logging — used throughout the authentication pipeline.

Responsibilities

  • Register AuthRequest_Handler on HttpApplication.AuthenticateRequest so authentication runs on every inbound request (clsSecurityModule.Init).
  • Classify the requesting host as "internal" or "external" and route to the corresponding authenticator (InternalUserAuthenticator / ExternalUserAuthenticator).
  • Decrypt the SAIFAUTH cookie (DPAPI) and exchange the recovered username/password for a Windows logon token (Win32 LogonUser/DuplicateToken), assigning the resulting WindowsPrincipal to HttpContext.Current.User.
  • Fall back to an HTTP 401 NTLM/Basic browser challenge (internal hosts) or a redirect to a configured login page (external hosts) when cookie authentication fails.
  • Catch and route unhandled authentication exceptions to a configured error page, while suppressing false-positive errors from ThreadAbortExceptions raised by Response.Redirect.

Key components

  • clsSecurityModule: IHttpModule pipeline entry point; wires and drives the authentication flow, and handles error routing.
  • UserAuthenticator (abstract base) with ExternalUserAuthenticator / InternalUserAuthenticator: factory-selected strategy layer for internal-vs-external handling and the "already authenticated" short-circuit.
  • CookieAuthenticator: decrypts and validates the SAIFAUTH cookie and obtains a Windows logon token via TokenProvider.
  • BrowserAuthenticator: issues the HTTP 401 NTLM/Basic challenge for internal hosts.
  • TokenProvider: Friend-scoped wrapper over Win32 LogonUser/DuplicateToken P/Invoke calls.
  • DPAPI: wraps Win32 CryptProtectData/CryptUnprotectData for encrypting/decrypting the SAIFAUTH cookie value and other secrets.
  • mdlLogging: shared log4net-backed logging facility consumed by every class in the module.

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
  • SAIF.Framework.SecurityModule\SAIF.Framework.SecurityModule.vbproj