Skip to content

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). The parameterless Configure(options) overload passes Options.DefaultName, so it is always a no-op.
  2. cert = _certService.GetCertificate() (BR-OIDC-14, BR-OIDC-15) — see Resolve data-protection certificate.
  3. On failure: may throw MissingDataProtectionCertificateException on a non-developer machine.
  4. 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), resolved through Resolve OIDC settings.
  5. Cookie.SecurePolicy is not set, so the default SameAsRequest applies*.
  6. 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). The purpose string contains the typo "ApsNetCore".
  7. On failure/branch: if cert is null (developer machine), the key ring is not encrypted at rest.
  8. Events.OnRedirectToLogin = ctx => _redirectService.Redirect(ctx.HttpContext) (BR-OIDC-16) — see Redirect to login.
  9. _logger.Info("Cookie authentication initialized.").

Process flow

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.
  • 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*.

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