Generic OIDC

The Generic OIDC connector provides a generic OpenID Connect integration for any OIDC-compliant identity provider — giving you flexibility to connect providers that don’t have a dedicated connector in the Orchestrator.

Console terminology: In the Maverics Console, this section is called Identity Fabric. The YAML configuration uses the connectors key to define identity provider integrations.

Overview

The Generic OIDC connector supports standard OpenID Connect discovery, authorization code flow, and token validation. It works with any identity provider that publishes an OIDC discovery document — making it suitable for non-standard providers, development/testing identity servers, and custom-built identity systems.

Use Cases

Unify SSO with any OIDC provider — Connect identity providers that don’t have a dedicated connector, extending SSO to legacy applications through any standards-compliant IdP
Rationalize custom identity systems — Integrate in-house or niche identity services into a unified orchestration layer, enabling gradual migration to a strategic IdP without rewriting applications
Identity resilience with secondary providers — Add any OIDC-compliant provider as a failover target, ensuring authentication continuity regardless of which providers are in your Identity Fabric
Development and testing — Integrate with local identity servers like Dex or mock OIDC providers to validate orchestration policies before deploying to production

Setup

Console UI
Configuration

To create a Generic OIDC Configuration connector in the Maverics Console:

Navigate to Identity Fabric in the Console sidebar.
Click Create and select Generic OIDC Configuration.
Enter a Name for the connector — this is the friendly name that identifies your OIDC integration.
Enter the OIDC Well Known URL — the URL that returns OpenID Connect metadata about the authorization server (typically ending in /.well-known/openid-configuration). This works with any OIDC-compliant provider.
Enter the OAuth Client ID — the client ID of the application registered with your identity provider.
Enter the OAuth Client Secret — the client secret associated with the client ID. Use the show/hide toggle to verify the value.
Add one or more Redirect URLs — the callback URL(s) where the provider redirects users after authentication. The Maverics OIDC handler will be served on this URL.
Optionally add Logout Callback URLs — the URL(s) that the OIDC provider calls after a successful logout.
Optionally enter Scopes — space-separated OIDC scopes to request (e.g., openid profile email). If left empty, default scopes are used.
Proof Key for Code Exchange (PKCE) is enabled by default. Disable this toggle only if your provider is not configured to support PKCE.
Optionally enable Offline Access if you need refresh tokens. When enabled, set your policy’s decision.lifetime slightly longer than the interval for token refreshing.
Optionally configure Error Handling rules to redirect users based on errors returned by the IdP during the OIDC callback. See Callback Error Handling for details.
Click Save.

The Generic OIDC Configuration works with any identity provider that publishes a standard OIDC discovery document — including Keycloak, Dex, IdentityServer, and other custom OIDC implementations. If your provider has a dedicated connector type in the Console (e.g., Okta, Entra ID), prefer using that instead for provider-specific optimizations.

connectors:
  - name: my-idp
    type: oidc
    oidcWellKnownURL: "https://idp.example.com/.well-known/openid-configuration"
    oauthClientID: "{{ env.OIDC_CLIENT_ID }}"
    oauthClientSecret: <vault.oidc_client_secret>
    oauthRedirectURL: "https://app.example.com/oidc/callback"
    scopes: "openid profile email"

Configuration Reference

Key	Type	Required	Description
`name`	string	Yes	Unique connector identifier referenced in app policies
`type`	string	Yes	Must be `oidc`
`oidcWellKnownURL`	string	Yes	OIDC discovery endpoint URL
`oauthClientID`	string	Yes	OAuth 2.0 client ID from the identity provider
`oauthClientSecret`	string	Yes	OAuth 2.0 client secret (use secret reference syntax)
`oauthRedirectURL`	string	Yes	Callback URL registered with the identity provider
`scopes`	string	No	Space-separated OAuth scopes (default: `openid profile email`)
`tls`	string	No	Named TLS profile for provider communication
`errorHandling`	object	No	Configures how IdP errors during the OIDC callback are handled. See Callback Error Handling below.

For the complete field reference including health checks, offline access, and PKCE settings, see Identity Fabric.

Callback Error Handling

When an identity provider returns an error during the OIDC callback (e.g., the user forgot their password, cancelled login, or the provider encountered a server error), the Orchestrator can evaluate configurable rules to redirect the user to a specific URL based on the error. Rules are evaluated in order — the first matching rule wins. You can match on the error or error_description callback parameters using exact or substring matching. A default catch-all rule can be included to handle any unmatched errors.

Console UI
Configuration

In the connector’s Error Handling section:

Click Add Rule to create a new error handling rule.
Select a Match On value — either Error or Error Description — to choose which OIDC callback parameter to match against.
Select a Match Type — either Contains (substring match) or Equals (exact match).
Enter the Match Value — the string to match against the selected callback parameter.
Enter the Redirect URL — the URL to redirect the user to when this rule matches.
Optionally check Default to make a rule the catch-all for any unmatched errors. A default rule does not require Match On, Match Type, or Match Value fields. Only one default rule is allowed.
Drag rules to reorder them — rules are evaluated top to bottom and the first match wins.
Click Save.

Rules are defined under errorHandling.onCallbackError:

connectors:
  - name: my-idp
    type: oidc
    oidcWellKnownURL: "https://idp.example.com/.well-known/openid-configuration"
    oauthClientID: "{{ env.OIDC_CLIENT_ID }}"
    oauthClientSecret: <vault.oidc_client_secret>
    oauthRedirectURL: "https://app.example.com/oidc/callback"
    errorHandling:
      onCallbackError:
        - contains: "AADB2C90118"
          matchOn: error_description
          redirectURL: "https://app.example.com/password-reset"
        - equals: server_error
          matchOn: error
          redirectURL: "https://app.example.com/error"
        - default: true
          redirectURL: "https://app.example.com/generic-error"

Rule Reference

Each rule in the onCallbackError list supports the following fields:

Key	Type	Required	Description
`contains`	string	Conditional	Matches when the target field contains this substring. Mutually exclusive with `equals`. Required unless `default` is `true`.
`equals`	string	Conditional	Matches when the target field exactly equals this value. Mutually exclusive with `contains`. Required unless `default` is `true`.
`matchOn`	string	Conditional	Which callback parameter to match against. Must be `error` or `error_description`. Required unless `default` is `true`.
`redirectURL`	string	Yes	The URL to redirect the user to when the rule matches.
`default`	boolean	No	When `true`, this rule acts as a catch-all for any error not matched by prior rules. When set, `contains`, `equals`, and `matchOn` must not be defined. Only one default rule is allowed.

If no rule matches the error and no default rule is defined, the Orchestrator falls back to the standard error handling behavior.

Troubleshooting

Verify the oidcWellKnownURL is accessible from the Orchestrator host — confirm the provider’s discovery document returns valid JSON
Ensure the oauthRedirectURL matches exactly what is registered in the identity provider
Check that the client secret reference resolves correctly via your secret provider

Identity Fabric

Overview of all identity providers

Generic SAML

Generic SAML 2.0 connector

Microsoft Entra ID

OIDC connector for Microsoft Entra ID

Okta

OIDC connector for Okta

Console Administration

Orchestration

Overview

Use Cases

Setup

Configuration Reference

Callback Error Handling

Rule Reference

Troubleshooting

Identity Fabric

Generic SAML

Microsoft Entra ID

Okta

Console Administration

Orchestration

​Overview

​Use Cases

​Setup

​Configuration Reference

​Callback Error Handling

​Rule Reference

​Troubleshooting

​Related Pages

Identity Fabric

Generic SAML

Microsoft Entra ID

Okta

Overview

Use Cases

Setup

Configuration Reference

Callback Error Handling

Rule Reference

Troubleshooting

Related Pages