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

---

## Local login

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

1. Open **/login** (or you’ll be redirected there when visiting a protected page).
2. Enter **Email or username** (identifier) and **Password**.
3. 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 config and sign up

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:

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

### OIDC sign-in flow

1. User opens **/login** and clicks the OIDC button (e.g. “Sign in with OIDC”).
2. They are redirected to the IdP to sign in (and sign up at the IdP if needed).
3. After success, the IdP redirects back to KestrelOS with an authorization code.
4. 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:

1. Sign in with OIDC.
2. Go to **Account**.
3. 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](atak-itak.md).

---

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