---
title: CookieAuthenticator
summary: API reference for CookieAuthenticator.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.SecurityModule
reference_type: package
---

# CookieAuthenticator

`CookieAuthenticator` implements the silent, cookie-based re-authentication fast path. It reads the `SAIFAUTH` request cookie, decrypts it via `DPAPI`, splits the recovered value into a username/password pair, exchanges those credentials for a Windows logon token via `TokenProvider`, and assigns the resulting `WindowsPrincipal` to `HttpContext.Current.User`.

## Purpose
- Provide silent Windows re-authentication from a previously issued encrypted cookie, avoiding a repeated browser credential prompt.
- Validate the decrypted cookie's shape before treating it as valid credentials (see [BR-003](../../business-rules.md#br-003-a-decrypted-saifauth-cookie-must-contain-exactly-two-tab-delimited-fields)).

## Context
- Namespace: `SAIF.Framework.SecurityModule`
- Assembly/package: `SAIF.Framework.SecurityModule` (packaged inside the `SAIF.BOF.Framework` NuGet package)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `Authenticate` | `Public Shared Function Authenticate(Context As HttpApplication) As Boolean` | Reads the `SAIFAUTH` cookie, decrypts and validates it, obtains a Windows token via `TokenProvider.GetToken`, builds a `WindowsIdentity`/`WindowsPrincipal`, and assigns it to `HttpContext.Current.User`. Returns `true` on success. |
| `DecryptCookie` | `Private Shared Function DecryptCookie(inCookie As String, inEntropy As String, ByRef inUserName As String, ByRef inPWD As String) As Boolean` | Decrypts `inCookie` via `DPAPI.Decrypt` (using `inEntropy`, typically the client host address), splits the result on `Chr(9)`, and outputs username/password by reference when exactly two segments are found. Private; listed for architectural completeness. |

## Behavioral notes
- If the `SAIFAUTH` cookie is absent from the request, `Authenticate` returns `false` without attempting decryption.
- The client's `UserHostAddress` is used as the DPAPI decryption entropy value, tying successful decryption to the requesting host address.
- On successful token acquisition, the local `password` variable is explicitly set to `Nothing` immediately afterward as a memory-hygiene measure before the `WindowsIdentity`/`WindowsPrincipal` is constructed.
- The acquired token handle is always released via `TokenProvider.ReleaseToken` in a `Finally` block, regardless of whether principal assignment succeeds.
- Any exception during `DecryptCookie` (e.g., a DPAPI decryption failure) is caught, logged with the cookie contents and entropy value, and treated as a decryption failure rather than propagated.

## Constraints and usage notes
- All public members are `Shared`; the class is not intended to be instantiated.
- `DecryptCookie` is `Private` and is only reachable through `Authenticate`.

## Sources
- `SAIF.Framework.SecurityModule\Authenticators\CookieAuthenticator.vb`