---
title: Add web authentication
summary: Configures Cookie/OpenIdConnect authentication schemes for web applications.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ServiceExtensions
reference_type: package
operation_id: OP-08
trigger: Register OIDC services calls AddWebAuthentication(type) as its final step.
---

# Add web authentication

This operation configures the Cookie and OpenIdConnect authentication handlers for web applications, defaulting the challenge scheme based on the requested authentication type. It is the final step of [Register OIDC services](register-oidc-services.md).

| Field | Value |
| --- | --- |
| **Operation ID** | OP-08 |
| **Trigger** | `RegisterOidcServices` calls `AddWebAuthentication(type)`. |
| **Inputs** | `type` — the authentication challenge type (`Cookie` or `OpenIdConnect`). |
| **Outputs** | `AddAuthentication`/`.AddCookie()`/`.AddOpenIdConnect()` configured with default schemes. |
| **Primary components** | `IServiceCollectionExtensions.AddWebAuthentication` |
| **Entry point** | `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs` (L177–212) |

## Steps

1. `ConfigureOptions<ConfigureCookieAuthenticationOptions>()` registers an `IConfigureOptions<CookieAuthenticationOptions>`.

   > **Origin**: The cookie-option configuration logic is implemented in [`Configure cookie auth`](../../saif-netcore-oidc/operations/op-01-configure-cookie-auth.md) (`SAIF.NetCore.OIDC`); this step only registers the configurator — it runs later, the first time the framework resolves `CookieAuthenticationOptions` for the `"Cookies"` scheme, not during this call.
2. `ConfigureOptions<ConfigureOpenIdConnectOptions>()` registers an `IConfigureOptions<OpenIdConnectOptions>`.

   > **Origin**: The OIDC option configuration logic, including the pre-redirect-to-IdP hook, is implemented in [`Configure OIDC`](../../saif-netcore-oidc/operations/op-02-configure-oidc.md) and [`Before redirect to IdP`](../../saif-netcore-oidc/operations/op-03-before-redirect-idp.md) (`SAIF.NetCore.OIDC`); this step only registers the configurator — it runs later, the first time the framework resolves `OpenIdConnectOptions` for the `"OpenIdConnect"` scheme, not during this call.
3. `AddAuthentication((options) => { options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme; options.DefaultChallengeScheme = challengeScheme; })`: `DefaultAuthenticateScheme = DefaultSignInScheme = "Cookies"`; `DefaultChallengeScheme = OpenIdConnect` if `type == OpenIdConnect`, else `"Cookies"` ([BR-SE-11](../business-rules.md#br-se-11-web-apps-default-to-cookie-authentication-with-optional-openidconnect-challenge))
4. `.AddCookie("Cookies").AddOpenIdConnect()` registers both handlers regardless of the selected challenge scheme.
   - On remote authentication failure at request time: the registered `OpenIdConnectOptions`'s own `OnRemoteFailure` behavior governs the response, implemented by OIDC's [`Handle remote failure`](../../saif-netcore-oidc/operations/op-04-handle-remote-failure.md) (`SAIF.NetCore.OIDC`) — this runs per-request during the OIDC challenge/callback flow, not as part of this registration call.

## Process flow

This diagram shows the one-time scheme-registration work performed when `AddWebAuthentication` is called as the final step of OIDC service registration, not the per-request authentication/challenge flow that runs afterward.

```mermaid
flowchart TD
    Start([AddWebAuthentication called]) --> S1[Configure cookie auth options]
    S1 --> S2[Configure OIDC auth options]
    S2 --> S3{type == OpenIdConnect?}
    S3 -->|Yes| S3a["DefaultChallengeScheme = OpenIdConnect"]
    S3 -->|No| S3b["DefaultChallengeScheme = Cookies"]
    S3a --> S4[Add Cookie and OpenIdConnect handlers]
    S3b --> S4
    S4 --> EndOk([Web authentication schemes ready])
```

## Failure and edge-case behavior
- A remote (IdP) authentication failure is handled by OIDC's own remote-failure handler, not by this library.

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

## Sources
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs`