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

# 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](/reference/orchestrator/installation) for full system requirements.
* **An identity provider account** -- You need an account with an identity provider such as [Microsoft Entra ID](/reference/orchestrator/identity-fabric/azure-ad) or [Okta](/reference/orchestrator/identity-fabric/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

**1. 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**

1. Log in to the [Maverics Console](https://maverics.strata.io)
2. Navigate to **Deployments** and create a new Deployment
3. Select a configuration storage provider (e.g., **No Cloud Storage Service Configured** for a quick start, or an S3/Azure/GCS bucket for production)
4. Open the **Download Orchestrator Software** modal
5. Download the installer for your platform and follow the platform-specific installation steps

**Configuration**

Download the Orchestrator binary from the [Maverics Console](https://maverics.strata.io). The Console provides platform-specific installers through the **Download Orchestrator Software** modal inside any Deployment.

After downloading and extracting the binary for your platform:

```bash theme={null}
# Verify the installation
maverics -version
```

> [!TIP]
>
> For a quick look at the available installation methods -- including Docker, Kubernetes, and direct install -- see the [Installation reference](/reference/orchestrator/installation).

**2. 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](/reference/orchestrator/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**

1. Navigate to **Identity Fabric** in the sidebar.

2. Click **Create**.

3. In the **Create Identity Fabric** dialog, search for and select your identity provider (e.g., **Microsoft Entra ID (OIDC)**).

4. 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`). |

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

6. Click **Save**.

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

**Configuration**

```yaml theme={null}
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](/reference/orchestrator/configuration/secret-providers).

> [!TIP]
>
> Not sure which connector to use? The [Identity Fabric overview](/reference/orchestrator/identity-fabric) has a comparison table that maps each connector to its supported protocols and use cases.

**3. 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**

1. Navigate to **Applications** in the sidebar.

2. Click **Create**.

3. In the **Create a new Application** dialog, select **Proxied App**.

4. 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`). |

5. Click **Save**.

6. In the application's settings, open the **Resources** card, click **Edit**, then click **Add Resource** and add your identity provider connector. A connector must be added as a resource before it can be used as an authentication source.

7. Find the **Access Control** card and click **Edit**. Add a policy with **Location** `/`, select your connector from the **Select an authentication source** dropdown, and choose **Allow all access** for the **Authorization method**.

8. Click **Save**, then publish your configuration.

> [!TIP]
>
> Route patterns, identity provider assignment, and authorization policies are configured on the application. The [Protect Your First Application](/guides/getting-started/first-application) guide covers this in more detail.

**Configuration**

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

**4. 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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

> [!TIP]
>
> **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](/guides/getting-started/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](/reference/orchestrator/configuration/secret-providers) 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.

## What's Next

> **[Protect Your First Application](/guides/getting-started/first-application)**
>
> Add session management and header injection to your route

> **[SSO with OIDC](/guides/authentication/sso-with-oidc)**
>
> Dive deeper into OpenID Connect single sign-on configuration and claim mapping