107 lines
4.5 KiB
Markdown
107 lines
4.5 KiB
Markdown
# 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. |
|