SAIF.NetCore.OIDC overview

Documentation context: Distributed as a NuGet package.

SAIF.NetCore.OIDC supplies turnkey Okta OpenID Connect and cookie-authentication building blocks for externally-hosted SAIF ASP.NET Core applications (BOL): option configurators for the cookie and OIDC handlers, authentication middleware, role-claim transformation, data-protection certificate lookup, login redirection, and an Okta refresh-token client. It is an implementation-layer library that depends only on the foundation layer, SAIF.NetCore.ServiceContracts.

Purpose

• Establish and maintain an authenticated principal for externally hosted applications through the Okta OIDC authorization-code flow and a shared, encrypted authentication cookie.
• Keep JWT claim values synchronized with the authentication cookie on every request, and redirect expired sessions to a dedicated token-refresh application.
• Map Okta group/role claims onto ClaimTypes.Role (when a consumer wires the transformer in), and resolve the data-protection certificate used to encrypt the cookie key ring.
• Resolve every OIDC-related setting from the Environment API section NetCore_OIDC.

Responsibilities

• Configure the ASP.NET Core cookie and OpenID Connect authentication handlers against Okta (ConfigureCookieAuthenticationOptions, ConfigureOpenIdConnectOptions).
• Enforce auth-cookie rewriting, JWT refresh, and URL-casing normalization through IMiddleware components (JwtClaimMiddleware, RefreshJwtMiddleware, LowerCaseUrlMiddleware).
• Refresh expired access/ID tokens against the Okta token endpoint (JwtRefreshService).
• Transform and cache role claims on the authenticated principal (RoleClaimTransformer, RoleClaimService, ClaimTransformationCacheService).
• Resolve data-protection certificates from the local certificate store for cookie key-ring protection (DataProtectionCertService).
• Redirect unauthenticated requests to the login flow, preserving the originating URL (LoginRedirectService).

Key components

• ConfigureCookieAuthenticationOptions / ConfigureOpenIdConnectOptions (SAIF.NetCore.OIDC.Options): one-time option configurators for the "Cookies"/"OpenIdConnect" authentication schemes.
• JwtClaimMiddleware, RefreshJwtMiddleware, LowerCaseUrlMiddleware (SAIF.NetCore.OIDC.Middleware): per-request cookie/claim synchronization, token-expiry redirect, and URL-casing enforcement.
• OidcSettings, JwtRefreshService, RoleClaimService/RoleClaimTransformer/ClaimTransformationCacheService, DataProtectionCertService, LoginRedirectService, UrlCaseService (SAIF.NetCore.OIDC.Services): settings resolution, Okta refresh calls, role-claim transformation and caching, certificate lookup, and login redirection.

This library ships no DI registration extension method of its own; composing and registering every type in this library into IServiceCollection/IApplicationBuilder is owned entirely by the consumer, SAIF.NetCore.ServiceExtensions (RegisterOidcServices/AddWebAuthentication). See Service registration.

Related documentation

• Index
• Architecture
• Dependencies
• Configuration
• Operations and processes
• Business rules
• Security and authorization
• Service registration
• API reference

Sources

• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/SAIF.NetCore.OIDC.csproj
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Constants.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Contracts/RefreshTokenResult.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Exceptions/HttpContextAuthenticateException.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Exceptions/JwtRefreshException.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Exceptions/MissingDataProtectionCertificateException.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Extensions/ClaimsPrincipalExtensions.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Extensions/HttpContextExtensions.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Middleware/JwtClaimMiddleware.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Middleware/LowerCaseUrlMiddleware.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Middleware/RefreshJwtMiddleware.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureCookieAuthenticationOptions.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureOpenIdConnectOptions.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/ClaimTransformationCacheService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/DataProtectionCertService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/JwtAuthorizationCookieClaimService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/JwtRefreshService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/LoginRedirectService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/OidcSettings.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/RoleClaimService.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/RoleClaimTransformer.cs
• src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Services/UrlCaseService.cs