kestrelos/docs/auth.md

Authentication

KestrelOS supports local login (username/email + password) and optional OIDC (SSO). All users must sign in.

Local Login

First run: On first start, KestrelOS creates an admin account:

• If BOOTSTRAP_EMAIL and BOOTSTRAP_PASSWORD are set → that account is created
• Otherwise → default admin (admin) with random password printed in terminal

Sign in: Open /login, enter identifier and password. Change password or add users via Members (admin only).

OIDC (SSO)

Enable: Set OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET. Optional: OIDC_LABEL, OIDC_REDIRECT_URI, OIDC_SCOPES.

IdP setup:

1. Create OIDC client in your IdP (Keycloak, Auth0, etc.)
2. Set redirect URI: https://<your-host>/api/auth/oidc/callback
3. Copy Client ID and Secret to env vars

Sign up: Users sign up at the IdP. First OIDC login in KestrelOS creates their account automatically.

Redirect URI: Defaults to {APP_URL}/api/auth/oidc/callback (uses NUXT_APP_URL/APP_URL or falls back to HOST/PORT).

OIDC Users and ATAK/iTAK

OIDC users don't have a KestrelOS password. To use ATAK/iTAK:

1. Sign in with OIDC
2. Go to Account → set ATAK password
3. Use KestrelOS username + ATAK password in TAK client

Roles

• Admin — Manage users, edit POIs, add/edit devices (API)
• Leader — Edit POIs, add/edit devices (API)
• Member — View map/cameras/POIs, use Share live

Only admins can change roles (Members page).