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 (Azure AD, 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 oidcProvider block configures server-wide settings (issuer, endpoints, signing keys) shared across all OIDC apps. Each apps[] entry with type: oidc registers 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.

Interface

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.

Supported Grant TypesThe Console shows toggles for the following grant types: authorization_code, client_credentials, refresh_token, password, implicit_id, implicit_token.

The Console UI provides a subset of the full YAML configuration. Options like buildUserInfoClaimsSE parameters and advanced JWKS algorithm settings are only available in the Configuration tab. 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

oidcProvider

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 Type (`apps[].type: oidc`)

Each OIDC app entry defines a relying party (client application) registered with the OIDC Provider. Apps are configured under the apps array with type: oidc. For shared app fields (name, type) and authorization rule syntax, see the Apps and Routes reference. Core Fields

Key	Type	Required	Description
`clientID`	String	Yes	Unique client identifier for the OIDC relying party
`public`	Boolean	No	When `true`, marks the client as a public client (no client secret required)
`credentials.secrets`	Array	No	Client secrets used for client authentication
`credentials.jwtPublicKeys[].name`	String	No	Name identifier for a JWT-based client authentication key
`credentials.jwtPublicKeys[].aud`	String	No	Expected audience value for the client JWT assertion
`credentials.jwtPublicKeys[].publicKey`	String	No	PEM-encoded public key for verifying client JWT assertions (RFC 7523)

DPoP (Demonstrating Proof-of-Possession)

Key	Type	Required	Description
`dpop.enabled`	Boolean	No	Enable DPoP sender-bound access tokens (RFC 9449)
`dpop.nonce.disabled`	Boolean	No	When `true`, disables the DPoP nonce requirement

Grant Types and URLs

Key	Type	Required	Description
`grantTypes`	Array	No	Allowed OAuth 2.0 grant types. Defaults to `authorization_code`, `client_credentials`, `refresh_token`. Also supports `urn:ietf:params:oauth:grant-type:token-exchange` (RFC 8693) and `password` (ROPC).
`redirectURLs`	Array	No	Allowed redirect URIs for authorization code flow
`logoutRedirectURLs`	Array	No	Allowed redirect URIs after logout
`allowDefaultRedirectURI`	Boolean	No	Allow a default redirect URI when none is supplied in the request

Claims and Scopes

Key	Type	Required	Description
`claimsMapping`	Object	No	Map connector attributes to OIDC claims. Keys are claim names, values are `connector.attribute` references (e.g., `email: upstream-idp.email`).
`customScopes.scopes[].name`	String	No	Define custom OAuth scopes beyond the standard set
`allowedAudiences`	Array	No	Restrict which audience values are permitted in token requests

Authentication

Key	Type	Required	Description
`authentication.idps`	Array	No	List of identity provider connector names for user authentication
`authentication.isAuthenticatedSE`	Object	No	Service extension for custom authentication checks
`authentication.authenticateSE`	Object	No	Service extension for custom authentication flows
`authentication.backchannel.authenticateSE`	Object	No	Service extension for backchannel authentication (used with the `password` grant type)

isAuthenticatedSE and authenticateSE must be defined together. When using SE-based authentication, you cannot also specify idps.

Authorization

Key	Type	Required	Description
`authorization.allowAll`	Boolean	No	Allow all authenticated users
`authorization.rules`	Array	No	Authorization rules with `and`/`or` conditions. See Apps and Routes for rule syntax.
`authorization.rulesAggregationMethod`	String	No	How to combine top-level rules: `and` (all must pass) or `or` (any may pass)
`authorization.tokenMinting.accessToken.policies`	Array	No	OPA policies for access token minting. Each entry has `name`, `file` (or `rego`).

Access Tokens

Key	Type	Required	Description
`accessToken.type`	String	No	Token format: `jwt` (signed JSON Web Token) or `opaque` (random string reference token)
`accessToken.length`	Integer	No	Length of opaque access tokens (22—256). Only applies when `accessToken.type` is `opaque`.
`accessToken.lifetimeSeconds`	Integer	No	Access token lifetime in seconds

Refresh Tokens

Key	Type	Required	Description
`refreshToken.allowOfflineAccess`	Boolean	No	Enable refresh tokens for this client
`refreshToken.length`	Integer	No	Refresh token length (22—256)
`refreshToken.lifetimeSeconds`	Integer	No	Refresh token lifetime in seconds

Attribute Providers and Service Extensions

Key	Type	Required	Description
`attrProviders[].connector`	String	No	Connector name for loading additional attributes after authentication
`attrProviders[].usernameMapping`	String	No	Template mapping for the username lookup (e.g., `{{ azure.sub }}`)
`loadAttrsSE`	Object	No	Service extension for custom attribute loading
`buildIDTokenClaimsSE`	Object	No	Service extension for customizing ID token claims
`buildAccessTokenClaimsSE`	Object	No	Service extension for customizing access token claims

CORS

Key	Type	Required	Description
`cors.allowedOrigins`	Array	No	Allowed CORS origins for browser-based OIDC flows
`cors.allowedCredentials`	Boolean	No	Allow credentials in CORS requests

Security

Key	Type	Required	Description
`insecureSkipPKCE`	Boolean	No	Disable PKCE requirement. Not recommended — PKCE protects against authorization code interception attacks.

DPoP (Demonstrating Proof-of-Possession)

DPoP (RFC 9449) creates sender-bound access tokens — the token is cryptographically tied to a specific client’s key pair, preventing token theft and replay attacks. When a client presents a DPoP-bound access token, it must also present a proof that it possesses the private key. If an attacker intercepts the access token, they cannot use it without the client’s private key. DPoP is configured per-app on OIDC Provider applications. When enabled, the Orchestrator validates DPoP proof headers on token requests and issues sender-bound access tokens.

Console UI
Configuration

DPoP is configured per-app via YAML only. The Console UI manages primary OIDC Provider settings (issuer, endpoints, signing keys) in the Deployment Settings dialog, but per-app token binding settings like DPoP are not yet available in the Console. See the Configuration tab for the full reference.

apps:
  - name: my-secure-client
    type: oidc
    clientID: my-secure-client
    credentials:
      secrets:
        - <my_secure_client_secret>
    dpop:
      enabled: true
      nonce:
        disabled: false  # nonce required by default
    accessToken:
      type: jwt
      lifetimeSeconds: 3600
    authentication:
      idps:
        - upstream-idp

Key	Type	Default	Description
`dpop.enabled`	Boolean	`false`	Enable DPoP sender-bound access tokens per RFC 9449. When enabled, the Orchestrator validates DPoP proof headers and binds issued tokens to the client’s public key.
`dpop.nonce.disabled`	Boolean	`false`	When `false` (the default), the Orchestrator requires a server-issued nonce in DPoP proofs. This prevents pre-generated proof replay. Set to `true` to disable the nonce requirement.

DPoP provides defense against token exfiltration attacks. Even if an access token is stolen from a log, cache, or network trace, it cannot be used without the corresponding private key. For maximum security, combine DPoP with short token lifetimes and TLS for transport-level protection.

JWT and Opaque Token Options

The accessToken.type field controls whether the OIDC Provider issues JWT tokens or opaque (reference) tokens:

JWT tokens (accessToken.type: jwt) — Self-contained tokens that include claims directly. Resource servers can validate them locally using the JWKS endpoint without calling back to the provider. This is the most common choice for APIs and modern applications.
Opaque tokens (accessToken.type: opaque) — Random string tokens that carry no claims. Resource servers must call the introspection endpoint to validate them. Use opaque tokens when you need to revoke tokens immediately or avoid exposing claims to intermediate services.

Console UI
Configuration

Per-app token type settings (JWT vs. opaque) are configured via YAML only. The Console UI manages provider-level OIDC settings (issuer, endpoints, signing keys) in the Deployment Settings dialog, but per-app access token format and lifetime are not yet available in the Console. See the Configuration tab for the full reference.

# JWT access tokens (self-contained, validated via JWKS)
apps:
  - name: my-api-client
    type: oidc
    clientID: my-api-client
    accessToken:
      type: jwt
      lifetimeSeconds: 3600

# Opaque access tokens (reference tokens, validated via introspection)
  - name: my-internal-client
    type: oidc
    clientID: my-internal-client
    accessToken:
      type: opaque
      length: 32
      lifetimeSeconds: 3600

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.

Console UI
Configuration

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. See the Configuration tab for the full reference.

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:

Azure AD

Microsoft Entra ID for enterprise SSO

Okta

Okta SSO consolidation

Custom 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

Troubleshooting

Token validation fails at the application

Symptoms: The application rejects tokens with “invalid signature”, “unable to verify token”, or similar errors.Causes:

The JWKS endpoint is unreachable from the application’s network.
A key mismatch occurred after key rotation — the application cached an old JWKS response.
The oidcProvider.discovery.issuer URL does not match the iss claim the application expects.

Resolution:

Verify that oidcProvider.discovery.issuer matches exactly what the application has configured as the issuer (including scheme, host, and path).
Confirm the JWKS endpoint is accessible from the application by requesting <issuer>/.well-known/openid-configuration and following the jwks_uri.
If you recently rotated keys, ensure the active signing key is the first entry in the jwks array and that old keys are still present for verification of previously issued tokens.

Redirect URI mismatch

Symptoms: Users see a “redirect_uri_mismatch” or “invalid redirect URI” error during the login flow.Causes:

The redirect URL sent by the application is not listed in the app’s redirectURLs array.
A subtle mismatch in scheme (http vs. https), port, or trailing slash between the configured and requested redirect URI.

Resolution:

Add the exact redirect URI (including scheme, host, port, and path) to apps[].redirectURLs in the OIDC app configuration.
Compare the redirect URI in the browser’s address bar during the error with the configured values — they must match character-for-character.

Claims missing from tokens

Symptoms: The application receives a valid token but expected claims (e.g., email, groups) are empty or absent.Causes:

The claimsMapping references a wrong connector name or attribute that does not exist on the upstream identity.
Attribute providers (attrProviders) are not configured, so enrichment attributes are not loaded.
The upstream IdP does not return the expected attributes in its token or UserInfo response.

Resolution:

Verify that connector names in claimsMapping match the connectors[].name values exactly.
If enrichment is needed, confirm attrProviders entries are configured with the correct connector names and usernameMapping.
Test the upstream IdP directly to confirm it returns the expected attributes.

IdP failover not working

Symptoms: Authentication fails when the primary IdP is down instead of falling back to a secondary IdP.Causes:

Only one IdP is listed in authentication.idps — there is no fallback configured.
The secondary IdP connector is misconfigured (wrong URL, expired credentials, network issue).

Resolution:

Verify that multiple IdP connector names are listed in authentication.idps in the desired failover order.
Test each connector independently by temporarily making it the only entry to confirm it works on its own.
Check Orchestrator logs for connector-specific error messages when failover is attempted.

Ephemeral key warning / tokens invalidated on restart

Symptoms: All previously issued tokens become invalid after an Orchestrator restart. Logs may show a warning about ephemeral key generation.Causes:

The jwks array is omitted from oidcProvider, so the Orchestrator auto-generates an ephemeral RSA key pair on every startup. Each restart produces new keys, invalidating tokens signed with the previous keys.

Resolution:

Provide explicit signing keys in the oidcProvider.jwks array using secret provider references (e.g., <oidc.signingPublicKey>, <oidc.signingPrivateKey>).
Ensure both publicKey and privateKey are set for at least one entry in the jwks array.

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

Interface

Configuration Reference

oidcProvider

OIDC App Type (`apps[].type: oidc`)

DPoP (Demonstrating Proof-of-Possession)

JWT and Opaque Token Options

Key Rotation

Azure AD

Okta

Custom OIDC

Continuity

Troubleshooting

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

​Interface

​Configuration Reference

​oidcProvider

​OIDC App Type (apps[].type: oidc)

​DPoP (Demonstrating Proof-of-Possession)

​JWT and Opaque Token Options

​Key Rotation

​Related Integrations

Azure AD

Okta

Custom OIDC

Continuity

​Troubleshooting

​Related Pages

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

Interface

Configuration Reference

oidcProvider

OIDC App Type (`apps[].type: oidc`)

DPoP (Demonstrating Proof-of-Possession)

JWT and Opaque Token Options

Key Rotation

Related Integrations

Troubleshooting

Related Pages