---
title: Web login and cookie issuance
summary: Authenticates a web user and issues the cookies needed for subsequent Forms-based requests.
status: draft
owner: <owner>
last_reviewed: 2026-07-30
library: SAIF.Framework.Security
reference_type: package
operation_id: OP-008
trigger: Caller invokes `clsSAIFLoginInfo.Login()`
---

# Web login and cookie issuance

`clsSAIFLoginInfo.Login()` is the operation an interactive web sign-in page ultimately calls. It wraps explicit-credential authentication for a web-scoped principal, and — only when that authentication succeeds — writes both a custom, DPAPI-encrypted `SAIFAUTH` cookie and the standard ASP.NET Forms authentication cookie, so that later requests can be recognized without asking the user to log in again.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-008 |
| **Trigger** | Caller invokes `clsSAIFLoginInfo.Login()` |
| **Inputs** | User ID, password, optional domain, current HTTP context |
| **Outputs** | Boolean login result plus `SAIFAUTH` and Forms authentication cookies on success |
| **Primary components** | `clsSAIFLoginInfo.Login`, `clsSecurityPrincipal.Authenticate`, `DPAPI.Encrypt` |
| **Entry point** | `SAIF.Framework.Security\clsSAIFLoginInfo.vb` |

## Steps

1. `Login()` constructs a web-scoped `clsSecurityPrincipal` and assigns `UserName`, `Password`, and optional `Domain` to it. Because those property setters always call `Logout()` first, any prior principal state is cleared before the new login attempt begins — enforcing [BR-006](../business-rules.md#br-006-changing-identity-properties-logs-the-principal-out).
2. The helper calls `SecurityPrincipal.Authenticate()`, delegating to the same explicit-credential NTLM authentication used elsewhere in the library.
   - If authentication fails: `Login()` returns `False` immediately, and no cookies are written.
3. On success, the helper concatenates `UserID`, a tab separator, and the clear-text password into a single payload, encrypts it with `DPAPI.Encrypt(MachineKey, credentials, HttpContext.Current.Request.UserHostAddress, "")` — using the requesting host address as additional entropy — and stores the encrypted result in the `SAIFAUTH` cookie.
4. The helper then issues `FormsAuthentication.SetAuthCookie("user@domain", False)`, giving later requests a standard Forms ticket that principal initialization can rehydrate through its Forms-identity branch.
5. `Login()` returns `True` to signal a completed, cookie-backed login.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Login requested]) --> Principal[Create web principal]
	Principal --> Auth[Authenticate credentials]
	Auth --> Success{Authenticated?}
	Success -->|No| EndErr([Return False])
	Success -->|Yes| Cookie1[Write SAIFAUTH cookie]
	Cookie1 --> Cookie2[Write Forms auth cookie]
	Cookie2 --> EndOk([Return True])
```

## Failure and edge-case behavior

- A failed authentication attempt prevents both cookies from being issued — there is no partial cookie state.
- The encrypted `SAIFAUTH` payload uses the requesting host's address as additional DPAPI entropy, tying the encrypted credential to the originating client.
- The helper requires an active HTTP context to create cookies; it is a web-only operation.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Security and authorization](../security-authorization.md)

## Sources
- `SAIF.Framework.Security\clsSAIFLoginInfo.vb`
- `SAIF.Framework.Security\clsSecurityPrincipal.vb`
- `SAIF.Framework.Security\DAPIEncrypt.vb`