---
title: Configure OpenID Connect
summary: Builds the "OpenIdConnect" named options — Okta authority, client credentials, token validation, state protection, and redirect/failure events.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.OIDC
reference_type: package
operation_id: OP-02
trigger: Options system builds the named OpenIdConnectOptions (first use of scheme "OpenIdConnect")
---

# Configure OpenID Connect

| Field | Value |
| --- | --- |
| **Operation ID** | OP-02 |
| **Trigger** | The options system builds the named `OpenIdConnectOptions` (first use of scheme `"OpenIdConnect"`) |
| **Inputs** | `IOidcSettings` |
| **Outputs** | Configured `OpenIdConnectOptions` |
| **Primary components** | `ConfigureOpenIdConnectOptions.Configure(string, OpenIdConnectOptions)`, `BeforeRedirectToIdentityProviderAsync`, `OnRemoteFailureAsync` |
| **Entry point** | `src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureOpenIdConnectOptions.cs` L50–104 |

## Steps

1. Return unless `options != null && name == "OpenIdConnect"` ([BR-OIDC-01](../business-rules.md#br-oidc-01-option-configurators-apply-only-to-their-named-scheme)).
2. `creds = _settings.AppCredentials` ([BR-OIDC-04](../business-rules.md#br-oidc-04-oidc-client-credentials-come-from-a-secure%2C-library-hashed-setting)) — see [Resolve OIDC settings](op-11-resolve-oidc-settings.md). This is a secure-setting retrieval; `OidcAppCredentials` splits `clientId|clientSecret`.
   - On failure: `ArgumentNullException`/`ArgumentException` (from `ServiceContracts`) on a missing or malformed value; `EnvironmentClientException` on a missing secure setting.
3. `JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear()` (global, process-wide) ([BR-OIDC-05](../business-rules.md#br-oidc-05-inbound-jwt-claim-names-are-not-remapped)).
4. Set `Authority = OktaBaseUrl + OktaAuthorizationServerUrl`, `RequireHttpsMetadata = true`, `ClientId`/`ClientSecret`, `ResponseType = "code"`, `GetClaimsFromUserInfoEndpoint = true`, add each `DefaultScopes` entry, `SaveTokens = true` ([BR-OIDC-06](../business-rules.md#br-oidc-06-oidc-uses-the-authorization-code-flow-against-okta)).
5. `SecurityTokenValidator = new StrictSecurityTokenValidator()` (Okta). `CallbackPath`, `SignedOutCallbackPath` (source comment at ~L73 notes the correct values are still undetermined), `UseTokenLifetime = false`. `BackchannelHttpHandler = new OktaHttpMessageHandler("okta-aspnetcore", typeof(OktaAuthenticationOptionsExtensions).Assembly.GetName().Version)` ([BR-OIDC-06](../business-rules.md#br-oidc-06-oidc-uses-the-authorization-code-flow-against-okta)).
6. Set `TokenValidationParameters`: `RequireExpirationTime`, `RequireSignedTokens`, `ValidateIssuer`, `ValidateAudience` (`ValidAudience = ClientId`), `ValidateIssuerSigningKey`, `ValidateLifetime` all `true`; `ClockSkew = ClockSkewSeconds`; `NameClaimType = "name"`; `RoleClaimType = ClaimTypes.Role` ([BR-OIDC-07](../business-rules.md#br-oidc-07-id-tokens-must-pass-full-validation)).
   - On failure: an invalid token (signature, expiry, issuer, or audience) fails validation and surfaces as a remote failure — see [Handle remote authentication failure](op-04-handle-remote-failure.md).
7. `DataProtectionProvider = DataProtectionProvider.Create(new DirectoryInfo(DPKeyDirectory), b => b.SetApplicationName($"{DPApplicationName}-oidc"))` ([BR-OIDC-08](../business-rules.md#br-oidc-08-oidc-correlation-state-uses-an-unencrypted-key-ring)). There is **no certificate protection** here; a source comment attributed to ryadug (dated 2026-07-29) at L93–95 notes the `-oidc` suffix can be removed once the cookie ring's own certificate protection is disabled.
8. `Events.OnRedirectToIdentityProvider = BeforeRedirectToIdentityProviderAsync` — see [Before redirect to identity provider](op-03-before-redirect-idp.md). `Events.OnRemoteFailure = OnRemoteFailureAsync` — see [Handle remote authentication failure](op-04-handle-remote-failure.md).
9. `_logger.Info("OIDC authentication initialized.")`.

## Process flow

```mermaid
flowchart TD
	Start([Options system builds OpenIdConnect options]) --> NameCheck{options present and name == OpenIdConnect?}
	NameCheck -->|No| NoOp([No change])
	NameCheck -->|Yes| Creds[Resolve AppCredentials secure setting]
	Creds --> ClearMap[Clear DefaultInboundClaimTypeMap - global]
	ClearMap --> SetAuthority["Set Authority, ClientId/Secret, ResponseType=code,<br>scopes, SaveTokens"]
	SetAuthority --> SetHandler["Set StrictSecurityTokenValidator, CallbackPath,<br>BackchannelHttpHandler"]
	SetHandler --> SetTVP["Set TokenValidationParameters: issuer, audience,<br>lifetime, signature"]
	SetTVP --> SetDP[Set DataProtectionProvider for OIDC state - unencrypted]
	SetDP --> WireEvents[Wire OnRedirectToIdentityProvider and OnRemoteFailure events]
	WireEvents --> Log["Log: OIDC authentication initialized"]
	Log --> Done([Configured OpenIdConnectOptions])
```

## Failure and edge-case behavior
- A missing or malformed `BOLAppCredentials` secure setting throws before the handler finishes building, so no OIDC request can be served ([BR-OIDC-04](../business-rules.md#br-oidc-04-oidc-client-credentials-come-from-a-secure%2C-library-hashed-setting)).
- `DefaultInboundClaimTypeMap.Clear()` is a **global, process-wide** mutation; it affects every `JwtSecurityTokenHandler` in the process, not just this authentication scheme.
- The OIDC correlation/nonce state key ring has no certificate protection, unlike the cookie key ring in [Configure cookie authentication](op-01-configure-cookie-auth.md) — noted as a known gap by a source comment attributed to ryadug (dated 2026-07-29).
- An invalid token (signature, issuer, audience, or expiry) does not throw directly here; it surfaces through the `OnRemoteFailure` event — see [Handle remote authentication failure](op-04-handle-remote-failure.md).

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

> **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/ConfigureOpenIdConnectOptions.cs`