Quick Start

By the end of this guide, you will have a running Maverics Orchestrator connected to your identity provider with your first application route protected by single sign-on.

Prerequisites

A supported operating system — The Orchestrator runs on Linux, macOS, Windows, and in containers. See the installation reference for full system requirements.
An identity provider account — You need an account with an identity provider such as Microsoft Entra ID or Okta. This is the system your users log into today.
A target application — Any web application running on a URL you can reach from the machine where the Orchestrator will run.

Install and Configure

Install the Orchestrator

The Maverics Orchestrator is a small, lightweight runtime that deploys almost anywhere — on a virtual machine, in a container, or on bare metal. Installation takes just a few minutes.The Orchestrator sits between your users and your applications, handling authentication and identity routing so your apps do not have to. Think of it as an identity abstraction layer — it authenticates users against your identity provider and then forwards authenticated requests to your upstream applications.

Console UI
Configuration

The fastest way to get started is to download an evaluation bundle from the Maverics Console.

Log in to the Maverics Console
Navigate to Deployments and create a new Deployment
Select Maverics storage as the configuration provider
Open the Download Orchestrator Software modal
Under Evaluation Bundles, download the bundle for your platform:
- Windows: maverics-evaluation.zip
- macOS: maverics-evaluation.tar.gz
- Linux: maverics-evaluation.tar.gz
Extract the bundle and run the Orchestrator binary

Download the Orchestrator binary from the Maverics Console. The Console provides evaluation bundles and platform-specific installers through the Download Orchestrator Software modal inside any Deployment.After downloading and extracting the binary for your platform:

# Verify the installation
maverics -version

For a quick look at the available installation methods — including Docker, Kubernetes, and direct install — see the Installation reference.

Connect your identity provider

An identity provider (IdP) is the system that manages your user accounts and handles login — services like Microsoft Entra ID (now called 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. Each connector handles the protocol details — OIDC, SAML, or LDAP — so you just need to provide your provider’s credentials and endpoint information.

Console UI
Configuration

Navigate to Identity Fabric in the sidebar.
Click Create.
In the Create Identity Fabric dialog, search for and select your identity provider (e.g., Microsoft Entra ID (OIDC)).

Fill in the connector fields:

Field	Description
Name	A friendly name for this connector (e.g., `azure`).
OIDC Well Known URL	Your provider’s OpenID Connect discovery endpoint.
OAuth Client ID	The client ID of the application registered in your identity provider.
OAuth Client Secret	The corresponding client secret.
Redirect URLs	The callback URL the Orchestrator will use (e.g., `https://app.example.com/callback`).

Leave PKCE enabled (recommended) and configure optional fields like Scopes or Logout Callback URLs if needed.
Click Save.

The dialog supports a wide range of providers including Okta, Auth0, Ping, LDAP, Active Directory, and more. Pick the connector that matches your identity provider’s protocol.

connectors:
  - name: azure
    type: azure
    oauthClientID: "{{ env.AZURE_CLIENT_ID }}"
    oauthClientSecret: <vault.azure_client_secret>
    oidcWellKnownURL: "https://login.microsoftonline.com/{{ env.AZURE_TENANT_ID }}/v2.0/.well-known/openid-configuration"
    oauthRedirectURL: "https://app.example.com/callback"

Replace the environment variable values with your Microsoft Entra ID tenant details. The {{ env.VAR }} syntax reads from environment variables. The <vault.azure_client_secret> syntax reads from your configured secret provider.

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

Define your first application route

An application route tells the Orchestrator which upstream application to protect and how to route traffic. When a user requests your application URL, the Orchestrator intercepts the request, authenticates the user against your IdP, and then forwards the authenticated request to your upstream service.This step connects the identity connector you just configured to a specific application — creating the link between “who the user is” and “what they can access.”

Console UI
Configuration

Navigate to Applications in the sidebar.
Click Create.
In the Create a new Application dialog, select Proxied App.
Fill in the application fields:
Field Description
Name A friendly name for your application.
Upstream URL The URL of the application the Orchestrator will proxy traffic to (e.g., https://internal-app.example.com).
Click Save.
Navigate to User Flows in the sidebar and create a new user flow for your application.
Under Access Control, add a policy for the / location, select your identity provider connector for Authentication, and choose Allow all access for Authorization.
Click Save, then publish your configuration.

Field	Description
Name	A friendly name for your application.
Upstream URL	The URL of the application the Orchestrator will proxy traffic to (e.g., `https://internal-app.example.com`).

Route patterns, identity provider assignment, and authorization policies are configured through User Flows rather than on the application itself. The Protect Your First Application guide covers this in more detail.

apps:
  - name: my-application
    type: proxy
    upstream: "https://internal-app.example.com"
    routePatterns:
      - "app.example.com"
    policies:
      - location: "/"
        authentication:
          idps: ["azure"]
        authorization:
          allowAll: true

The policies[].authentication.idps array specifies which connectors handle authentication for this route. The authorization.allowAll: true allows any authenticated user.

Start and verify

With the Orchestrator installed, your identity provider connected, and your application route defined, you are ready to start the Orchestrator and confirm everything works.Start the Orchestrator and check its health endpoint to verify it is running:

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

The health endpoint returns a JSON response showing the status of the Orchestrator:

{
  "status": "up"
}

Next, open your application URL in a browser. You should be redirected to your identity provider’s login page. After authenticating, you will be redirected back to your application — now with a valid session managed by the Orchestrator.

Success! Your Orchestrator is running and your first application route is protected with single sign-on. Users authenticate through your identity provider, and the Orchestrator manages the session lifecycle.

To add session management and identity header injection to this route, continue to the Protect Your First Application guide.

Troubleshooting

The Orchestrator fails to start

Check that the configuration file path is correct and that the file is valid YAML. The Orchestrator logs the specific parsing error on startup — look for a line starting with error in the output. Common causes include indentation issues, missing required fields, or referencing a connector name that does not match the name in your connectors block.

Identity provider connection fails

Verify that your IdP credentials (client ID, client secret, tenant ID) are correct and that the Orchestrator can reach your IdP’s endpoints over the network. If you are using environment variables for secrets, confirm they are set in the shell where the Orchestrator is running. See the secret providers reference for alternative secret management options.

Browser shows a redirect loop or 502 error

A redirect loop usually means the callback URL configured in your identity provider does not match the Orchestrator’s expected redirect URI. Double-check both sides. A 502 error means the Orchestrator cannot reach your upstream application — verify the upstream URL is correct and the application is running.

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

Prerequisites

Install and Configure

Troubleshooting

What’s Next

Protect Your First Application

SSO with OIDC

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

​Prerequisites

​Install and Configure

​Troubleshooting

​What’s Next

Protect Your First Application

SSO with OIDC

Prerequisites

Install and Configure

Troubleshooting

What’s Next