---
title: Configure cookie authentication
summary: Builds the "Cookies" named options — cookie attributes, data-protection ticket format, and the login-redirect event.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.OIDC
reference_type: package
operation_id: OP-01
trigger: Options system builds the named CookieAuthenticationOptions (first use of scheme "Cookies")
---

# Configure cookie authentication

| Field | Value |
| --- | --- |
| **Operation ID** | OP-01 |
| **Trigger** | The options system builds the named `CookieAuthenticationOptions` (first use of scheme `"Cookies"`) |
| **Inputs** | `IOidcSettings`, `IDataProtectionCertService`, `ILoginRedirectService` |
| **Outputs** | Configured `CookieAuthenticationOptions` |
| **Primary components** | `ConfigureCookieAuthenticationOptions.Configure(string, CookieAuthenticationOptions)` |
| **Entry point** | `src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureCookieAuthenticationOptions.cs` L49–92 |

## Steps

1. Return without changes unless `name == "Cookies"` ([BR-OIDC-01](../business-rules.md#br-oidc-01-option-configurators-apply-only-to-their-named-scheme)). The parameterless `Configure(options)` overload passes `Options.DefaultName`, so it is always a no-op.
2. `cert = _certService.GetCertificate()` ([BR-OIDC-14](../business-rules.md#br-oidc-14-data-protection-certificate-must-match-subject-and-validity-window), [BR-OIDC-15](../business-rules.md#br-oidc-15-a-missing-dp-certificate-is-fatal-outside-developer-machines)) — see [Resolve data-protection certificate](op-07-resolve-dp-certificate.md).
   - On failure: may throw `MissingDataProtectionCertificateException` on a non-developer machine.
3. Set `Cookie.Name = CookieName`, `LoginPath = CookieLoginPath`, `ExpireTimeSpan = CookieExpireMinutes` minutes, `Cookie.SameSite = Lax`, `Cookie.IsEssential = true`, `Cookie.HttpOnly = true`, `Cookie.Path = "/"`, `SlidingExpiration = true`, `AccessDeniedPath = CookieAccessDeniedPath` ([BR-OIDC-02](../business-rules.md#br-oidc-02-cookie-attributes-are-fixed%3B-secure-policy-is-not-enforced)), resolved through [Resolve OIDC settings](op-11-resolve-oidc-settings.md).
   - `Cookie.SecurePolicy` is **not** set, so the default `SameAsRequest` applies*.
4. `TicketDataFormat = new SecureDataFormat<AuthenticationTicket>(TicketSerializer.Default, DataProtectionProvider.Create(new DirectoryInfo(DPKeyDirectory), b => { b.SetApplicationName(DPApplicationName); if (cert != null) b.ProtectKeysWithCertificate(cert); }).CreateProtector("Microsoft.ApsNetCore.Authentication.Cookies.CookieAuthenticationMiddleware", "Cookies", "v2"))` ([BR-OIDC-03](../business-rules.md#br-oidc-03-cookie-tickets-are-protected-by-a-shared-file-system-key-ring)). The purpose string contains the typo "**Aps**NetCore".
   - On failure/branch: if `cert` is `null` (developer machine), the key ring is not encrypted at rest.
5. `Events.OnRedirectToLogin = ctx => _redirectService.Redirect(ctx.HttpContext)` ([BR-OIDC-16](../business-rules.md#br-oidc-16-login-redirects-always-use-https-on-the-current-host)) — see [Redirect to login](op-08-redirect-to-login.md).
6. `_logger.Info("Cookie authentication initialized.")`.

## Process flow

```mermaid
flowchart TD
	Start([Options system builds Cookies options]) --> NameCheck{name == Cookies?}
	NameCheck -->|No| NoOp([No change])
	NameCheck -->|Yes| GetCert[Resolve data-protection certificate]
	GetCert --> SetAttrs["Set cookie name, paths, expiry, SameSite=Lax, HttpOnly"]
	SetAttrs --> TicketFormat[Build TicketDataFormat with DataProtectionProvider]
	TicketFormat --> CertBranch{Certificate available?}
	CertBranch -->|Yes| Encrypted[Key ring encrypted with certificate]
	CertBranch -->|No| Unencrypted[Key ring unencrypted - dev machine]
	Encrypted --> Event[Wire OnRedirectToLogin event]
	Unencrypted --> Event
	Event --> Log["Log: Cookie authentication initialized"]
	Log --> Done([Configured CookieAuthenticationOptions])
```

## Failure and edge-case behavior
- A missing data-protection certificate on a non-developer machine throws `MissingDataProtectionCertificateException` before the cookie options finish building, so authentication cannot start.
- `Cookie.SecurePolicy` is never set, so cookies can be sent over plain HTTP when the request itself is HTTP*; see [Security and authorization](../security-authorization.md).
- The ticket-format purpose string contains a typo (`Aps` instead of `Asp`); this is a cosmetic/compatibility detail of the data-protection purpose chain, not a functional defect*.

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

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- `src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureCookieAuthenticationOptions.cs`