Authentication

KestrelOS supports local login (username/email + password) and optional OIDC (single sign-on with an identity provider). All users must sign in to use the app.

First run: bootstrap admin

On first start, if the database has no users, KestrelOS creates an admin account:

If you set env vars:
BOOTSTRAP_EMAIL and BOOTSTRAP_PASSWORD
→ That account is created (identifier = email, role = admin).
If you do not set them:
A default admin is created with identifier admin and a random password.
The password is printed in the terminal—copy it and sign in at /login.

After first login, change the password or add users via Members (admin only).

Signing in (local)

Open /login (or you’ll be redirected there when visiting a protected page).
Enter Email or username (identifier) and Password.
Click Sign in. You’re redirected to the map or the page you came from.

Local users can always use this form. Their password is stored hashed in the database.

OIDC lets users sign in with an external identity provider (IdP), e.g. Keycloak, Auth0, or your organization’s IdP. There is no “sign up” inside KestrelOS for OIDC: accounts are created when a user signs in for the first time (first-time OIDC login creates a KestrelOS user linked to that IdP identity).

Enabling OIDC

Set these environment variables:

Variable	Required	Description
`OIDC_ISSUER`	Yes	IdP issuer URL (e.g. `https://auth.example.com/realms/myrel`).
`OIDC_CLIENT_ID`	Yes	OIDC client ID.
`OIDC_CLIENT_SECRET`	Yes	OIDC client secret.
`OIDC_LABEL`	No	Button label (default: "Sign in with OIDC").
`OIDC_REDIRECT_URI`	No	Callback URL (default: `{APP_URL}/api/auth/oidc/callback`).
`OIDC_SCOPES`	No	Scopes (default: `openid profile email`).

The app derives the redirect URI if not set:

Prefer NUXT_APP_URL or APP_URL (e.g. https://kestrelos.example.com).
Callback = {that base}/api/auth/oidc/callback.
Otherwise it uses HOST, PORT, and NODE_ENV (e.g. http://localhost:3000/api/auth/oidc/callback).

IdP configuration

In your IdP:

Create an OIDC client (confidential, or public with PKCE if supported).
Set Redirect URI to:
https://<your-kestrelos-host>/api/auth/oidc/callback
(or the same with http for local dev).
Copy Client ID and Client Secret into OIDC_CLIENT_ID and OIDC_CLIENT_SECRET.
Set Issuer in OIDC_ISSUER (issuer URL from the IdP’s discovery document).

User opens /login and clicks the OIDC button (e.g. “Sign in with OIDC”).
They are redirected to the IdP to sign in (and sign up at the IdP if needed).
After success, the IdP redirects back to KestrelOS with an authorization code.
KestrelOS exchanges the code for tokens and creates or finds the user (by oidc_issuer + oidc_sub), then logs them in.

Sign up: Done at the IdP. The first time a user completes OIDC login, KestrelOS creates a new user; no separate “sign up” page in KestrelOS.

OIDC and ATAK/iTAK

OIDC users don’t have a KestrelOS password. To use ATAK or iTAK with “Use Authentication,” they must set an ATAK password once in the web app:

Sign in with OIDC.
Go to Account.
Under ATAK / device password, set and confirm a password, then save.

They then use their KestrelOS username (identifier) and this ATAK password in the TAK client. See ATAK and iTAK.

Roles

Admin — Can manage users (add, edit, delete, change roles), edit POIs, and add/edit devices (via API).
Leader — Can edit POIs and add/edit devices (via API). Cannot change user roles.
Member — Can view map, cameras, and POIs; can use Share live. Cannot edit POIs or manage devices.

Only admins can change roles (Members page).

Summary

Goal	Action
First-time setup	Set `BOOTSTRAP_EMAIL` / `BOOTSTRAP_PASSWORD` or use printed default admin password.
Local sign-in	Use /login with identifier and password.
Enable SSO	Set `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (and optional `OIDC_LABEL`, `OIDC_REDIRECT_URI`).
“Sign up” with OIDC	Users sign up at the IdP; first OIDC login in KestrelOS creates their account.
Use ATAK/iTAK as OIDC user	Set ATAK password under Account in the web app.

4.5 KiB Raw Blame History Unescape Escape

Authentication

Local login