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 Azure AD 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 Orchestrator Software modal showing evaluation bundles and platform installers

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 Azure AD (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

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

Identity provider connector configuration screen in Maverics Console

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 Azure AD 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

Application route configuration screen in Maverics Console

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

Operations

Security

Prerequisites

Install and Configure

Troubleshooting

What’s Next

Protect Your First Application

SSO with OIDC

Getting Started

Authentication

AI Identity

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