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

# Protect Your First Application

This guide picks up where the Quick Start left off. You already have a running Orchestrator with SSO protecting a basic route. Now you will add session management, identity header injection, and production-ready configuration.

## Prerequisites

* **Completed the [Quick Start guide](/guides/getting-started/quick-start)** -- You should have a running Orchestrator with an identity provider connected and a working application route protected by SSO.
* **A configured identity provider connector** -- Your Orchestrator should already be connected to an identity provider (Microsoft Entra ID, Okta, or another supported IdP) from the Quick Start.

## Configure Your Application

You should already have a working application route from the Quick Start guide. The steps below add session management and header injection to that existing configuration.

**1. Set up session management**

Session management controls how the Orchestrator tracks authenticated users between requests. Without session management, users would need to re-authenticate on every page load -- which is not a practical experience.

The Orchestrator creates a session after a user successfully authenticates. This session stores the user's identity information (who they are, what claims they have) so that subsequent requests can be authorized without a full round-trip to the identity provider. Sessions can be stored in-memory for development or configured with [cookie-based sticky sessions](/reference/orchestrator/sessions/local) for production multi-node deployments (the load balancer uses the `maverics_session` cookie for affinity).

**Console UI**

Session management is configured in the Deployment settings, not on an individual application.

1. Navigate to **Deployments** in the sidebar and select your deployment.

2. Under **Orchestrator Settings**, find the **Session and Cookie** section.

3. Click **Edit Session and Cookie** to open the settings dialog.

4. Configure session lifetime settings:

   | Field | Default | Description |
   | - | - | - |
   | Max Lifetime Seconds | 86400 (24 hours) | The maximum number of seconds that can elapse post-authentication before a session's authentication state becomes invalidated. |
   | Idle Timeout | 0 (disabled) | The number of seconds a session may remain idle before timing out. Set to `0` to disable idle timeout. |
   | Cache Size | 50,000 | Limits the number of sessions maintained in memory. |

5. Optionally configure the **Cookie** settings:

   | Field | Description |
   | - | - |
   | Domain | Specifies the hosts to which the session cookie will be sent (e.g., `example.com`). |
   | Name | The name of your Maverics session cookie. |
   | Disable HttpOnly Attribute | If enabled, the session cookie can be accessed via client-side scripts. Leave disabled for security. |
   | Disable Secure Cookie Attribute | If enabled, the cookie can be sent over unencrypted HTTP. Leave disabled for security. |

6. Click **Save**.

> [!NOTE]
>
> The dialog also offers optional **Service Extension** dropdowns for evaluating session maximum lifetime and idle timeout programmatically. See the [Sessions reference](/reference/orchestrator/sessions) for details.

**Configuration**

```yaml theme={null}
session:
  cookie:
    name: "maverics_session"
    domain: "example.com"
  lifetime:
    maxTimeout: "12h"
    idleTimeout: "30m"
  store:
    type: "local"
    local:
      capacity: 50000
```

The `cookie.domain` scopes the session cookie to your domain. The `lifetime` settings control how long sessions remain valid. The `store.type: "local"` uses in-memory storage suitable for both development and production. See the [Sessions Reference](/reference/orchestrator/sessions) for all session configuration options.

**2. Configure header injection**

Header injection (also called identity propagation) is how the Orchestrator passes user identity information to your upstream application. After the Orchestrator authenticates a user, it adds HTTP headers to the proxied request -- telling your application who the user is without your application needing to handle authentication directly.

Common headers include the user's email address, display name, group memberships, and any custom claims from the identity provider. Your upstream application reads these headers to identify the user and make authorization decisions.

For example, the Orchestrator might inject:

* `X-Forwarded-User` -- The authenticated user's unique identifier
* `X-Forwarded-Email` -- The user's email address from the identity provider
* `X-Forwarded-Groups` -- A comma-separated list of the user's group memberships

**Console UI**

Header injection is configured per-location within the application's access control policy.

1. Open your application's settings.

2. In the **Resources** card, click **Edit**, 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.

3. Find the **Access Control** card and click **Edit**, then click **Policy** to add a policy (or edit an existing one) in the **Edit Access Control** drawer.

4. Set the **Location** for the route you want to protect (e.g., `/`).

5. From the **Select an authentication source** dropdown, select the identity provider connector that will authenticate users for this location.

6. For **Authorization method**, choose **Allow all access**.

7. Under **Headers**, add the identity headers your application needs:

   | Header Name | Identity Source | Attribute Mapping |
   | - | - | - |
   | `X-Forwarded-User` | Your IdP connector | `sub` |
   | `X-Forwarded-Email` | Your IdP connector | `email` |
   | `X-Forwarded-Groups` | Your IdP connector | `groups` |

   Click **Header** to add each additional header.

8. Click **Save**.

> [!TIP]
>
> You can also use the **Global Request Headers & Service Extensions** card on the application to add headers to all locations without repeating them in each access control policy.

**Configuration**

Add the `headers` array to your existing app entry from the Quick Start:

```yaml theme={null}
# Add to your existing app entry from Quick Start
headers:
  - name: "X-Forwarded-User"
    value: "{{ azure.sub }}"
  - name: "X-Forwarded-Email"
    value: "{{ azure.email }}"
  - name: "X-Forwarded-Groups"
    value: "{{ azure.groups }}"
```

Headers are defined as an array of `{name, value}` objects. Values use the `{{ connector.claim }}` template syntax, where the connector name (e.g., `azure`) is the namespace and the claim name (e.g., `email`, `sub`, `groups`) comes from the identity provider.

Your complete app entry with headers should look like this:

```yaml theme={null}
apps:
  - name: my-application
    type: proxy
    upstream: "https://internal-app.example.com"
    routePatterns:
      - "app.example.com"
    headers:
      - name: "X-Forwarded-User"
        value: "{{ azure.sub }}"
      - name: "X-Forwarded-Email"
        value: "{{ azure.email }}"
      - name: "X-Forwarded-Groups"
        value: "{{ azure.groups }}"
    policies:
      - location: "/"
        authentication:
          idps: ["azure"]
        authorization:
          allowAll: true
```

> [!WARNING]
>
> Make sure your upstream application only trusts these headers when they come
> from the Orchestrator. If users can reach your application directly (bypassing
> the Orchestrator), they could forge these headers. Configure your application
> to only accept traffic from the Orchestrator's IP address or network, or use
> [mTLS](/guides/security/tls) between the Orchestrator and your upstream so
> both sides verify each other's identity cryptographically.

**3. Test the complete flow**

With session management and header injection configured, restart the Orchestrator to pick up your updated configuration.

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

1. **Visit your application URL** -- You should be redirected to your identity provider's login page
2. **Authenticate** -- Log in with valid credentials
3. **Verify redirect** -- After authentication, you should land on your application with full access
4. **Verify session persistence** -- Close and reopen your browser, then revisit the application URL. Your session should persist without requiring re-authentication (within the configured timeout)
5. **Check headers** -- If your application has a debug or profile page, verify that the injected identity headers (`X-Forwarded-User`, `X-Forwarded-Email`, `X-Forwarded-Groups`) are present and contain the correct values

> [!TIP]
>
> **Success!** Your application is fully protected by the Maverics Orchestrator.
> Users authenticate through your identity provider, sessions are managed
> automatically, and your application receives user identity through HTTP
> headers -- all without modifying your application code.

## Troubleshooting

> **User authenticates but sees a 403 Forbidden error**
>
> A 403 error after successful authentication usually means an authorization
> policy is blocking the user. Check whether you have configured any access
> policies that restrict which users can access the application. Also verify
> that the user's claims from the identity provider include the required
> attributes (such as group membership) that your policies expect.

> **Headers are not reaching the upstream application**
>
> Verify that header injection is configured for the correct application entry.
> If your upstream application is behind a load balancer or reverse proxy, that
> intermediate layer may be stripping non-standard headers. Check each hop in
> the request path. You can use a tool like `curl -v` to inspect the headers
> the Orchestrator sends to your upstream.

> **Session expires too quickly or not at all**
>
> Session behavior is controlled by the session store configuration. Check the
> session timeout value -- it may be set too low for your use case. If sessions
> are not expiring, verify that the session store is correctly configured and
> that the Orchestrator is reading from the same store it writes to (important
> in multi-instance deployments). See the
> [Sessions reference](/reference/orchestrator/sessions) for all
> timeout and expiration options.

## What's Next

> **[Authentication Guides](/guides/authentication/overview)**
>
> Explore SSO with OIDC, SAML federation, and identity provider migration

> **[Deploy to Production](/guides/operations/deploy)**
>
> Learn how to deploy the Orchestrator for production workloads with high availability