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
proxy	An existing reverse proxy that authenticates users (OAuth2 Proxy, Authelia)	Configure proxy authentication
oauth	Direct sign-in with an OIDC IdP (Okta, Entra ID, Google, Cognito)	Configure OAuth sign-in
builtin	Small teams with no IdP	Configure builtin authentication

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.

Set the mode

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

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

2. Apply the values.

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

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.

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

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.

Verify

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

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: variables, Helm values, providers, routes, roles.
• Authentication architecture: how the dashboard and agent layers fit together.
• Grant workspace access with IdP groups
• Manage workspaces