OIDC Provider

The OIDC Provider mode configures the Maverics Orchestrator as an OpenID Connect authorization server. It sits between your applications and upstream identity providers — handling authentication flows, enriching claims from multiple sources, and providing seamless IdP failover without application changes.

Console terminology: In the Maverics Console, the combination of applications, policies, headers, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].policies[].

When to use this mode

OIDC Provider — Choose this mode when your applications support OpenID Connect. Best for modern apps that can consume OIDC tokens natively.
SAML Provider — Choose this mode for applications that only support SAML 2.0 assertions.
HTTP Proxy — Choose this mode when you cannot modify the application’s authentication code.
LDAP Provider — Choose this mode for applications that require an LDAP directory for authentication.
AI Identity Gateway — Choose this mode for securing AI agent-to-tool communication via MCP.

Use Cases

SSO consolidation — Unify multiple identity providers behind a single OIDC-compliant interface, giving users one login experience across all applications.
IdP migration with zero downtime — Route authentication traffic between old and new identity providers during migration without disrupting end users.
Legacy app modernization via OIDC — Add OpenID Connect support to applications that previously relied on proprietary or outdated authentication mechanisms.
Claim enrichment from multiple sources — Aggregate user attributes from directories, databases, and APIs into a single enriched token for downstream applications.

How It Works

The OIDC Provider authentication flow follows these steps:

Application redirects — A user accesses an application registered as an OIDC relying party. The application redirects the user to the Orchestrator’s authorization endpoint.
Upstream authentication — The Orchestrator routes the user to the configured upstream identity provider (Microsoft Entra ID, Okta, etc.) for authentication. If multiple IdPs are configured, failover rules determine which to use.
Attribute enrichment — After authentication, the Orchestrator loads additional attributes from configured attribute providers (directories, databases, APIs) and enriches the user’s profile.
Token issuance — The Orchestrator generates OIDC tokens (ID token, access token, optional refresh token) with claims mapped from the authenticated identity and enriched attributes.
Application receives tokens — The application receives the tokens at its redirect URI and uses them for session establishment and authorization decisions.
Ongoing token operations — The Orchestrator serves the JWKS endpoint for token verification, handles token introspection and revocation, and manages token refresh flows.

Key Concepts

Provider vs Apps

The OIDC Provider has two configuration levels: provider-level settings (issuer, endpoints, signing keys) shared across all OIDC apps, and individual app entries that each register a specific relying party (client application) with its own credentials, scopes, and claims mapping. One Orchestrator can serve many OIDC apps.

Claims Mapping

Claims mapping translates attributes from upstream identity providers into OIDC token claims. The format connector.attribute (e.g., upstream-idp.email) references a specific claim from a named connector. This enables enriching tokens with data from multiple identity sources.

IdP Failover

When multiple identity providers are listed under authentication.idps, the Orchestrator tries them in order. If the primary IdP is unavailable, authentication falls back to the next provider seamlessly — no application changes required.

Token Types

The Orchestrator issues two token formats: JWT tokens (self-contained, verified via JWKS) and opaque tokens (reference tokens, verified via introspection). Choice depends on whether resource servers can validate locally or must call back.

Service Extensions

Go-based extension hooks allow custom logic at key points in the flow — custom authentication checks, custom claim building, and custom attribute loading. These provide escape hatches when standard configuration is insufficient.

Setup

Console UI
Configuration

In the Maverics Console, OIDC Provider settings are configured in the Deployment Settings dialog under the OIDC Provider section.Issuer and Endpoints

Field	Required	Description
Issuer	Yes	Case-sensitive HTTPS URL that identifies this OIDC Provider. Used as the `iss` claim in issued tokens.
Generate	—	Button that auto-generates all endpoint URLs from the Issuer domain.
Well-Known	Yes	OIDC discovery endpoint (auto-generated from Issuer).
Authorization	Yes	Authorization endpoint for login flows (auto-generated).
Token	Yes	Token endpoint for code exchange and refresh (auto-generated).
Introspect	Yes	Token introspection endpoint (auto-generated).
Revocation	Yes	Token revocation endpoint (auto-generated).
End Session	Yes	End session / logout endpoint (auto-generated).

User Info Claims

Field	Required	Description
User Info	Yes	UserInfo endpoint URL (auto-generated from Issuer).
Build User Info Claims SE	No	Dropdown to select a Service Extension for customizing UserInfo response claims.

JSON Web Keys

Field	Required	Description
JWKS	Yes	JWKS endpoint URL for publishing public keys (auto-generated from Issuer).
Edit JSON Web Keys	—	Button to edit private/public key pairs used for token signing.

Additional Settings

Field	Required	Description
Redis Cache	No	Dropdown to select a configured Redis cache. Defaults to in-memory if not set.
Session Correlation	No	Toggle to correlate OIDC sessions with HTTP sessions.

The Console UI provides a subset of the full YAML configuration. Options like buildUserInfoClaimsSE parameters, advanced JWKS algorithm settings, and per-app grant type selection are only available in YAML or at the app level. The Console auto-generates endpoints from the Issuer URL; in YAML, each endpoint is set independently.

The OIDC Provider mode requires two configuration levels: the oidcProvider top-level key for authorization server settings, and one or more apps entries with type: oidc for client applications.

version: 0.0.1

http:
  address: 0.0.0.0:443
  tls: server

tls:
  server:
    certFile: /etc/maverics/certs/server.pem
    keyFile: /etc/maverics/certs/server-key.pem
  upstream-idp:
    caFile: /etc/maverics/certs/ca.pem

session:
  cookie:
    name: auth_session
  lifetime:
    maxTimeout: 24h
    idleTimeout: 15m

connectors:
  - name: upstream-idp
    type: oidc
    tls: upstream-idp
    oidcWellKnownURL: https://idp.example.com/.well-known/openid-configuration
    oauthClientID: my-oidc-provider
    oauthClientSecret: <upstream_idp_client_secret>
    oauthLoginRedirect:
      urls:
        - https://auth.example.com/oidc-callback
    oauthLogoutRedirect:
      urls:
        - https://auth.example.com/logout
    scopes: openid profile email

oidcProvider:
  correlateSession: true
  discovery:
    issuer: https://auth.example.com
    endpoints:
      wellKnown: https://auth.example.com/.well-known/openid-configuration
      jwks: https://auth.example.com/oauth2/jwks
      auth: https://auth.example.com/oauth2/auth
      token: https://auth.example.com/oauth2/token
      userinfo: https://auth.example.com/oauth2/userinfo
      introspect: https://auth.example.com/oauth2/introspect
  jwks:
    - algorithm: RSA256
      publicKey: <oidc_signing_public_key>
      privateKey: <oidc_signing_private_key>

apps:
  - name: my-spa
    type: oidc
    clientID: my-spa
    credentials:
      secrets:
        - <my_spa_client_secret>
    redirectURLs:
      - https://spa.example.com/callback
    authentication:
      idps:
        - upstream-idp
    accessToken:
      type: jwt
    claimsMapping:
      email: upstream-idp.email
      name: upstream-idp.name

Configuration Reference

The oidcProvider top-level key configures the authorization server behavior shared across all OIDC apps. It defines the issuer identity, OIDC discovery endpoints, signing keys (JWKS), and optional session correlation. Every OIDC app served by this Orchestrator instance uses these provider-level settings.

Key	Type	Required	Description
`oidcProvider.discovery.issuer`	String	Yes	Issuer URL used in OIDC discovery and the `iss` claim in tokens
`oidcProvider.discovery.endpoints.wellKnown`	String	No	OIDC discovery endpoint path (typically `/.well-known/openid-configuration`)
`oidcProvider.discovery.endpoints.jwks`	String	No	JWKS endpoint path for publishing public keys
`oidcProvider.discovery.endpoints.auth`	String	No	Authorization endpoint path
`oidcProvider.discovery.endpoints.token`	String	No	Token endpoint path
`oidcProvider.discovery.endpoints.userinfo`	String	No	UserInfo endpoint path
`oidcProvider.discovery.endpoints.introspect`	String	No	Token introspection endpoint path (RFC 7662)
`oidcProvider.discovery.endpoints.revoke`	String	No	Token revocation endpoint path (RFC 7009)
`oidcProvider.discovery.endpoints.endSession`	String	No	End session (logout) endpoint path
`oidcProvider.jwks[].algorithm`	String	Yes	Signing algorithm (`RSA256` is the only supported value)
`oidcProvider.jwks[].publicKey`	String	No*	PEM-encoded public key. *Required for production. If omitted, the Orchestrator auto-generates an ephemeral key pair (not suitable for production).
`oidcProvider.jwks[].privateKey`	String	No*	PEM-encoded private key. *Required for production. If omitted, the Orchestrator auto-generates an ephemeral key pair (not suitable for production).
`oidcProvider.cache`	String	No	Name of a cache to use (references a `caches` entry)
`oidcProvider.correlateSession`	Boolean	No	Correlate OIDC sessions with HTTP sessions
`oidcProvider.buildUserInfoClaimsSE`	Object	No	Service extension for customizing the UserInfo response claims

If the jwks array is omitted, the Orchestrator auto-generates an RSA key pair at startup. This key pair is ephemeral — a new key pair is generated on every restart, invalidating all previously issued tokens. Auto-generation is intended only for local development and testing. Production deployments should always provide explicit keys using secret provider references (e.g., <oidc.signingPublicKey>, <oidc.signingPrivateKey>).

OIDC App Configuration

Each OIDC client application is registered under the apps array with type: oidc. App configuration includes client credentials, grant types, redirect URLs, claims mapping, token settings, DPoP, and CORS.

OIDC App

Full configuration reference, Console UI setup steps, and troubleshooting for OIDC apps

Key Rotation

The oidcProvider.jwks field is an array, supporting multiple key pairs for seamless key rotation. The first entry in the array is the active signing key used to sign new tokens. Additional entries are published in the JWKS endpoint so that resource servers can still verify tokens signed with previous keys.To rotate keys:

Generate a new key pair.
Insert the new key pair as the first entry in the jwks array.
Move the old key pair to a later position in the array.
Deploy the updated configuration. New tokens are signed with the new key; existing tokens remain verifiable.
After all tokens signed with the old key have expired, remove the old entry.

Key rotation is managed via YAML only. The Console UI allows editing the current JSON Web Keys through the Edit JSON Web Keys button in Deployment Settings, but multi-key rotation (maintaining old keys alongside new ones for seamless verification) requires direct YAML configuration.

oidcProvider:
  jwks:
    # Active signing key (signs new tokens)
    - algorithm: RSA256
      publicKey: <oidc_signing_public_key_new>
      privateKey: <oidc_signing_private_key_new>
    # Previous key (still published in JWKS for verification)
    - algorithm: RSA256
      publicKey: <oidc_signing_public_key_old>
      privateKey: <oidc_signing_private_key_old>

The OIDC Provider mode works with all Identity Fabric connectors. The Orchestrator translates between any upstream IdP protocol and OIDC tokens for your applications. These are the most commonly used pairings:

Microsoft Entra ID

Microsoft Entra ID for enterprise SSO

Okta

Okta SSO consolidation

Generic OIDC

Any OIDC-compliant provider

Continuity

IdP failover and migration

See the connector compatibility matrix for all supported pairings and the Identity Fabric overview for the full connector list. The OIDC Provider also pairs with:

Secret Providers — Store signing keys and client secrets securely
Caches — Distributed token and session storage with Redis

OIDC App

Client application configuration, setup steps, and troubleshooting for OIDC apps

SAML Provider

Configure the Orchestrator as a SAML 2.0 identity provider for federation

Identity Fabric

Connect upstream identity providers to the Orchestrator

Architecture and Concepts

Understand how modes fit into the Orchestrator architecture

HTTP Proxy

Protect applications without code modification using reverse proxy mode

Console Administration

Orchestration

Use Cases

How It Works

Key Concepts

Provider vs Apps

Claims Mapping

IdP Failover

Token Types

Service Extensions

Setup

Configuration Reference

OIDC App Configuration

OIDC App

Key Rotation

Microsoft Entra ID

Okta

Generic OIDC

Continuity

OIDC App

SAML Provider

Identity Fabric

Architecture and Concepts

HTTP Proxy

Console Administration

Orchestration

​Use Cases

​How It Works

​Key Concepts

​Provider vs Apps

​Claims Mapping

​IdP Failover

​Token Types

​Service Extensions

​Setup

​Configuration Reference

​OIDC App Configuration

OIDC App

​Key Rotation

​Related Integrations

Microsoft Entra ID

Okta

Generic OIDC

Continuity

​Related Pages

OIDC App

SAML Provider

Identity Fabric

Architecture and Concepts

HTTP Proxy

Use Cases

How It Works

Key Concepts

Provider vs Apps

Claims Mapping

IdP Failover

Token Types

Service Extensions

Setup

Configuration Reference

OIDC App Configuration

Key Rotation

Related Integrations

Related Pages