SSO with OIDC

By the end of this guide, you will have a running Maverics Orchestrator configured as an OIDC Provider — authenticating users through your identity provider and issuing tokens to your application.

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

Prerequisites

A running Maverics Orchestrator — If you have not installed the Orchestrator yet, follow the Quick Start guide or see the installation reference.
An identity provider account — You need credentials for an identity provider such as Azure AD, Okta, or Auth0. While this guide demonstrates an OIDC connector, the Orchestrator supports OIDC, SAML, and LDAP connectors, so your IdP does not need to support OIDC specifically.
A target application — Any web application that accepts OIDC tokens or that you want to protect with OIDC-based single sign-on.

Configure SSO

Create an Orchestrator Deployment

In the Maverics Console, all configuration lives within a Deployment — a managed Orchestrator instance with its own configuration, storage provider, and signing keys. Before you can create identity connectors, applications, or user flows, you need a Deployment to hold them.

Console UI
Configuration

Log in to the Maverics Console.
Navigate to Deployments in the sidebar and click Create.
Enter a name for your deployment (e.g., OIDC SSO).
Select a deployment provider. The Console supports several options:
- Evaluation — Strata-managed storage, no infrastructure needed. Best for getting started.
- AWS S3, Azure Blob Storage, or Google Cloud Storage — customer-managed cloud storage for production.
- GitHub or GitLab — deploy bundles to a Git repository.
- Download Only — manual bundle download for air-gapped environments.
See Publishing Deployment Configs overview for provider setup details.
Click Create.

Your new deployment opens automatically. You can now configure identity connectors, applications, and user flows within it.

When using direct configuration, no deployment setup is needed — configuration is defined directly in the maverics.yaml file and delivered to the Orchestrator via the -config flag or MAVERICS_CONFIG environment variable. See Installation for details on configuration delivery options.

Configure the OIDC Provider

The OIDC Provider must be enabled and configured at the deployment level before creating applications. This sets up the issuer identity, endpoints, and signing keys that all OIDC applications in the deployment share.

Console UI
Configuration

Open your deployment and click the gear icon in the sidebar to open Deployment Settings.
Find the OIDC Provider section.
Enter the Issuer URL (e.g., https://your-orchestrator.example.com). This becomes the iss claim in all issued tokens.
Click Generate to auto-populate the Well-Known, Authorization, Token, Introspect, Revocation, End Session, UserInfo, and JWKS endpoint URLs from the Issuer.
Under JSON Web Keys, click Edit JSON Web Keys to configure the signing key pair used for token signing.
Click Save.

If JSON Web Keys are left blank, the Orchestrator auto-generates a signing key pair at startup. This key pair is ephemeral — a new one is created every time the Orchestrator restarts, which means all previously issued tokens become unverifiable. Only rely on auto-generated keys for local development and testing. For production, always configure explicit signing keys managed by a secret provider.

The OIDC Provider Deployment Settings fields are documented in detail in the OIDC Provider reference. Use the Console UI tab there for field-by-field descriptions.

In YAML, the OIDC Provider is configured via the oidcProvider top-level key. This is shown in the next step alongside the application configuration.

If the jwks array is omitted from oidcProvider, the Orchestrator auto-generates a signing key pair at startup. This key pair is ephemeral — it is regenerated on every restart, invalidating all previously issued tokens. For production deployments, always provide explicit keys using secret provider references (e.g., <oidc.signingPublicKey>).

Connect your identity provider

An identity provider (IdP) is the service that manages your user accounts and handles login — think Azure AD (now Microsoft Entra ID), Okta, or Google Workspace. Connecting the Orchestrator to your IdP tells it where to send users when they need to authenticate.The Orchestrator uses Identity Fabric connectors to communicate with your IdP. This guide demonstrates an OIDC connector, but the connector protocol is independent of the Orchestrator’s mode — even though the Orchestrator is serving OIDC to your application, the IdP connector can use OIDC, SAML, or LDAP. The Orchestrator handles the protocol translation between your IdP and your application.You will need your IdP’s client ID, client secret, and discovery URL (sometimes called the issuer URL or well-known endpoint). These credentials allow the Orchestrator to establish a trust relationship with your provider.

Console UI
Configuration

Navigate to Identity Fabric in the sidebar and click Create.
Select your identity provider from the list. Choose a provider-specific option (such as Okta (OIDC), Microsoft Entra ID (OIDC), or Auth0 (OIDC)) or select Generic OIDC Configuration for any OIDC-compliant provider. SAML and LDAP connector options are also available — this guide demonstrates the OIDC connector path, but any connector type is valid here.
Fill in the connector form:

Field	Required	Description
Name	Yes	A friendly name for your identity provider (e.g., `my-idp`).
OIDC Well Known URL	Yes	Your IdP’s OIDC discovery endpoint (e.g., `https://your-idp.example.com/.well-known/openid-configuration`).
OAuth Client ID	Yes	The client ID from the application you registered in your IdP for Maverics.
Client Authentication Method	Yes	Select OAuth Client Secret (default) or OAuth JWT Client Authentication.
OAuth Client Secret	Yes	The client secret from your IdP. For production, use a secret provider.
Redirect URLs	Yes	The callback URL where your IdP redirects after authentication (e.g., `https://your-orchestrator.example.com/oidc-callback`).
Scopes	No	Space-separated OIDC scopes (e.g., `openid profile email`).

The PKCE toggle is enabled by default. Disable it only if your IdP does not support Proof Key for Code Exchange.

Click Save.

Define an OIDC connector in the connectors section of your maverics.yaml file. The connector specifies how the Orchestrator communicates with your identity provider.

maverics.yaml

connectors:
  - name: my-idp
    type: oidc
    oidcWellKnownURL: https://your-idp.example.com/.well-known/openid-configuration
    oauthClientID: your-orchestrator-client-id
    oauthClientSecret: <idp.clientSecret>
    oauthLoginRedirect:
      urls:
        - https://your-orchestrator.example.com/oidc-callback
    oauthLogoutRedirect:
      urls:
        - https://your-orchestrator.example.com/logout
    disablePKCE: false
    scopes: openid profile email

Replace your-idp.example.com with your identity provider’s domain. The oidcWellKnownURL points to the OIDC discovery endpoint, which provides the Orchestrator with all of the IdP’s endpoints and signing keys automatically.The oauthClientSecret uses the <idp.clientSecret> secret reference syntax — the Orchestrator retrieves this value at runtime from your secret provider rather than reading a plaintext value from the config file.

Not sure which connector to use? The Identity Fabric overview includes a comparison table mapping each connector to its supported protocols and use cases.

Protocol translation: This guide shows an OIDC connector, but the Orchestrator can connect to your IdP using any supported protocol — OIDC, SAML, or LDAP. The Orchestrator’s mode (OIDC Provider) determines what protocol your application speaks. The connector determines what protocol your IdP speaks. These are independent — you can connect a SAML-only IdP and the Orchestrator will translate to OIDC for your application. See the Identity Fabric overview for all connector types.

Define your application

Next, register your application with the Orchestrator’s OIDC Provider. This tells the Orchestrator which application will receive OIDC tokens and how to handle the authentication flow.You configure a client ID and secret for your application (separate from the IdP credentials above), the redirect URLs your application accepts after authentication, and which identity connector to use for authenticating users.

Console UI
Configuration

In the Console, defining your application is split across two steps: creating the OIDC application and then creating a User Flow that connects the application to your identity provider.Create the application:

Navigate to Applications in the sidebar and click Create.
Select OIDC-based.
Fill in the application form:

Field	Required	Description
Name	Yes	A friendly name for your application (e.g., `my-web-app`).
Client ID	Yes	The client identifier your application will use to authenticate with the Orchestrator.
Client Secret	Yes	Click Add Client Secret and enter a secret. Your application will use this to authenticate token requests.
Redirect URL	Yes	Click Add Redirect URL and enter the callback URL your application accepts after authentication (e.g., `https://your-app.example.com/callback`).

The default grant types (Authorization Code, Refresh Token, and Client Credentials) work for most applications. Under Access Token Settings, the token type defaults to JWT.

Click Save.

Store application client secrets using the <namespace.key> secret reference syntax rather than plaintext values. See Secrets Management for setup instructions.

Create a User Flow to connect the application to your IdP:

Navigate to User Flows in the sidebar and click Create.
Enter a name for the User Flow and select your application from the dropdown, then click Create.
On the User Flow page, find the Sign On Policy card and click Edit.
Under Authentication, select your identity provider from the Select an authentication source dropdown. This is the connector you created in the previous step.
Click Save.

Define the OIDC Provider and register your application in the apps section. The authentication.idps array binds the connector from the previous step to this application.

maverics.yaml

oidcProvider:
  discovery:
    issuer: https://your-orchestrator.example.com
    endpoints:
      wellKnown: https://your-orchestrator.example.com/.well-known/openid-configuration
      jwks: https://your-orchestrator.example.com/oauth2/jwks
      auth: https://your-orchestrator.example.com/oauth2/auth
      token: https://your-orchestrator.example.com/oauth2/token
      userinfo: https://your-orchestrator.example.com/oauth2/userinfo
      introspect: https://your-orchestrator.example.com/oauth2/introspect
  jwks:
    - algorithm: RSA256
      publicKey: <oidc.signingPublicKey>
      privateKey: <oidc.signingPrivateKey>

apps:
  - name: my-web-app
    type: oidc
    clientID: my-web-app
    credentials:
      secrets:
        - <app.clientSecret>
    redirectURLs:
      - https://your-app.example.com/callback
    authentication:
      idps:
        - my-idp
    accessToken:
      type: jwt

The authentication.idps array references the connector name from the previous step (my-idp). When a user accesses your application, the Orchestrator redirects them to that IdP for authentication.The credentials.secrets array uses secret references so your application’s client secret is never stored in plaintext. The accessToken.type can be jwt (self-contained tokens) or opaque (reference tokens that require introspection).

Configure claim mapping

Claims are pieces of identity information about the user — their email address, display name, group memberships, roles, and any custom attributes your IdP provides. When the Orchestrator acts as an OIDC Provider, it issues tokens to your application that contain these claims.Claim mapping lets you control which identity attributes from your IdP end up in the tokens your application receives. You can rename claims (so your app sees email instead of preferred_username), filter out unnecessary data, or combine claims from multiple sources.This is where the Orchestrator’s protocol translation becomes powerful — your IdP might use one claim format, but your application expects another. The Orchestrator handles the translation so neither side needs to change.

Console UI
Configuration

Open the User Flow you created in the previous step.
Find the Claims and OAuth 2.0 Scopes card and click Edit claims.
Under Attribute to Standard OIDC Claim Mapping, add a claim mapping for each attribute your application needs:

Field	Description
Claim Name	The claim name that will appear in the issued token (e.g., `email`, `name`, `given_name`).
Claim Source	Select the identity provider connector to pull the attribute from.
Value Mapping	The attribute name from the identity provider (e.g., `preferred_username`, `name`).

Click the Claim button to add additional rows for each claim you need to map.

For example, to pass the user’s email, name, and family name, add three claim rows:

email from your IdP’s preferred_username
name from your IdP’s name
family_name from your IdP’s family_name

Click Save.

Add a claimsMapping section to your application definition. Each entry maps a claim name in the issued token (left side) to an attribute from your IdP connector (right side), using the format connectorName.attributeName.

maverics.yaml

apps:
  - name: my-web-app
    type: oidc
    clientID: my-web-app
    credentials:
      secrets:
        - <app.clientSecret>
    redirectURLs:
      - https://your-app.example.com/callback
    authentication:
      idps:
        - my-idp
    accessToken:
      type: jwt
    claimsMapping:
      email: my-idp.preferred_username
      name: my-idp.name
      family_name: my-idp.family_name
      given_name: my-idp.given_name

The claimsMapping keys (email, name, family_name, given_name) are the claim names that appear in the tokens your application receives. The values (my-idp.preferred_username, my-idp.name, etc.) reference attributes from the identity connector. The prefix before the dot must match the connector name from the previous step.See OIDC Provider Reference for all available fields, including scopes, token lifetimes, and advanced claim configuration.

See the OIDC Provider reference for the complete list of configurable claims, scopes, and token settings.

Publish your configuration

After configuring your deployment, identity connector, application, and claim mapping in the Console, you need to publish the configuration so the Orchestrator receives it and applies your changes.

Console UI
Configuration

At the bottom of the deployment Settings page, click Publish Preview in the sticky footer bar.
In the Deployment Manager dialog, review the configuration diff to verify your changes.
Optionally add a revision note describing what changed (e.g., “Initial OIDC SSO setup”).
Click Publish to deploy the configuration bundle to your storage provider.
The Orchestrator detects the new bundle on its next poll cycle and applies the configuration automatically.

See Publishing Deployment Configs overview for details on the publishing lifecycle, revision history, and bundle verification.

When using direct configuration, configuration is delivered directly to the Orchestrator via the -config flag or MAVERICS_CONFIG environment variable. No publishing step is needed — restart the Orchestrator to apply configuration changes.

Verify SSO is working

With your identity provider connected, your application defined, and claim mapping configured, you are ready to test the complete SSO flow.Start (or restart) the Orchestrator to pick up your configuration and verify it is healthy:

maverics -config /etc/maverics/config.yaml
curl -s https://localhost:9443/status | jq .

A healthy response confirms the Orchestrator is running:

{
  "status": "up"
}

Now open your application’s public URL in a browser and walk through the SSO flow:

Visit your application URL — You should be redirected to your identity provider’s login page
Authenticate — Log in with valid credentials
Verify redirect — After authentication, you should land on your application with full access
Inspect tokens — If your application exposes token details, verify the claims match your mapping configuration

Success! Your Maverics Orchestrator is acting as an OIDC Provider — authenticating users through your identity provider and issuing tokens with the claims your application expects. Users experience seamless single sign-on without your application needing to integrate directly with your IdP.

Troubleshooting

Redirect URI mismatch error

This is the most common OIDC configuration issue. Your identity provider rejects the authentication request because the redirect URI (callback URL) the Orchestrator sends does not exactly match what is registered in your IdP. Check both sides — the URI configured in the Orchestrator and the URI registered in your IdP’s application settings must be character-for-character identical, including the protocol (https://), domain, port, and path. Trailing slashes matter.

Token validation fails or claims are missing

If your application receives a token but cannot validate it, verify that the audience (aud) claim in the token matches what your application expects. The audience is set during claim mapping — make sure it points to your application’s client ID or expected identifier. If claims are missing from the token, check that the scopes requested during authentication include the data you need (for example, email scope for email claims, profile scope for name claims). See the OIDC Provider reference for scope-to-claim mappings.

Users see a blank page or infinite loading after login

This usually indicates the Orchestrator successfully authenticated the user but cannot reach the upstream application. Verify that the upstream URL in your application route is correct and that the application is running and accessible from the Orchestrator’s network. Check the Orchestrator logs for connection errors or timeouts.

What’s Next

Federate SAML Apps

Set up SAML 2.0 federation for legacy enterprise applications that do not support OIDC

OIDC Provider Reference

Explore the complete OIDC Provider configuration — scopes, claims, token lifetimes, and advanced settings

Getting Started

Authentication

AI Identity

Operations

Security

Prerequisites

Configure SSO

Troubleshooting

What’s Next

Federate SAML Apps

OIDC Provider Reference

Getting Started

Authentication

AI Identity

Operations

Security

​Prerequisites

​Configure SSO

​Troubleshooting

​What’s Next

Federate SAML Apps

OIDC Provider Reference

Prerequisites

Configure SSO

Troubleshooting

What’s Next