# Configure dashboard authentication

Choose an authentication mode for the dashboard, set it in your Helm values, and harden the install for production.

## Prerequisites

- Omnia installed with the Helm chart, with `dashboard.enabled: true`.
- For OAuth mode, credentials from your identity provider (IdP).

## Choose a mode

| Mode | Use it for | Guide |
|------|------------|-------|
| `anonymous` | Isolated development | [Anonymous mode](#use-anonymous-mode) |
| `proxy` | An existing reverse proxy that authenticates users (OAuth2 Proxy, Authelia) | [Configure proxy authentication](/how-to/security/configure-dashboard-auth-proxy/) |
| `oauth` | Direct sign-in with an OIDC IdP (Okta, Entra ID, Google, Cognito) | [Configure OAuth sign-in](/how-to/security/configure-dashboard-auth-oauth/) |
| `builtin` | Small teams with no IdP | [Configure builtin authentication](/how-to/security/configure-dashboard-auth-builtin/) |

The chart has no default for `dashboard.auth.mode` and fails to render while it is empty.

management-api, the service behind the dashboard's API, serves sign-in in every mode and is the only reader of the sessions it writes. One management-api replica keeps sessions in memory; more than one needs a Redis they share, named in `redis.default` or `dashboard.session.redis`. `builtin` also needs a PostgreSQL database for management-api in `managementApi.database.existingSecret`. The chart fails to render without them. `anonymous` needs neither.

For agent endpoint authentication (JWT, Istio), see [Configure agent authentication](/how-to/security/configure-authentication/).

## Set the mode

1. Add the mode to your values file. Each guide above lists the settings for its mode.

   ```yaml
   dashboard:
     auth:
       mode: oauth   # anonymous, proxy, oauth or builtin
   ```

2. Apply the values.

   ```bash
   helm upgrade --install omnia oci://ghcr.io/altairalabs/charts/omnia \
     --devel --namespace omnia-system -f values.yaml
   ```

The chart renders management-api's `OMNIA_*` environment variables from `dashboard.auth.*`, `dashboard.proxy.*`, `dashboard.oauth.*` and `dashboard.builtin.*`. The [reference](/reference/platform/dashboard-auth/#helm-values) maps each variable to its value. Put credentials in Kubernetes Secrets and name them in the `existing*Secret` values. The chart also accepts literal credential values, which store them in the rendered manifests.

## Use anonymous mode

Anonymous mode turns authentication off. Every visitor gets the role in `dashboard.auth.anonymousRole` (default `viewer`).

```yaml
dashboard:
  auth:
    mode: anonymous
    allowAnonymous: true   # required; the chart fails without it
    anonymousRole: viewer  # or editor, admin
```

Use it only on an isolated development install or behind network-level controls.

## Set the session secret

Helm installs need no action: the chart generates `OMNIA_SESSION_SECRET` on first install and keeps it across upgrades. To manage the secret yourself, create a Secret with the key `OMNIA_SESSION_SECRET` (32 or more characters) and reference it.

```yaml
dashboard:
  auth:
    existingSessionSecret: omnia-dashboard-session
```

Outside the Helm chart, set the same `OMNIA_SESSION_SECRET` on every management-api container. In production it refuses to start without one, rather than sign session cookies with the fixed development key published in the source tree.

## Harden for production

1. Leave `dashboard.auth.allowAnonymous` at `false` and use `oauth`, `proxy` or `builtin`.
2. Serve the dashboard over HTTPS: set `dashboard.ingress.tls`, or terminate TLS in front of the dashboard. The session cookie carries `Secure` in production, and browsers send it only over HTTPS.
3. Set `dashboard.baseUrl` to the public HTTPS URL. Without it, the chart derives the URL from `dashboard.ingress.host` and `dashboard.ingress.tls` when ingress is on.
4. Shorten `dashboard.auth.ttl` (seconds, default `86400`) to limit how long a stolen cookie works.
5. Set `dashboard.apiKeys.defaultExpiration` (days, default `90`). A value of `0` creates keys that never expire.
6. Map IdP groups to platform roles with `dashboard.auth.roleMapping.adminGroups` and `editorGroups`.

To replace the default Content-Security-Policy, set `OMNIA_CSP_POLICY` through `dashboard.extraEnv`. The [reference](/reference/platform/dashboard-auth/#security-headers) lists every header.

## Use API keys

API key authentication is on by default. Users create keys in **Settings → API keys**. A client sends the key in either header:

```bash
curl -H "Authorization: Bearer omnia_sk_<key>" \
  https://dashboard.example.com/api/workspaces

curl -H "X-API-Key: omnia_sk_<key>" \
  https://dashboard.example.com/api/workspaces
```

The default store is `memory`, which loses every key when the dashboard restarts. Choose a durable store with [Durable API keys](/how-to/security/api-keys/).

## Verify

For `oauth` and `builtin`, an unauthenticated API request is refused.

```bash
curl -i https://dashboard.example.com/api/workspaces
```

The response is `401` with the body `{"error":"unauthenticated"}`. Browser requests to a page redirect to `/login`.

For any non-anonymous mode, sign in and open `https://dashboard.example.com/api/auth/session`. It returns `{"authenticated":true}`.

## Troubleshooting

### The chart fails with a message about `dashboard.auth.mode`

The chart requires an explicit mode. `anonymous` also needs `dashboard.auth.allowAnonymous: true`.

### The user is signed out after a page refresh

1. Confirm the Secret named in `existingSessionSecret` has the key `OMNIA_SESSION_SECRET`.
2. Check the browser developer tools for the `omnia_session` cookie (or your `dashboard.auth.cookieName`).
3. Check that no proxy strips cookies, and that the site is served over HTTPS.

### API calls with a key return 401

1. Confirm the key starts with `omnia_sk_` and has not expired.
2. With the `memory` store, a dashboard restart deletes every key. Create a new one or switch store.

## Related pages

- [Dashboard authentication reference](/reference/platform/dashboard-auth/): variables, Helm values, providers, routes, roles.
- [Authentication architecture](/explanation/security/authentication/): how the dashboard and agent layers fit together.
- [Grant workspace access with IdP groups](/how-to/security/grant-workspace-access-with-idp-groups/)
- [Manage workspaces](/how-to/workspaces/manage-workspaces/)