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

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="Console UI">
        The fastest way to get started is to download an **evaluation bundle** from the Maverics Console.

        1. Log in to the [Maverics Console](https://maverics.strata.io)
        2. Navigate to **Deployments** and create a new Deployment
        3. Select **Maverics storage** as the configuration provider
        4. Open the **Download Orchestrator Software** modal
        5. Under **Evaluation Bundles**, download the bundle for your platform:
           * **Windows:** `maverics-evaluation.zip`
           * **macOS:** `maverics-evaluation.tar.gz`
           * **Linux:** `maverics-evaluation.tar.gz`
        6. Extract the bundle and run the Orchestrator binary
      </Tab>

      <Tab title="Configuration">
        Download the Orchestrator binary from the [Maverics Console](https://maverics.strata.io). 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:

        ```bash theme={null}
        # Verify the installation
        maverics -version
        ```
      </Tab>
    </Tabs>

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

  <Step title="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.

    <Tabs>
      <Tab title="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.
        </Tip>
      </Tab>

      <Tab title="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).
      </Tab>
    </Tabs>

    <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.
    </Tip>
  </Step>

  <Step title="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."

    <Tabs>
      <Tab title="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.
        </Tip>
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.

    <Check>
      **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.
    </Check>

    To add session management and identity header injection to this route, continue to the [Protect Your First Application](/guides/getting-started/first-application) guide.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Protect Your First Application" icon="shield-halved" href="/guides/getting-started/first-application">
    Add session management and header injection to your route
  </Card>

  <Card title="SSO with OIDC" icon="key" href="/guides/authentication/sso-with-oidc">
    Dive deeper into OpenID Connect single sign-on configuration and claim mapping
  </Card>
</CardGroup>