> ## 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.

# 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.

> [!NOTE]
>
> **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**

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

1. Navigate to **Identity Fabric** in the Console sidebar.
2. Click **Create** and select **Generic OIDC Configuration**.
3. Enter a **Name** for the connector -- this is the friendly name that identifies your OIDC integration.
4. 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.
5. Enter the **OAuth Client ID** -- the client ID of the application registered with your identity provider.
6. Enter the **OAuth Client Secret** -- the client secret associated with the client ID. Use the show/hide toggle to verify the value.
7. 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.
8. Optionally add **Logout Callback URLs** -- the URL(s) that the OIDC provider calls after a successful logout.
9. Optionally enter **Scopes** -- space-separated OIDC scopes to request (e.g., `openid profile email`). If left empty, default scopes are used.
10. **Proof Key for Code Exchange (PKCE)** is enabled by default. Disable this toggle only if your provider is not configured to support PKCE.
11. 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.
12. Optionally configure **Error Handling** rules to redirect users based on errors returned by the IdP during the OIDC callback. See [Callback Error Handling](#callback-error-handling) for details.
13. Click **Save**.

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

**Configuration**

```yaml theme={null}
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>
    oauthLoginRedirect:
      urls:
        - 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 | Conditional | OAuth 2.0 client secret (use secret reference syntax). Required if `oauthClientAssertion` is not configured. |
| `oauthClientAssertion` | object | Conditional | Client assertion config for RFC 7523 private key JWT authentication. Required if `oauthClientSecret` is not configured. See [Client Assertion Authentication](#client-assertion-authentication). |
| `oauthClientAssertion.privateKey` | string | Yes | PEM-encoded RSA private key used to sign the assertion JWT. Use secret reference syntax. |
| `oauthClientAssertion.audience` | string | No | The `aud` claim in the assertion JWT. Defaults to the IdP's token endpoint URL. |
| `oauthLoginRedirect.urls` | list | Yes | Callback URL(s) registered with the identity provider. The Orchestrator selects the URL whose host matches the incoming request. |
| `oauthLogoutRedirect.urls` | list | No | URL(s) called by the identity provider after a successful logout. |
| `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](#callback-error-handling) below. |

For the complete field reference including health checks, offline access, and PKCE settings, see [Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference).

## Client Assertion Authentication

By default, the Generic OIDC connector authenticates to the identity provider using a client secret (`oauthClientSecret`). For providers that require stronger client authentication, you can use **RFC 7523 private key JWT** -- the connector signs a short-lived assertion JWT with an RSA private key instead of sending a shared secret.

Replace `oauthClientSecret` with an `oauthClientAssertion` block:

```yaml theme={null}
connectors:
  - name: my-idp
    type: oidc
    oidcWellKnownURL: https://idp.example.com/.well-known/openid-configuration
    oauthClientID: exampleClientID
    oauthClientAssertion:
      privateKey: <vault.oidc_private_key>
      audience: https://idp.example.com
    oauthLoginRedirect:
      urls:
        - https://app.example.com/oidc/callback
    oauthLogoutRedirect:
      urls:
        - https://app.example.com/logout
```

The `privateKey` value should be sourced from a secret provider. See [Secrets Management](/guides/security/secrets-management) for supported reference syntax.

## 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**

In the connector's **Error Handling** section:

1. Click **Add Rule** to create a new error handling rule.
2. Select a **Match On** value -- either **Error** or **Error Description** -- to choose which OIDC callback parameter to match against.
3. Select a **Match Type** -- either **Contains** (substring match) or **Equals** (exact match).
4. Enter the **Match Value** -- the string to match against the selected callback parameter.
5. Enter the **Redirect URL** -- the URL to redirect the user to when this rule matches.
6. 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.
7. Drag rules to reorder them -- rules are evaluated top to bottom and the first match wins.
8. Click **Save**.

**Configuration**

Rules are defined under `errorHandling.onCallbackError`:

```yaml theme={null}
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>
    oauthLoginRedirect:
      urls:
        - 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. |

> [!NOTE]
>
> 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 each URL in `oauthLoginRedirect.urls` matches exactly** what is registered in the identity provider
* **Check that the client secret reference resolves correctly** via your secret provider

## Related Pages

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Generic SAML](/reference/orchestrator/identity-fabric/custom-saml)**
>
> Generic SAML 2.0 connector

> **[Microsoft Entra ID](/reference/orchestrator/identity-fabric/azure-ad)**
>
> OIDC connector for Microsoft Entra ID

> **[Okta](/reference/orchestrator/identity-fabric/okta)**
>
> OIDC connector for Okta