---
title: SAIF.NetCore.OIDC overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.OIDC
reference_type: package
---

# 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](service-registration.md).

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [Service registration](service-registration.md)
- [API reference](api/index.md)

## 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`