OIDC App

Register OpenID Connect clients with the Orchestrator’s built-in OIDC Provider. The Orchestrator acts as an authorization server, handling authentication flows, enriching claims from multiple identity sources, and providing seamless IdP failover — all without changes to your OIDC-compatible applications.

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[].

Overview

An OIDC app registers an OpenID Connect client with the Orchestrator’s OIDC Provider mode. Each app entry defines a client with its own credentials, redirect URLs, grant types, and token settings. The Orchestrator issues ID tokens, access tokens, and refresh tokens to registered clients, acting as a standards-compliant authorization server.

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.

Use Cases

SSO consolidation — Unify multiple IdPs behind a single OIDC interface so applications authenticate against one provider.
IdP migration with zero downtime — Move users between identity providers transparently while applications continue to use the same OIDC endpoints.
Legacy app modernization — Add OIDC-based authentication to older applications without rewriting them.
Claim enrichment from multiple sources — Combine attributes from multiple Identity Fabric connectors into a single set of OIDC claims.

Key Concepts

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

OIDC applications are configured under Applications in the Maverics Console.

Navigate to Applications

Go to Applications in the sidebar and click Create. Select OIDC-based from the application type list.

Set the application name

Enter a Name to identify this OIDC application.

Configure client credentials

Enter the Client ID that OIDC clients will use to authenticate. Choose the Client Authentication Method: Client Secret or JWT Client Authentication (RFC 7523).If using client secrets, click Add Client Secret to add one or more secrets.

Store client secrets in a secret provider rather than entering them directly. Use secret reference syntax (e.g., <vault.client_secret>) so the Orchestrator resolves the value at runtime.

Configure redirect URLs

Click Add Redirect URL to add allowed redirect URLs for the authorization code flow. Optionally enable Default Redirect URL (Fallback) to use the first URL when authorization requests omit the redirect_uri parameter.

Per the OIDC RFC, redirect_uri is a required parameter. Only enable the fallback for apps that cannot provide a redirect URI.

Configure logout redirect URLs

Click Logout Redirect URL to add URLs where logout responses can be sent.

Configure security settings

Enable Public Client for single-page or native applications that cannot securely store credentials. Public clients support Authorization Code (with PKCE), Refresh Token, and Implicit flows only.

Configure DPoP (optional)

Enable Require DPoP (Demonstrating Proof of Possession) if clients must provide DPoP proofs. DPoP proofs must include a nonce claim per RFC 9449.

Configure CORS

Click Allowed Origins to add origins authorized to make cross-origin requests. Enable Include Credentials to include credentials in CORS response headers (only for trusted origins you control).

Configure PKCE

Enable Bypass Proof Key for Code Exchange (PKCE) only for legacy apps that cannot use PKCE. Per OAuth 2.0 security best practices, public clients MUST use PKCE with the Authorization Code grant type.

Select grant types

Choose which grant types this client supports.Recommended and Modern Flows: Authorization Code, Refresh Token.Machine to Machine and Agentic Flows: Client Credentials, Token Exchange.Legacy or Deprecated Flows: ROPC, Implicit (ID Token), Implicit (Access Token).

Configure audiences (optional)

Click Allowed Audience to specify which resources are authorized to receive tokens.

Configure access token settings

Select the token Type (JWT or opaque). Optionally set Lifetime Seconds (default: 1 hour) and Length (for opaque tokens, 22—256 characters).

Configure refresh token settings

Enable Allow Offline Access to allow refresh tokens. Optionally set Lifetime Seconds (default: 24 hours) and Length (22—256 characters).

Save

Click Save to create the OIDC application.

OIDC apps are defined under the apps key with type: oidc. For shared app fields (name, type) and authorization rule syntax, see the Applications reference.

Configuration 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)

The clientSecret field is deprecated. Use credentials.secrets instead to support multiple secrets and secret rotation.

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 Applications for rule syntax.
`authorization.rulesAggregationMethod`	String	No	How to combine top-level rules: `and` (all must pass) or `or` (any may pass)
`authorization.isAuthorizedSE`	Object	No	Service Extension for custom authorization logic. Mutually exclusive with `allowAll` and `rules`.
`authorization.unauthorizedPage`	String	No	Redirect URL for unauthorized users
`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.

Example

A complete OIDC app with authorization code flow, claim enrichment, and refresh tokens:

apps:
  - name: employee-portal
    type: oidc
    clientID: employee-portal-client
    credentials:
      secrets:
        - <vault.employee_portal_secret>
    grantTypes:
      - authorization_code
      - refresh_token
    redirectURLs:
      - https://portal.example.com/callback
    claimsMapping:
      email: azure.preferred_username
      name: azure.name
      groups: azure.groups
    accessToken:
      type: jwt
      lifetimeSeconds: 3600
    refreshToken:
      allowOfflineAccess: true
    cors:
      allowedOrigins:
        - https://portal.example.com

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

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.

Applications

Overview of application types and routing configuration

OIDC Provider

Configure the Orchestrator as an OIDC authorization server

Identity Fabric

Connect identity sources for claim enrichment and IdP failover

Sessions

Session storage and lifecycle configuration

Console Administration

Orchestration

Overview

How It Works

Use Cases

Key Concepts

Claims Mapping

IdP Failover

Token Types

Service Extensions

Setup

Configuration Reference

Example

DPoP (Demonstrating Proof-of-Possession)

JWT and Opaque Token Options

Troubleshooting

Applications

OIDC Provider

Identity Fabric

Sessions

Console Administration

Orchestration

​Overview

​How It Works

​Use Cases

​Key Concepts

​Claims Mapping

​IdP Failover

​Token Types

​Service Extensions

​Setup

​Configuration Reference

​Example

​DPoP (Demonstrating Proof-of-Possession)

​JWT and Opaque Token Options

​Troubleshooting

​Related Pages

Applications

OIDC Provider

Identity Fabric

Sessions

Overview

How It Works

Use Cases

Key Concepts

Claims Mapping

IdP Failover

Token Types

Service Extensions

Setup

Configuration Reference

Example

DPoP (Demonstrating Proof-of-Possession)

JWT and Opaque Token Options

Troubleshooting

Related Pages