> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
**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:
1. **Application redirects** -- A user accesses an application registered as an OIDC relying party. The application redirects the user to the Orchestrator's authorization endpoint.
2. **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.
3. **Attribute enrichment** -- After authentication, the Orchestrator loads additional attributes from configured attribute providers (directories, databases, APIs) and enriches the user's profile.
4. **Token issuance** -- The Orchestrator generates OIDC tokens (ID token, access token, optional refresh token) with claims mapped from the authenticated identity and enriched attributes.
5. **Application receives tokens** -- The application receives the tokens at its redirect URI and uses them for session establishment and authorization decisions.
6. **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
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 open the JWK editor drawer, where keys are added, removed, and configured. |
| Use RFC 7638 thumbprint for key ID | No | Per-key toggle in the JWK editor. When on, the published key ID (`kid`) is the canonical [RFC 7638](https://datatracker.ietf.org/doc/html/rfc7638) JWK thumbprint; when off, a pre-RFC-7638 legacy `kid` is used for backward compatibility. New keys default to **on**. The toggle is only available when creating a key — changing the algorithm for an existing key requires deleting and recreating it in the editor, or managing the key in YAML. |
**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](/reference/orchestrator/applications/oidc). 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.
```yaml theme={null}
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:
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:
privateKey:
apps:
- name: my-spa
type: oidc
clientID: my-spa
credentials:
secrets:
-
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.jwks[].useRFC7638Thumbprint` | Boolean | No | Selects the key ID (`kid`) algorithm. Defaults to `false` (legacy, pre-RFC-7638 algorithm) for backward compatibility with deployments whose relying parties have already cached the legacy `kid`. Set to `true` to publish the canonical [RFC 7638](https://datatracker.ietf.org/doc/html/rfc7638) JWK thumbprint; recommended for new keys. Changing this on an in-use key changes the `kid`, which breaks relying parties that cache or pin it — rotate to a new key instead. |
| `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](/guides/security/secrets-management) references (e.g., ``, ``).
#### 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.
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:
1. Generate a new key pair.
2. Insert the new key pair as the first entry in the `jwks` array.
3. Move the old key pair to a later position in the array.
4. Deploy the updated configuration. New tokens are signed with the new key; existing tokens remain verifiable.
5. 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.
```yaml theme={null}
oidcProvider:
jwks:
# Active signing key (signs new tokens)
- algorithm: RSA256
publicKey:
privateKey:
useRFC7638Thumbprint: true
# Previous key (still published in JWKS for verification)
- algorithm: RSA256
publicKey:
privateKey:
```
## Related Integrations
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 for enterprise SSO
Okta SSO consolidation
Any OIDC-compliant provider
IdP failover and migration
See the [connector compatibility matrix](/guides/authentication/choosing-a-mode#connector-compatibility) for all supported pairings and the [Identity Fabric overview](/reference/orchestrator/identity-fabric) for the full connector list.
The OIDC Provider also pairs with:
* **[Secret Providers](/reference/orchestrator/configuration/secret-providers)** -- Store signing keys and client secrets securely
* **[Caches](/reference/orchestrator/caches)** -- Distributed token and session storage with Redis
## Related Pages
Client application configuration, setup steps, and troubleshooting for OIDC apps
Configure the Orchestrator as a SAML 2.0 identity provider for federation
Connect upstream identity providers to the Orchestrator
Understand how modes fit into the Orchestrator architecture
Protect applications without code modification using reverse proxy mode