---
title: SAIF.Framework.SecurityModule operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-07-30
library: SAIF.Framework.SecurityModule
reference_type: package
---

# 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](operations/register-authenticate-request-handler.md) | 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](operations/authenticate-inbound-web-request.md) | 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](business-rules.md#br-001-already-authenticated-users-are-not-re-processed), [BR-002](business-rules.md#br-002-host-classification-as-external-drives-the-authentication-fallback-path), [BR-005](business-rules.md#br-005-thread-abort-exceptions-from-response-redirect-must-not-be-treated-as-authentication-errors), [BR-006](business-rules.md#br-006-any-unhandled-authentication-exception-redirects-to-the-error-page) | None | None |
| [Perform cookie-based silent re-authentication](operations/perform-cookie-based-silent-reauthentication.md) | 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](business-rules.md#br-003-a-decrypted-saifauth-cookie-must-contain-exactly-two-tab-delimited-fields), [BR-004](business-rules.md#br-004-a-failed-windows-logon-is-treated-as-an-authentication-failure) | None | None |
| [Issue browser credential challenge](operations/issue-browser-credential-challenge.md) | 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](business-rules.md#br-002-host-classification-as-external-drives-the-authentication-fallback-path) | None | None |
| [Redirect external user to login](operations/redirect-external-user-to-login.md) | 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](business-rules.md#br-002-host-classification-as-external-drives-the-authentication-fallback-path), [BR-005](business-rules.md#br-005-thread-abort-exceptions-from-response-redirect-must-not-be-treated-as-authentication-errors) | None | None |
| [Protect and unprotect sensitive values](operations/protect-and-unprotect-sensitive-values.md) | 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](operations/write-contextual-diagnostic-log-entry.md) | 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.

```mermaid
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](business-rules.md#br-001-already-authenticated-users-are-not-re-processed)).
- 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](business-rules.md#br-002-host-classification-as-external-drives-the-authentication-fallback-path), [BR-003](business-rules.md#br-003-a-decrypted-saifauth-cookie-must-contain-exactly-two-tab-delimited-fields)).
- 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](business-rules.md#br-004-a-failed-windows-logon-is-treated-as-an-authentication-failure), [BR-006](business-rules.md#br-006-any-unhandled-authentication-exception-redirects-to-the-error-page)).
- 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](business-rules.md#br-005-thread-abort-exceptions-from-response-redirect-must-not-be-treated-as-authentication-errors)).

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## 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`