From 87041c88427f8513d297d8a7678a9100fe40329b Mon Sep 17 00:00:00 2001 From: Maurice Date: Sat, 24 Oct 2026 23:24:29 +0200 Subject: [PATCH] Update the login, reset, 2FA, passkey and SSO wiki pages for the current screens Describe the world map login panel, the first-run admin form, the plain HTTP cookie warning, the SSO error messages, the reset page states and the Reset 2FA action in the admin user dialog. Disabling 2FA accepts a backup code. --- wiki/Login-and-Registration.md | 40 +++++++++++++++++++------------ wiki/OIDC-SSO.md | 26 ++++++++++---------- wiki/Passkeys.md | 22 ++++++++--------- wiki/Password-Reset.md | 20 ++++++++-------- wiki/Two-Factor-Authentication.md | 18 +++++++------- 5 files changed, 69 insertions(+), 57 deletions(-) diff --git a/wiki/Login-and-Registration.md b/wiki/Login-and-Registration.md index 8e78dc4cb..73ebd089c 100644 --- a/wiki/Login-and-Registration.md +++ b/wiki/Login-and-Registration.md @@ -1,10 +1,12 @@ # Login and Registration -![TREK login page: the product splash panel on the left and the Sign In card on the right with email and password fields, a Remember me switch, a Forgot password? link and a Register link](assets/Registration.png) +![TREK login page: the animated world map panel with the tagline "Your Trips. Your Plan." on the left and the Sign In card on the right with email and password fields, a Remember me switch, a Forgot password? link and a Register link](assets/Registration.png) + +On a wide screen (1024 pixels and up) the left side of the page shows an animated dot map of the world on which routes light up between cities, with the tagline **Your Trips. Your Plan.** and a short description. The sign in card sits on the right. On narrower screens the panel is hidden and the card is shown under the TREK logo. ## Signing in -Navigate to `/login` and enter your email and password. On success, the server sets a `trek_session` cookie — httpOnly, sameSite=`lax`, and secure in production — that keeps you signed in across page reloads. How long it survives depends on the **Remember me** switch, described below. You do not need to sign in again until the session expires or you explicitly log out. +Navigate to `/login` and enter your email and password. On success, the server sets a `trek_session` cookie (httpOnly, sameSite=`lax`, and secure in production) that keeps you signed in across page reloads. How long it survives depends on the **Remember me** switch, described below. You do not need to sign in again until the session expires or you explicitly log out. > **Note:** The `secure` flag on the cookie can be overridden by setting `COOKIE_SECURE=false` in the server environment (useful for plain-HTTP dev setups), or force-enabled with `FORCE_HTTPS=true`. @@ -16,16 +18,16 @@ If you have forgotten your password, click the **"Forgot password?"** link below The **Remember me** switch below the password field decides how long the session lives: -- **Off** (the default) — a browser-session cookie with no `maxAge`, cleared when you close the browser, backed by a token valid for `SESSION_DURATION` (default `24h`). -- **On** — a persistent cookie matching a token valid for `SESSION_DURATION_REMEMBER` (default `30d`), so the session survives browser restarts. +- **Off** (the default): a browser-session cookie with no `maxAge`, cleared when you close the browser, backed by a token valid for `SESSION_DURATION` (default `24h`). +- **On**: a persistent cookie matching a token valid for `SESSION_DURATION_REMEMBER` (default `30d`), so the session survives browser restarts. -Both durations are configurable per instance, see [Environment-Variables](Environment-Variables). Your choice is carried through the MFA step, through a password change, and through SSO sign-in. While you keep using TREK the cookie is silently re-issued once the token is past half its lifetime, with the same Remember me semantics, so an active session never expires mid-use. Only cookie sessions are renewed this way — API and MCP clients authenticating with a bearer token are not. +Both durations are configurable per instance, see [Environment-Variables](Environment-Variables). Your choice is carried through the MFA step, through a password change, and through SSO sign-in. While you keep using TREK the cookie is silently re-issued once the token is past half its lifetime, with the same Remember me semantics, so an active session never expires mid-use. Only cookie sessions are renewed this way; API and MCP clients authenticating with a bearer token are not. -Sign-ins that never pass through this switch — registration, the demo button and passkey sign-in — get the historical default instead: a persistent cookie lasting `SESSION_DURATION`. +Sign-ins that never pass through this switch (registration, the demo button and passkey sign-in) get the historical default instead: a persistent cookie lasting `SESSION_DURATION`. ### Forced password change -Some accounts are flagged as needing a new password: the admin account TREK seeds on first boot always is, and so is an account restored with the `reset-admin.js` recovery script (see [Troubleshooting](Troubleshooting)). For those accounts a **Set new password** form is shown immediately after a successful login (or after the MFA step). The session cookie has already been issued at that point — the app simply keeps you on the form until the new password is saved, and saving it re-issues the cookie and signs your other sessions out. +Some accounts are flagged as needing a new password: the admin account TREK seeds on first boot always is, and so is an account restored with the `reset-admin.js` recovery script (see [Troubleshooting](Troubleshooting)). For those accounts a **Set new password** form is shown immediately after a successful login (or after the MFA step). The session cookie has already been issued at that point; the app simply keeps you on the form until the new password is saved, and saving it re-issues the cookie and signs your other sessions out. There is no control in the Admin Panel that flags an existing account. An admin-set password (see [Admin-Users-and-Invites](Admin-Users-and-Invites)) neither raises the flag nor clears it, so a user who already carries it is still asked to choose their own password at the next sign-in. @@ -39,9 +41,9 @@ To end sessions on other devices, the API offers `GET /api/auth/sessions` (the s The Register form appears under one of these conditions: -- **Open registration** — the admin has enabled password registration for the instance (`password_registration` setting). -- **Valid invite link** — you visited `/register?invite=TOKEN` with a valid token (see below). -- **No accounts at all** — nobody has signed up yet; the registration form is shown automatically and the first account created becomes an admin. On a normal install this never happens, because TREK seeds an admin on first boot (see [First run](#first-run) below). +- **Open registration**: the admin has enabled password registration for the instance (`password_registration` setting). +- **Valid invite link**: you visited `/register?invite=TOKEN` with a valid token (see below). +- **No accounts at all**: nobody has signed up yet; the registration form is shown automatically and the first account created becomes an admin. On a normal install this never happens, because TREK seeds an admin on first boot (see [First run](#first-run) below). Registration fields: **username**, **email**, and **password**. @@ -77,19 +79,25 @@ On a normal install TREK seeds an admin account on first boot, before anyone can - With **both** `ADMIN_EMAIL` and `ADMIN_PASSWORD` set, those values are used. - With only one of the two set, both are ignored (a warning is logged) and the generated credentials below are used instead. -- Otherwise the account is `admin@trek.local`, username `admin`, with a randomly generated password printed to the container log — run `docker logs trek` to retrieve it. +- Otherwise the account is `admin@trek.local`, username `admin`, with a randomly generated password printed to the container log; run `docker logs trek` to retrieve it. + +If no user exists at all, the page opens on a **Create Admin Account** form instead: "Set up the first admin account for TREK." The account created there is the admin. The seeded admin is flagged as requiring a password change, so you are forced to set a new password on first sign-in. Until that happens the Register link stays hidden even though password registration is enabled by default; once the password is changed the link appears normally. -Two setups skip the seeder entirely. `DEMO_MODE=true` seeds the demo data instead (see [Demo-Mode](Demo-Mode)), and on an **OIDC-only** install no local account is created at all — there the first user who signs in through the identity provider is assigned the **admin** role. +Two setups skip the seeder entirely. `DEMO_MODE=true` seeds the demo data instead (see [Demo-Mode](Demo-Mode)), and on an **OIDC-only** install no local account is created at all; there the first user who signs in through the identity provider is assigned the **admin** role. See [Quick-Start](Quick-Start) for the full first-boot walkthrough. +## Sign-in over plain HTTP + +If you reach TREK over plain HTTP, the browser drops the secure session cookie and the next request fails with "Access token required". After such a sign-in the page shows a warning, **Login won't stick over HTTP**, with an **Open the Troubleshooting guide** link. Use HTTPS, or for a home lab set `COOKIE_SECURE=false`. See [Troubleshooting](Troubleshooting). + ## Rate limiting Requests to the login endpoint are rate-limited to **10 per 15-minute window** per IP address. The counter is incremented before the credentials are checked, so successful sign-ins count against it too, not only failed ones. After exceeding the limit, further requests return HTTP 429 until the window resets. The window is fixed from the first counted request, and blocked requests do not extend it. -That counter is shared rather than per-endpoint. `POST /api/auth/login`, `POST /api/auth/register`, `GET /api/auth/invite/:token` and the passkey sign-in ceremony each allow 10 requests from it; `PUT /api/auth/me/password`, `POST /api/auth/mfa/disable`, `POST /api/auth/mcp-tokens` and passkey deletion draw on the same counter but are rejected once it reaches 5. Unrelated activity from the same IP therefore eats into the allowance — ten registration attempts will 429 the next login, and five requests of any kind will 429 a password change. +That counter is shared rather than per-endpoint. `POST /api/auth/login`, `POST /api/auth/register`, `GET /api/auth/invite/:token` and the passkey sign-in ceremony each allow 10 requests from it; `PUT /api/auth/me/password`, `POST /api/auth/mfa/disable`, `POST /api/auth/mcp-tokens` and passkey deletion draw on the same counter but are rejected once it reaches 5. Unrelated activity from the same IP therefore eats into the allowance: ten registration attempts will 429 the next login, and five requests of any kind will 429 a password change. MFA verification attempts are rate-limited separately to **5 attempts per 15-minute window** per IP address. @@ -97,14 +105,16 @@ Forgot-password requests are rate-limited to **3 attempts per 15-minute window** ## Demo mode -When the server is started with `DEMO_MODE=true`, a **"Try the demo — no registration needed"** button appears below the login form. Clicking it signs you in as the demo user without entering credentials. The demo credentials (`demo@trek.app` / `demo12345`) are also displayed in the app config for reference, but the one-click button is the intended entry point. +When the server is started with `DEMO_MODE=true`, a **Try the demo** button ("no registration needed") appears below the login form. Clicking it signs you in as the demo user without entering credentials. The demo credentials (`demo@trek.app` / `demo12345`) are also part of the app config for reference, but the one-click button is the intended entry point. See [Demo-Mode](Demo-Mode). ## SSO If the admin has configured OpenID Connect, a **"Sign in with SSO"** button (labelled with the configured `OIDC_DISPLAY_NAME`, defaulting to `SSO`) appears below the login form. See [OIDC-SSO](OIDC-SSO) for details on setup and the sign-in flow. +If the identity provider's answer cannot be used, the login page shows why: registration is disabled for this instance, the provider sent no email address, the provider has not confirmed the email address so it cannot be linked to an existing account, or the sign-in could not be linked to the existing account with that email and your administrator has to confirm the address. + When OIDC-only mode is active (password login disabled), visiting `/login` automatically redirects the browser to the identity provider. The page only says where it is going ("Taking you to Keycloak…", with the configured display name) and offers nothing to fill in; should the redirect not have happened after eight seconds, a link to continue appears. The email/password form is never shown, not even while the page is still asking the server which sign-in it offers: until the answer arrives it shows a short wait, and on a repeat visit it announces the redirect straight away. The automatic redirect is suppressed when you have explicitly logged out, after a failed sign-in at the identity provider, and when the server could not be reached; the SSO button is shown instead so you can choose to sign back in. --- -**See also:** [OIDC-SSO](OIDC-SSO) · [Admin-Users-and-Invites](Admin-Users-and-Invites) · [Password-Reset](Password-Reset) +**See also:** [OIDC-SSO](OIDC-SSO), [Admin-Users-and-Invites](Admin-Users-and-Invites), [Password-Reset](Password-Reset) diff --git a/wiki/OIDC-SSO.md b/wiki/OIDC-SSO.md index bce9a6994..898cf794d 100644 --- a/wiki/OIDC-SSO.md +++ b/wiki/OIDC-SSO.md @@ -4,7 +4,7 @@ ## What OIDC gives you -OpenID Connect (OIDC) lets users log in with an existing identity provider — Google, Authentik, Keycloak, or any OIDC-compatible IdP — instead of a local email/password. On first SSO login, a TREK account is created automatically using the email from the provider. +OpenID Connect (OIDC) lets users log in with an existing identity provider (Google, Authentik, Keycloak, or any OIDC-compatible IdP) instead of a local email/password. On first SSO login, a TREK account is created automatically using the email from the provider. ## User flow @@ -16,7 +16,9 @@ OpenID Connect (OIDC) lets users log in with an existing identity provider — G The code is only half of what the exchange needs: the callback also sets a one-minute `HttpOnly` cookie (`trek_oidc_exchange`) holding a secret that never appears in a URL, and the exchange requires both. A code copied out of the address bar, out of history, or out of a proxy log is therefore worthless in any other browser, and it is spent by the first attempt to redeem it whether that attempt succeeds or not. If your reverse proxy strips cookies on the way back from the identity provider, SSO login will fail here with `Invalid or expired code`. 6. Your `trek_session` cookie is set and you land on the dashboard. -**Remember me.** The Remember-me switch on the login page is carried into SSO as a query flag on the login URL: `GET /api/auth/oidc/login?remember=1` (or `remember=0`), appended with `&` when an invite token is already present. Only `0` and `1` are accepted; any other value — and starting SSO from the register tab, where the switch is not shown — is treated as if the parameter were absent. The choice is held in the server-side login state, survives the provider round-trip and the one-time-code exchange, and decides both the session lifetime and the cookie lifetime: +If the sign-in fails, you are returned to the login page with a message: registration is disabled, the provider sent no email address, authentication failed, the session was invalid (try again), the provider has not confirmed your email address, or the sign-in could not be linked to the existing account with that email (ask your administrator to confirm the address, see [How an existing account gets linked](#how-an-existing-account-gets-linked)). + +**Remember me.** The Remember-me switch on the login page is carried into SSO as a query flag on the login URL: `GET /api/auth/oidc/login?remember=1` (or `remember=0`), appended with `&` when an invite token is already present. Only `0` and `1` are accepted; any other value (and starting SSO from the register tab, where the switch is not shown) is treated as if the parameter were absent. The choice is held in the server-side login state, survives the provider round-trip and the one-time-code exchange, and decides both the session lifetime and the cookie lifetime: | `remember` | Session lifetime | `trek_session` cookie | |---|---|---| @@ -34,7 +36,7 @@ Set the following environment variables before starting the server: | Variable | Required | Description | |---|---|---| -| `APP_URL` | Yes | Base URL of your TREK instance (e.g. `https://trek.example.com`). Used to build the redirect URI. **Env var only — not configurable via the admin panel.** If it is unset, TREK falls back to the first `ALLOWED_ORIGINS` entry, and only if that one is missing or unparseable to `http://localhost:{PORT}` — which produces a redirect URI your IdP will reject. A scheme-less `ALLOWED_ORIGINS=trek.example.com` does not parse, so it ends up on localhost too. A set but unparseable `APP_URL` does not fall back: the server refuses to start with `Invalid environment configuration` naming `APP_URL`. | +| `APP_URL` | Yes | Base URL of your TREK instance (e.g. `https://trek.example.com`). Used to build the redirect URI. **Env var only, not configurable via the admin panel.** If it is unset, TREK falls back to the first `ALLOWED_ORIGINS` entry, and only if that one is missing or unparseable to `http://localhost:{PORT}`, which produces a redirect URI your IdP will reject. A scheme-less `ALLOWED_ORIGINS=trek.example.com` does not parse, so it ends up on localhost too. A set but unparseable `APP_URL` does not fall back: the server refuses to start with `Invalid environment configuration` naming `APP_URL`. | | `OIDC_ISSUER` | Yes | Issuer URL of your identity provider. Must use HTTPS in production. | | `OIDC_CLIENT_ID` | Yes | OAuth 2.0 client ID registered with your IdP. | | `OIDC_CLIENT_SECRET` | Yes | OAuth 2.0 client secret. | @@ -53,15 +55,15 @@ For example: `https://trek.example.com/api/auth/oidc/callback` |---|---| | `OIDC_DISPLAY_NAME` | Label shown on the SSO button. Defaults to `SSO`. | | `OIDC_ONLY` | Set to `true` to disable local password login and password registration. SSO login and SSO registration remain governed by their own toggles. This is an environment-variable-only setting and cannot be toggled at runtime via the admin panel. | -| `OIDC_ADMIN_CLAIM` | OIDC claim to inspect for admin role mapping. Defaults to `groups`. The claim value may be an array or a plain string. The claim only reaches TREK if one of the scopes in `OIDC_SCOPE` carries it — see *Admin role mapping* below. **Env var only — not configurable via the admin panel.** | -| `OIDC_ADMIN_VALUE` | Value that must be present in `OIDC_ADMIN_CLAIM` to grant the admin role. If unset, claim-based role mapping is disabled. When set, the role is re-evaluated on every login. **Env var only — not configurable via the admin panel.** | +| `OIDC_ADMIN_CLAIM` | OIDC claim to inspect for admin role mapping. Defaults to `groups`. The claim value may be an array or a plain string. The claim only reaches TREK if one of the scopes in `OIDC_SCOPE` carries it (see *Admin role mapping* below). **Env var only, not configurable via the admin panel.** | +| `OIDC_ADMIN_VALUE` | Value that must be present in `OIDC_ADMIN_CLAIM` to grant the admin role. If unset, claim-based role mapping is disabled. When set, the role is re-evaluated on every login. **Env var only, not configurable via the admin panel.** | | `OIDC_USERNAME_CLAIM` | Claim the username of a new account is built from. Defaults to `name`, then `preferred_username`, then the part of the email before the `@`. Set it to `preferred_username` for providers like Pocket ID whose `name` is the full "Jane Doe". Only read when the account is created, so a username changed later in TREK stays; when the provider leaves the claim empty, the default order applies. **Env var only, not configurable via the admin panel.** | -| `OIDC_SCOPE` | Overrides the default scope list sent to the provider. Defaults to `openid email profile`. Ensure `openid` and `email` are always included, plus whichever scope carries your `OIDC_ADMIN_CLAIM`. **Env var only — not configurable via the admin panel.** | +| `OIDC_SCOPE` | Overrides the default scope list sent to the provider. Defaults to `openid email profile`. Ensure `openid` and `email` are always included, plus whichever scope carries your `OIDC_ADMIN_CLAIM`. **Env var only, not configurable via the admin panel.** | | `OIDC_DISCOVERY_URL` | Full URL to the OIDC discovery document. Use this for providers with non-standard discovery paths (e.g. Authentik tenants). If unset, discovery is attempted at `/.well-known/openid-configuration`. The discovery document is cached for 1 hour. | ## Admin role mapping -TREK requests exactly the scopes listed in `OIDC_SCOPE` and nothing else, and a provider only emits a claim when a requested scope carries it. So a claim that is not covered by `OIDC_SCOPE` never arrives, and a claim that never arrives can never grant the admin role — no matter how `OIDC_ADMIN_CLAIM` is spelled. +TREK requests exactly the scopes listed in `OIDC_SCOPE` and nothing else, and a provider only emits a claim when a requested scope carries it. So a claim that is not covered by `OIDC_SCOPE` never arrives, and a claim that never arrives can never grant the admin role, no matter how `OIDC_ADMIN_CLAIM` is spelled. Authentik is the usual example: `groups` rides the default `profile` scope, so it works out of the box, while `entitlements` has a scope of its own. Mapping admins onto an entitlement therefore takes all three variables: @@ -71,13 +73,13 @@ OIDC_ADMIN_VALUE=trek-admins OIDC_SCOPE=openid email profile entitlements ``` -Keycloak (group and role mappers carry their own "Add to userinfo" switch) and Entra ID (optional claims) behave the same way — whatever the claim is called, check that its scope is requested. +Keycloak (group and role mappers carry their own "Add to userinfo" switch) and Entra ID (optional claims) behave the same way: whatever the claim is called, check that its scope is requested. -If the configured claim is missing from the userinfo response entirely, TREK leaves the stored role untouched — a claim that never arrived is not a statement that somebody is no longer an admin — and writes one line to the server log naming the claim it looked for and the claims it did receive. Read that line first when role mapping does not do what you expect. A claim that *does* arrive without `OIDC_ADMIN_VALUE` in it still demotes on the next login; that is how the mapping takes admin away. Every role change it makes is recorded in the admin audit log. +If the configured claim is missing from the userinfo response entirely, TREK leaves the stored role untouched (a claim that never arrived is not a statement that somebody is no longer an admin) and writes one line to the server log naming the claim it looked for and the claims it did receive. Read that line first when role mapping does not do what you expect. A claim that *does* arrive without `OIDC_ADMIN_VALUE` in it still demotes on the next login; that is how the mapping takes admin away. Every role change it makes is recorded in the admin audit log. ### Taking admin away -Some providers omit a claim instead of sending it empty. Okta emits a filtered `groups` claim only when the filter matches at least one group, and Entra ID leaves `groups` out for a user who is in no group at all. **On those providers, removing somebody from the admin group does not demote them in TREK.** Their next login carries no claim, and no claim means no verdict, so the account keeps `admin` for as long as it exists. Take the role away in TREK as well, in **Admin → Users** ([Admin-Users-and-Invites](Admin-Users-and-Invites)) — the IdP side alone is not enough. +Some providers omit a claim instead of sending it empty. Okta emits a filtered `groups` claim only when the filter matches at least one group, and Entra ID leaves `groups` out for a user who is in no group at all. **On those providers, removing somebody from the admin group does not demote them in TREK.** Their next login carries no claim, and no claim means no verdict, so the account keeps `admin` for as long as it exists. Take the role away in TREK as well, in **Admin → Users** ([Admin-Users-and-Invites](Admin-Users-and-Invites)); the IdP side alone is not enough. TREK writes a warning to the server log on **every** login where this happens, naming the account, so `docker logs trek | grep OIDC` lists the users it affects: @@ -89,7 +91,7 @@ A provider that sends the claim as an empty list instead of dropping it is not a ## New-user registration via SSO -When an SSO login matches an existing TREK account by OIDC subject (`sub`), that account is used directly. When it matches only by **email**, the OIDC identity is linked to that account only if the provider asserts `email_verified` for it; if the claim is missing or false the login is rejected with an `email_not_verified` error, so an unverified address can never take over a local account. Make sure your IdP includes `email_verified` in the userinfo response — it is part of the `email` scope. If no matching account exists, TREK attempts to create one. The outcome depends on the following: +When an SSO login matches an existing TREK account by OIDC subject (`sub`), that account is used directly. When it matches only by **email**, the OIDC identity is linked to that account only if the provider asserts `email_verified` for it; if the claim is missing or false the login is rejected with an `email_not_verified` error, so an unverified address can never take over a local account. Make sure your IdP includes `email_verified` in the userinfo response; it is part of the `email` scope. If no matching account exists, TREK attempts to create one. The outcome depends on the following: - **First user ever**: always created as admin, no invite required. - **Open SSO registration enabled** (**SSO Auto-Provisioning** in **Admin → Settings**, card **Authentication Methods**; setting `oidc_registration`): account is created as a regular user. @@ -132,4 +134,4 @@ When password login and password registration are both off, through `OIDC_ONLY` --- -**See also:** [Login-and-Registration](Login-and-Registration) · [Environment-Variables](Environment-Variables) +**See also:** [Login-and-Registration](Login-and-Registration), [Environment-Variables](Environment-Variables) diff --git a/wiki/Passkeys.md b/wiki/Passkeys.md index dff3f7f8d..a52f6f6b9 100644 --- a/wiki/Passkeys.md +++ b/wiki/Passkeys.md @@ -8,22 +8,22 @@ Open **Settings** and select the **Account** tab. The **Passkeys** section sits > **Admin:** Passkey login is off by default. Turn on **Enable passkey login** in **Admin → Settings**, under the **Passkey login** card. -The section is hidden entirely when the feature is off and you have no passkeys enrolled. If you already have passkeys, the list stays visible even after an admin turns the feature off, so you can always clean them up. +The section is hidden entirely when the feature is off and you have no passkeys enrolled, and it is always hidden on the demo account. If you already have passkeys, the list stays visible even after an admin turns the feature off, so you can always clean them up. ## Enrolling a passkey 1. Click **Add a passkey**. -2. Enter your **current password** — TREK asks for it so a hijacked session cannot silently plant a passkey. +2. Enter your **current password**; TREK asks for it so a hijacked session cannot silently plant a passkey. 3. Optionally give the passkey a name (the placeholder suggests something like `iPhone`). Leave it blank and TREK names it **Passkey (synced)** or **Passkey** depending on the authenticator. 4. Click **Add a passkey** again and follow your device prompt (Touch ID, Windows Hello, Android screen lock, a YubiKey, and so on). -Every passkey is registered with *user verification required*, so a biometric or PIN check always happens — a bare "tap the key" gesture is not enough. The same authenticator cannot be enrolled twice on one account, and enrolment expires if you take longer than five minutes. +Every passkey is registered with *user verification required*, so a biometric or PIN check always happens; a bare "tap the key" gesture is not enough. The same authenticator cannot be enrolled twice on one account, and enrolment expires if you take longer than five minutes. If you dismiss the browser dialog you get **Passkey setup cancelled** and nothing is stored. ## Signing in with a passkey -On the login page, a **Sign in with a passkey** button appears below the password form (separated by an **or** divider). Click it, pick your passkey in the browser prompt, and you are signed straight in — no username, no password, no second step. +On the login page, a **Sign in with a passkey** button appears below the password form (separated by an **or** divider). Click it, pick your passkey in the browser prompt, and you are signed straight in; no username, no password, no second step. The button only shows when all of these hold: @@ -38,16 +38,16 @@ TREK never reveals which accounts have passkeys: the login ceremony uses discove Each entry in the list shows its name, a **Synced** or **This device** badge, the date it was **Added**, and either **Last used** with a date or **Never used**. -- **Rename** (pencil icon) — edit the name inline; press Enter to save, Escape to cancel. Names are capped at 60 characters. -- **Delete** (trash icon) — confirms with *Remove this passkey? Confirm with your password.* and requires your current password. +- **Rename** (pencil icon): edit the name inline; press Enter to save, Escape to cancel. Names are capped at 60 characters. +- **Delete** (trash icon): confirms with *Remove this passkey? Confirm with your password.* and requires your current password. -Removing every passkey can never lock you out — your password always remains as a fallback. +Removing every passkey can never lock you out; your password always remains as a fallback. > **Admin:** In **Admin → Users**, editing a user exposes a **Reset passkeys** action that removes all of that user's passkeys at once (for a lost device). The user can still sign in with their password. ## Passkeys and two-factor authentication -A user-verified passkey is already two factors — possession of the device plus a biometric or PIN — so it mints a session directly and does **not** prompt for a TOTP code afterwards. +A user-verified passkey is already two factors (possession of the device plus a biometric or PIN) so it mints a session directly and does **not** prompt for a TOTP code afterwards. The same reasoning applies to the admin **Require two-factor authentication (2FA)** policy: owning at least one passkey satisfies that policy exactly like an enabled TOTP authenticator does. A brand-new user under the policy can enrol a passkey instead of setting up an authenticator app; the enrolment endpoints stay reachable while the rest of the API is blocked, so nobody gets stuck. See [Two-Factor-Authentication](Two-Factor-Authentication). @@ -59,8 +59,8 @@ Passkeys are bound to a domain (the *Relying Party ID*). If no usable domain res Both values can be pinned with environment variables, which take priority over the Admin panel fields: -- `WEBAUTHN_RP_ID` — the registrable domain, e.g. `trek.example.com`. A pinned value is used verbatim, so it has to be a real domain: browsers refuse a bare IP address as a Relying Party ID. TREK checks for one only on the RP ID it derives from `APP_URL` — an IP host there resolves to nothing and the feature reports itself as not configured. -- `WEBAUTHN_ORIGINS` — comma-separated allowed origins, e.g. `https://trek.example.com`. +- `WEBAUTHN_RP_ID`: the registrable domain, e.g. `trek.example.com`. A pinned value is used verbatim, so it has to be a real domain: browsers refuse a bare IP address as a Relying Party ID. TREK checks for one only on the RP ID it derives from `APP_URL`; an IP host there resolves to nothing and the feature reports itself as not configured. +- `WEBAUTHN_ORIGINS`: comma-separated allowed origins, e.g. `https://trek.example.com`. See [Environment-Variables](Environment-Variables) for the full description of both. @@ -72,7 +72,7 @@ Login and enrolment attempts are rate limited per IP over a 15-minute window. ## Permissions -No TREK permission gates passkeys — any signed-in user can enrol and manage their own. Only the instance-wide toggle and the WebAuthn domain configuration are admin-controlled, and the **Reset passkeys** action is admin-only. +No TREK permission gates passkeys: any signed-in user can enrol and manage their own. Only the instance-wide toggle and the WebAuthn domain configuration are admin-controlled, and the **Reset passkeys** action is admin-only. ## See also diff --git a/wiki/Password-Reset.md b/wiki/Password-Reset.md index 999b3de9d..c91f01dc6 100644 --- a/wiki/Password-Reset.md +++ b/wiki/Password-Reset.md @@ -2,7 +2,7 @@ ## Self-service reset (Forgot password?) -TREK supports email-based self-service password reset. On the login page, click the **"Forgot password?"** link to go to `/forgot-password`. Enter your email address and submit — if the address matches a local account, a reset link is sent to that inbox. The page always shows the same confirmation message regardless of whether the email was found, to prevent account enumeration. +TREK supports email-based self-service password reset. On the login page, click the **"Forgot password?"** link to go to `/forgot-password`. Enter your email address and submit; if the address matches a local account, a reset link is sent to that inbox. The page always shows the same confirmation message regardless of whether the email was found, to prevent account enumeration. ![Reset your password card with a Back to sign in link, an email field and a Send reset link button, plus a warning that SMTP is unconfigured so the reset link is written to the server console](assets/PasswordReset.png) @@ -12,20 +12,20 @@ TREK supports email-based self-service password reset. On the login page, click 1. Click **"Forgot password?"** on the login page. 2. Enter your email address and submit. -3. Open the reset link from your email (or console) — valid for **60 minutes**. -4. Enter a new password. If your account has **MFA enabled**, you must also supply a valid TOTP code or backup code before the reset completes. -5. After a successful reset the page shows a **Password updated** confirmation ("You can now sign in with your new password.") with a **Sign In** button back to the login page — there is no automatic redirect. **All existing sessions are invalidated** — every device is signed out immediately. +3. Open the reset link from your email (or console), valid for **60 minutes**. +4. The link opens a **Set a new password** page. Enter a new password; the rules appear as a checklist under the field. If your account has **MFA enabled**, the page asks for your 2FA code or a backup code first and the button reads **Verify & reset** instead of **Reset password**. A link that is missing or broken shows **Invalid reset link** with a button to request a new one. +5. After a successful reset the page shows a **Password updated** confirmation ("You can now sign in with your new password.") with a **Sign In** button back to the login page, and there is no automatic redirect. **All existing sessions are invalidated** and every device is signed out immediately. ### Security properties | Property | Detail | |---|---| | Token entropy | 256-bit cryptographically random, base64url-encoded | -| Storage | Only the SHA-256 hash is stored in the database — never the raw token | +| Storage | Only the SHA-256 hash is stored in the database, never the raw token | | Expiry | 60 minutes, single-use; any prior unconsumed token is invalidated when a new one is issued | | Enumeration safety | `/forgot-password` always returns `{ok:true}` with a minimum response latency pad | | Rate limiting | 3 requests / 15-min per IP on `/forgot-password`; 5 requests / 15-min per IP on `/reset-password` | -| MFA gate | If the account has 2FA enabled, a valid TOTP code or backup code is required to complete the reset — a compromised mailbox alone cannot take over a 2FA-protected account | +| MFA gate | If the account has 2FA enabled, a valid TOTP code or backup code is required to complete the reset; a compromised mailbox alone cannot take over a 2FA-protected account | | Session invalidation | Resetting the password ends every session of the account on the server and bumps the `password_version` on the account and the `pv` claim in all JWTs, so every live session is rejected immediately, including ones from before sessions were tracked | | Audit log | `user.password_reset_request`, `user.password_reset_success`, and `user.password_reset_fail` events are recorded | @@ -35,15 +35,15 @@ The email delivery uses the same SMTP settings as other notification emails. See ### OIDC accounts -Any account linked to an identity provider cannot use the forgot-password flow — one created by SSO, but equally a local account that was auto-linked to the IdP on its first SSO login. The forgot-password page still shows the generic confirmation to avoid revealing whether the email is SSO-linked. Continue using [OIDC-SSO](OIDC-SSO) to sign in; a local password can still be set by an admin, or by you from **Settings → Account** if you know your current one. +Any account linked to an identity provider cannot use the forgot-password flow: one created by SSO, but equally a local account that was auto-linked to the IdP on its first SSO login. The forgot-password page still shows the generic confirmation to avoid revealing whether the email is SSO-linked. Continue using [OIDC-SSO](OIDC-SSO) to sign in; a local password can still be set by an admin, or by you from **Settings → Account** if you know your current one. ### Password login disabled -If the admin has globally disabled password login, no reset link is ever issued. For enumeration safety the endpoint still answers with the same generic confirmation, so the page looks exactly as it always does — the email (or the console line) simply never arrives. The refusal is recorded in the audit log as `user.password_reset_request` with `reason: password_login_disabled`. +If the admin has globally disabled password login, no reset link is ever issued. For enumeration safety the endpoint still answers with the same generic confirmation, so the page looks exactly as it always does; the email (or the console line) simply never arrives. The refusal is recorded in the audit log as `user.password_reset_request` with `reason: password_login_disabled`. ## Admin-initiated reset -An admin can set a new password for any user directly from the admin panel (**Admin → Users**, edit the user). Leaving the **New Password** field empty keeps the current password; entering one saves it immediately — no email is required. Setting a password this way also ends every session of the account and bumps its `password_version`, which signs the user out everywhere; separately, it deletes all of their MCP tokens and revokes their OAuth tokens. +An admin can set a new password for any user directly from the admin panel (**Admin → Users**, edit the user). Leaving the **New Password** field empty keeps the current password; entering one saves it immediately, no email is required. Setting a password this way also ends every session of the account and bumps its `password_version`, which signs the user out everywhere; separately, it deletes all of their MCP tokens and revokes their OAuth tokens. There is no **"Force password change on next login"** option in the Admin Panel. That prompt is raised only for the admin account TREK seeds on first boot and for accounts restored with the `reset-admin.js` recovery script (see [Troubleshooting](Troubleshooting)). An admin-set password neither raises the flag nor clears it, so a user who already carries it is still asked to choose their own password at the next sign-in. @@ -73,4 +73,4 @@ While you type, the form lists the five character rules under the password field --- -**See also:** [Login-and-Registration](Login-and-Registration) · [Admin-Users-and-Invites](Admin-Users-and-Invites) · [Two-Factor-Authentication](Two-Factor-Authentication) · [OIDC-SSO](OIDC-SSO) +**See also:** [Login-and-Registration](Login-and-Registration), [Admin-Users-and-Invites](Admin-Users-and-Invites), [Two-Factor-Authentication](Two-Factor-Authentication), [OIDC-SSO](OIDC-SSO) diff --git a/wiki/Two-Factor-Authentication.md b/wiki/Two-Factor-Authentication.md index ef6ccb2a1..0de5f2e88 100644 --- a/wiki/Two-Factor-Authentication.md +++ b/wiki/Two-Factor-Authentication.md @@ -8,9 +8,9 @@ TREK supports Time-based One-Time Password (TOTP) two-factor authentication, com ## Setting up 2FA -Go to **Settings → Account**, find the **Two-factor authentication (2FA)** section and click **Set up authenticator**. +Go to **Settings → Account**, find the **Two-factor authentication (2FA)** card (it is a card of its own, below Change Password) and click **Set up authenticator**. -1. A QR code and a text secret are displayed. Scan the QR code with your authenticator app. +1. A QR code and a **Secret key (manual entry)** are displayed. Scan the QR code with your authenticator app, or type the secret in by hand. > **Note:** The setup session expires after **15 minutes**. If you do not complete setup within that window, start again. 2. Enter the 6-digit code shown in your authenticator app and click **Enable 2FA**. 3. Save your **10 backup codes**. These are single-use codes shown only once, so store them somewhere safe (a password manager, printed paper). Each code has the format `XXXX-XXXX`. The **Backup codes** box offers **Copy codes**, **Download TXT** and **Print / PDF**. @@ -28,7 +28,7 @@ After entering your email and password, TREK shows a second prompt for your TOTP Go to **Settings → Account** and use the **Disable 2FA** form. You must provide both: - Your current account **password** -- A valid **TOTP code** from your authenticator app +- A current **6-digit code** from your authenticator app, or an unused **backup code** Disabling 2FA signs out every other session of your account: the second factor is what kept a stolen password out of them. The session you disabled it from stays signed in, since it just proved both the password and the code. @@ -36,15 +36,15 @@ Disabling 2FA signs out every other session of your account: the second factor i ## Admin-enforced 2FA -An admin can require 2FA for all users. Before enabling this setting the admin must have secured their own account with either an authenticator app or a passkey — the server rejects the change otherwise with *Secure your own account with two-factor authentication or a passkey before requiring it for all users.* +An admin can require 2FA for all users. Before enabling this setting the admin must have secured their own account with either an authenticator app or a passkey; the server rejects the change otherwise with *Secure your own account with two-factor authentication or a passkey before requiring it for all users.* -If the setting is active and your account has neither 2FA nor a passkey, any API request after login returns a 403 error and the client redirects you to **Settings → Account** with a prompt to complete 2FA setup. You cannot use the app until setup is complete. See [Admin-Permissions](Admin-Permissions). +If the setting is active and your account has neither 2FA nor a passkey, any API request after login returns a 403 error and the client redirects you to **Settings → Account** with a prompt to complete 2FA setup. The 2FA card also carries a notice that your administrator requires it. You cannot use the app until setup is complete. See [Admin-Permissions](Admin-Permissions). -A user-verified **passkey** satisfies this policy the way a TOTP authenticator does: with at least one passkey on your account the API stops blocking you and you never need an authenticator app. That holds even if an admin later turns passkey login off again — an existing passkey keeps satisfying the policy. Real-time sync is the one exception: the WebSocket handshake accepts only TOTP, so a passkey-only account under this policy can use TREK normally but never receives live updates from other members. Nothing tells you — the client simply keeps retrying the connection. +A user-verified **passkey** satisfies this policy the way a TOTP authenticator does: with at least one passkey on your account the API stops blocking you and you never need an authenticator app. That holds even if an admin later turns passkey login off again: an existing passkey keeps satisfying the policy. Real-time sync is the one exception: the WebSocket handshake accepts only TOTP, so a passkey-only account under this policy can use TREK normally but never receives live updates from other members. Nothing tells you; the client simply keeps retrying the connection. -Whether enrolling a passkey is a way *out* of the lockout depends on the instance. Passkey login is off by default (see [Passkeys](Passkeys)); where an admin has turned it on, the enrolment endpoints stay reachable while the rest of the API is blocked, so you can add a passkey from **Settings → Account** instead of setting up an authenticator app. Where it is off, TOTP setup is the only way to unblock yourself — or ask an admin to reset your 2FA. +Whether enrolling a passkey is a way *out* of the lockout depends on the instance. Passkey login is off by default (see [Passkeys](Passkeys)); where an admin has turned it on, the enrolment endpoints stay reachable while the rest of the API is blocked, so you can add a passkey from **Settings → Account** instead of setting up an authenticator app. Where it is off, TOTP setup is the only way to unblock yourself, or ask an admin to reset your 2FA. -> **Admin:** You can clear a locked-out user's 2FA with `DELETE /api/admin/users//mfa` (admin session required; it refuses your own account). It also signs that user out of every session. The admin panel has no button for it: the user modal offers only **Reset passkeys**. See [Troubleshooting](Troubleshooting#locked-out-of-mfa--lost-authenticator). +> **Admin:** You can clear a locked-out user's 2FA from **Admin → Users**: open the user and use **Reset 2FA** (it is not offered for your own account). It switches 2FA off for that user and signs them out of every session, and they can set it up again after logging in with their password. The same action is available as `DELETE /api/admin/users//mfa`. See [Troubleshooting](Troubleshooting#locked-out-of-mfa--lost-authenticator). ## Rate limits @@ -63,4 +63,4 @@ The demo user account cannot enable or disable MFA. --- -**See also:** [Login-and-Registration](Login-and-Registration) · [Passkeys](Passkeys) · [Admin-Permissions](Admin-Permissions) · [Admin-Users-and-Invites](Admin-Users-and-Invites) · [User-Settings](User-Settings) +**See also:** [Login-and-Registration](Login-and-Registration), [Passkeys](Passkeys), [Admin-Permissions](Admin-Permissions), [Admin-Users-and-Invites](Admin-Users-and-Invites), [User-Settings](User-Settings)