---
title: Perform cookie-based silent re-authentication
summary: Reconstruct a Windows principal from the encrypted SAIFAUTH cookie without prompting the browser.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-07-30
library: SAIF.Framework.SecurityModule
reference_type: package
operation_id: perform-cookie-based-silent-reauthentication
trigger: An internal or external authenticator attempts silent sign-in for the current request.
---

# Perform cookie-based silent re-authentication

This operation is the library's silent sign-in path, used by both fallback branches before they resort to a redirect or a browser challenge. It reads the `SAIFAUTH` request cookie, decrypts and validates the credentials packed inside it, exchanges those credentials for a Windows logon token, and — only if every step succeeds — assigns the resulting `WindowsPrincipal` to `HttpContext.Current.User`.

| Field | Value |
| --- | --- |
| **Operation ID** | `perform-cookie-based-silent-reauthentication` |
| **Trigger** | An internal or external authenticator attempts silent sign-in for the current request. |
| **Inputs** | `HttpApplication`, `SAIFAUTH` cookie, `Request.UserHostAddress`, `sec-logindomain` |
| **Outputs** | Boolean success/failure and optional `HttpContext.Current.User` assignment |
| **Primary components** | `CookieAuthenticator.Authenticate`, `CookieAuthenticator.DecryptCookie`, `TokenProvider.GetToken` |
| **Entry point** | `SAIF.Framework.SecurityModule\Authenticators\CookieAuthenticator.vb` |

## Steps

1. Log `Begin AuthenticateCookie`, initialize the local success flag and credential variables, and read `Context.Request.Cookies("SAIFAUTH")`.
   - If the cookie is missing, skip the credential path entirely and return `False` after the closing log entry — a missing cookie is not treated as an error.
2. Call `DecryptCookie(authCookie.Value, Context.Request.UserHostAddress, username, password)` to recover the packed credentials from the cookie.
   - The helper delegates the cryptographic reversal to [Protect and unprotect sensitive values](protect-and-unprotect-sensitive-values.md).
   - It splits the decrypted string on tab characters, discarding empty entries, and accepts the payload only when exactly two fields remain ([BR-003](../business-rules.md#br-003-a-decrypted-saifauth-cookie-must-contain-exactly-two-tab-delimited-fields)).
   - If the split count is wrong, log a warning and return `False`.
   - If decryption or splitting throws an exception, log the exception together with the cookie value and entropy, then return `False`.
3. If cookie decryption or validation failed at any point, log `Error decrypting SAIFAuth cookie`, log `End AuthenticateCookie`, and return `False` to the caller.
4. If cookie decryption and validation succeeded, call `TokenProvider.GetToken(username, password)` to obtain a Windows logon token for the recovered credentials.
   - `GetToken` calls Win32 `LogonUser` against the domain named in `AppSettings("sec-logindomain")`, duplicates the returned handle, and closes the original handle.
   - If the Win32 logon fails or the original handle is zero, `GetToken` throws `Unable to login`, which this operation does not catch ([BR-004](../business-rules.md#br-004-a-failed-windows-logon-is-treated-as-an-authentication-failure)).
5. Clear the local password reference, construct a `WindowsIdentity` from the token, wrap it in a `WindowsPrincipal`, and assign that principal to `HttpContext.Current.User`.
   - If the assignment succeeds, set the local result flag to `True`.
   - If the assignment throws, catch the exception locally, log its message at debug level, and leave the result as `False` rather than propagating the exception.
6. In a `Finally` block, call `TokenProvider.ReleaseToken(Token)` unconditionally, regardless of whether token creation or principal assignment succeeded.
7. Log `End AuthenticateCookie` and return the Boolean result to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Read SAIFAUTH cookie]) --> D1{Cookie present?}
	D1 -->|No| EndFail([Return False])
	D1 -->|Yes| S1[Decrypt and split cookie]
	S1 --> D2{Exactly two fields?}
	D2 -->|No| EndFail
	D2 -->|Yes| S2[Call TokenProvider.GetToken]
	S2 --> D3{Token created?}
	D3 -->|No| EndErr([Exception to caller])
	D3 -->|Yes| S3[Create principal and assign HttpContext.Current.User]
	S3 --> EndOk([Return True])
```

## Failure and edge-case behavior

- A missing cookie is a normal silent-authentication miss: the operation returns `False` without raising an exception, letting the caller fall back to a redirect or challenge.
- A cookie payload that fails to decrypt, or that decrypts but does not split into exactly two tab-delimited fields, is rejected and logged rather than accepted partially ([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 propagates `Unable to login` up to the top-level request handler rather than being swallowed here ([BR-004](../business-rules.md#br-004-a-failed-windows-logon-is-treated-as-an-authentication-failure)).
- Principal-assignment failures are caught and logged locally, so the caller only ever sees a plain `False` result — never an exception — for that specific failure mode.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

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