StreamTrace BETA
Documentation menu

Authentication & Access Control

Authentication

Enable login, configure JWT signing keys, and bootstrap the first admin.

Authentication is enabled by default (ST_AUTH_ENABLED=true). Stream Trace supports local email/password accounts and OIDC single sign-on, with short-lived access tokens and rotating refresh tokens.

JWT signing keys (required)

When auth is enabled you must configure a JWT signing key ring. Each key needs a unique id and a secret of at least 32 bytes:

ST_AUTH_JWT_ACTIVE_KEY_ID=primary
ST_AUTH_JWT_KEYS='[{"id":"primary","secret":"replace-with-a-random-32-byte-minimum-secret"}]'

The active key signs new tokens; keeping older keys in the ring lets existing tokens validate during a rotation.

Bootstrap the first admin

Create the first instance_admin either from the setup page the UI shows on a fresh install, or at startup with environment variables:

ST_AUTH_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
ST_AUTH_BOOTSTRAP_ADMIN_PASSWORD='correct horse battery staple'
ST_AUTH_BOOTSTRAP_ADMIN_DISPLAY_NAME='Admin'

If those are set and no users exist yet, the admin is created on startup.

Local accounts

Local password auth is enabled by default with signup disabled:

ST_AUTH_LOCAL_ENABLED=true
ST_AUTH_SIGNUP_MODE=disabled          # enabled | disabled | invite_only
ST_AUTH_ALLOWED_EMAIL_DOMAINS=example.com
  • invite_only lets admins invite users from the admin console.
  • ST_AUTH_ALLOWED_EMAIL_DOMAINS restricts which email domains may register or be invited.

Email verification and password reset require an email transport:

ST_AUTH_EMAIL_DELIVERY=smtp           # disabled | log | smtp
ST_AUTH_EMAIL_FROM=stream-trace@example.com
ST_AUTH_SMTP_HOST=smtp.example.com
ST_AUTH_SMTP_PORT=587
ST_AUTH_SMTP_USERNAME=stream-trace
ST_AUTH_SMTP_PASSWORD=secret
ST_AUTH_SMTP_TLS=starttls             # starttls | tls | none

With log delivery, verification and reset links are written to the logs - handy for testing without a real mail server.

Sessions & tokens

  • Access token - a short-lived JWT (ST_AUTH_ACCESS_TOKEN_TTL, default 15m).
  • Refresh token - stored in an HTTP-only cookie and rotated on each use (ST_AUTH_REFRESH_TOKEN_TTL, default 720h).
  • CSRF - a CSRF token is issued at login and required for state-changing requests.

Cookie behavior is controlled by ST_AUTH_COOKIE_SECURE (default true) and ST_AUTH_COOKIE_SAME_SITE (default lax). Set ST_AUTH_COOKIE_SECURE=false only when serving over plain HTTP locally.

Disabling auth (local only)

For a quick local look you can turn auth off entirely:

ST_AUTH_ENABLED=false

This attaches a synthetic local-development admin actor and shows a warning banner in the UI.

Do not use disabled auth in a shared or production environment. Anyone who can reach the UI gets full admin access.

Next steps