Configure builtin authentication for the dashboard

Use local users and passwords for sign-in when you have no identity provider. management-api serves the builtin sign-in and keeps the users in a PostgreSQL database of its own.

Prerequisites

A PostgreSQL database for management-api: omnia_management by convention, on the same instance as session-api, with its own credentials.
A Redis that the dashboard and management-api share for sessions. management-api writes a session when a user signs in, and the dashboard reads it to admit their page loads.

Steps

Create a Secret with management-api’s database URL, under the key POSTGRES_CONN, and one with the initial admin password.

kubectl create secret generic omnia-management-db \
  --namespace omnia-system \
  --from-literal=POSTGRES_CONN=postgresql://<user>:<password>@<host>:5432/omnia_management

kubectl create secret generic omnia-dashboard-admin \
  --namespace omnia-system \
  --from-literal=OMNIA_BUILTIN_ADMIN_PASSWORD=<initial-password>

Set the mode, the database, the session store and the admin user.

dashboard:
  auth:
    mode: builtin
  builtin:
    admin:
      username: admin
      email: admin@example.com
      existingSecret: omnia-dashboard-admin
managementApi:
  database:
    existingSecret: omnia-management-db
redis:
  default:
    existingSecret:
      name: omnia-redis   # a Secret holding the Redis URL
      key: url

The chart refuses to render builtin mode without managementApi.database.existingSecret or a Redis session store (redis.default or dashboard.session.redis).

management-api creates its tables at startup. It creates the admin user only when the user table is empty and the username, email and password are all set.

Optionally tune registration and lockout. These are the defaults.
```
dashboard:
  builtin:
    allowSignup: false       # allow public self-registration
    verifyEmail: false       # require email verification
    minPasswordLength: 8
    maxFailedAttempts: 5     # failed logins before lockout
    lockoutDuration: 900     # seconds
```
The reset-token lifetime (OMNIA_BUILTIN_RESET_TOKEN_EXPIRATION, default 3600 seconds) and the verification-token lifetime (OMNIA_BUILTIN_VERIFICATION_TOKEN_EXPIRATION, default 86400 seconds) have no Helm value. Set them on management-api through managementApi.podOverrides.extraEnv.
If you enable verifyEmail or want password reset, configure SMTP in dashboard.builtin.smtp: host, port, secure, from and user, with the password in the Secret existingSecret names, under the key OMNIA_SMTP_PASS. The reference lists the OMNIA_SMTP_* variables they set.

Apply the values.

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

Users in a dashboard SQLite file or a dashboard PostgreSQL user table are not imported into management-api’s database. Sign in with the seeded admin and recreate the other users.

Verify

Open https://dashboard.example.com, which redirects to /login. Sign in with the admin username and the password from the Secret. Then open https://dashboard.example.com/api/v1/auth/session; it returns {"authenticated":true}.

Troubleshooting

Correct credentials are rejected

Confirm the user exists in management-api’s database.
Confirm the account is not locked.
If verifyEmail is on, confirm the user verified their email.
Confirm management-api can reach its database: its log names a failed migration at startup.

The dashboard and management-api read different session stores. Confirm both pods carry the same OMNIA_SESSION_REDIS_URL and OMNIA_SESSION_SECRET.

An account is locked

Wait for lockoutDuration (15 minutes by default), or clear the lock in management-api’s database:

UPDATE users SET failed_login_attempts = 0, locked_until = NULL WHERE email = 'user@example.com';

No reset or verification email arrives

Confirm OMNIA_SMTP_HOST is set on management-api. Without it management-api sends nothing and logs a warning.
Confirm the token has not expired.
Confirm a user with that email exists. The forgot-password endpoint reports success either way.