Skip to content

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).
  2. creds = _settings.AppCredentials (BR-OIDC-04) — see Resolve OIDC settings. This is a secure-setting retrieval; OidcAppCredentials splits clientId|clientSecret.
  3. On failure: ArgumentNullException/ArgumentException (from ServiceContracts) on a missing or malformed value; EnvironmentClientException on a missing secure setting.
  4. JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear() (global, process-wide) (BR-OIDC-05).
  5. Set Authority = OktaBaseUrl + OktaAuthorizationServerUrl, RequireHttpsMetadata = true, ClientId/ClientSecret, ResponseType = "code", GetClaimsFromUserInfoEndpoint = true, add each DefaultScopes entry, SaveTokens = true (BR-OIDC-06).
  6. 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).
  7. Set TokenValidationParameters: RequireExpirationTime, RequireSignedTokens, ValidateIssuer, ValidateAudience (ValidAudience = ClientId), ValidateIssuerSigningKey, ValidateLifetime all true; ClockSkew = ClockSkewSeconds; NameClaimType = "name"; RoleClaimType = ClaimTypes.Role (BR-OIDC-07).
  8. On failure: an invalid token (signature, expiry, issuer, or audience) fails validation and surfaces as a remote failure — see Handle remote authentication failure.
  9. DataProtectionProvider = DataProtectionProvider.Create(new DirectoryInfo(DPKeyDirectory), b => b.SetApplicationName($"{DPApplicationName}-oidc")) (BR-OIDC-08). 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.
  10. Events.OnRedirectToIdentityProvider = BeforeRedirectToIdentityProviderAsync — see Before redirect to identity provider. Events.OnRemoteFailure = OnRemoteFailureAsync — see Handle remote authentication failure.
  11. _logger.Info("OIDC authentication initialized.").

Process flow

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).
  • 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 — 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.

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