Skip to content

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.

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); 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 and Before redirect to IdP (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) 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) — 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.

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.

Sources

  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IServiceCollectionExtensions.cs