mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
c6d1631afe
* feat(recovery): add safe-mode recovery surface and emergency CLI Add a read-only Recovery tab under Settings (admin-only) backed by a new GET /api/diagnostics endpoint reporting app version, database integrity, encryption-key status, Docker reachability, account and SSO counts, and non-secret configuration. The endpoint loads without Docker or live metrics so it stays available when the dashboard does not, requires a genuine admin session, and builds its config block from a non-secret allowlist so no credentials are ever exposed. Expand the emergency command-line toolkit beyond the two-factor reset with seven host-level commands: reset-password, create-emergency-admin, clear-sessions, disable-sso, diagnostics, validate-db, and backup-data. Each prints its result, exits with a meaningful status code, and writes an audit entry where it changes state. Document the toolkit in a new operator guide and link it from the recovery and two-factor pages. * feat(recovery): download the emergency command reference as a text file The recovery commands are needed exactly when the dashboard is unreachable, so reading them only in-app is a chicken-and-egg problem. Add a Download button to the command-line section that saves the full `docker compose exec sencho ...` reference as a text file, letting operators keep it on hand before they need it. Reuses a shared download helper with the existing diagnostics export. * fix(recovery): harden diagnostics, backup, and emergency-admin against edge cases Address findings from an independent review of the recovery toolkit: - DiagnosticsService now degrades instead of throwing when a queried table is missing or corrupt: each read falls back and is folded into database.ok, so a broken database reports "problem detected" rather than failing the whole endpoint or showing a misleading healthy state with zeroed counts. - backup-data refuses a destination that resolves to the live database, which would otherwise report success while producing no separate copy. - create-emergency-admin now applies the same username rule as the user- management route, extracted to a shared helper so both stay in sync. Adds tests for a missing read table, a malformed emergency-admin username, and the backup same-target rejection.
80 lines
5.6 KiB
Plaintext
80 lines
5.6 KiB
Plaintext
---
|
|
title: Managing Two-Factor Authentication
|
|
description: Reset a user's 2FA, recover from lockouts, and understand the per-user vs per-provider MFA toggles.
|
|
---
|
|
|
|
<Note>
|
|
This page is for administrators handling 2FA on behalf of other operators. For general 2FA usage (enrolment, recovery codes, the sign-in challenge), see [Two-Factor Authentication](/features/two-factor-authentication).
|
|
</Note>
|
|
|
|
## Reset a user's 2FA
|
|
|
|
A user who has lost both their authenticator app and their remaining backup codes cannot sign in on their own. Any administrator can reset the affected account from the Settings UI.
|
|
|
|
1. Open **Settings · Users**.
|
|
2. Find the user in the list. Users with 2FA enabled show a shield-off icon (warning color) in the action column.
|
|
3. Click the shield icon and confirm the reset.
|
|
|
|
<Frame>
|
|
<img src="/images/two-factor-auth/admin-reset.png" alt="Reset 2FA confirmation modal opened from the Users panel. The header shows the kicker USERS RESET 2FA and the italic display title Reset 2FA for viewer. The body reads Removes the user's authenticator enrolment and backup codes They will sign in with just their password on their next login and can re-enrol from their account settings Use this when a user has lost access to their authenticator. The footer has Cancel and Reset 2FA buttons." />
|
|
</Frame>
|
|
|
|
The modal copy is verbatim:
|
|
|
|
> Removes the user's authenticator enrolment and backup codes. They will sign in with just their password on their next login and can re-enrol from their account settings. Use this when a user has lost access to their authenticator.
|
|
|
|
After confirming:
|
|
|
|
- The user can sign in with their password alone; no second factor is required.
|
|
- The user's token version is bumped, so every existing session of theirs returns `401` on its next API request.
|
|
- The action is recorded in the audit log under the administrator's username.
|
|
|
|
Tell the user to re-enrol from **Settings · Account · Two-factor authentication · Set up 2FA** as soon as they are back in. The account is unprotected until they do.
|
|
|
|
## Emergency recovery from the command line
|
|
|
|
If every administrator has lost access to 2FA and no one can sign in through the UI, reset the admin account directly on the host running Sencho.
|
|
|
|
From a shell on that host:
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/resetMfa.js <username>
|
|
```
|
|
|
|
Replace `<username>` with the admin's account name. On success the command prints a confirmation line and exits with code 0. Sign in with the password, then re-enrol immediately.
|
|
|
|
The command respects the container's `DATA_DIR`, so it always acts on the same SQLite database the application uses. It writes an audit-log entry attributed to `cli` so the action is auditable after the fact.
|
|
|
|
This is one of several host-level recovery commands. See [Emergency command-line recovery](/operations/emergency-cli) for the full set, including password reset, creating an emergency admin, and disabling a broken SSO provider.
|
|
|
|
<Note>
|
|
Enabling **Developer Mode** under **Settings · Developer** surfaces additional `[MFA:diag]` lines in the backend logs. They are helpful when investigating a 2FA support ticket and can be turned off again once the issue is resolved.
|
|
</Note>
|
|
|
|
## SSO and 2FA: two independent toggles
|
|
|
|
When SSO (LDAP or OIDC) is configured, users with 2FA enabled sign in through SSO **without** a second factor by default. SSO is already an authenticated flow, and a TOTP on top is extra friction most teams do not need.
|
|
|
|
Two separate toggles let you change this, and they are independent:
|
|
|
|
| Toggle | Where it lives | Tier | What it does |
|
|
|--------|----------------|------|--------------|
|
|
| **Require 2FA on SSO sign-in** | Each user's own **Settings · Account · Two-factor authentication** section | All tiers | Per-user opt-in. When on, that one user's SSO sign-ins also require a TOTP after the SSO flow returns. Helper text: `By default, SSO logins skip the second factor. Enforce it here to require both.` |
|
|
| **Require MFA** (per provider) | The provider config under **Settings · SSO** | Admiral (LDAP), Skipper (preset OIDC), Community (Custom OIDC) | Admin-set, fleet-wide for that provider. When on, every SSO-provisioned user must enrol TOTP after their first successful sign-in before they can use the rest of the console. |
|
|
|
|
The per-user toggle decides *whether a TOTP is asked for on every SSO sign-in*. The per-provider toggle decides *whether new SSO users are forced to enrol TOTP at all*. Both can be on at once: the per-provider toggle ensures enrolment, the per-user toggle then asks for the TOTP on every sign-in.
|
|
|
|
If your organisation needs a fleet-wide policy that asks every SSO user for a TOTP on every sign-in, raise this with the Sencho team; it is not exposed as a global setting today. The closest workaround is to enable both toggles for every user.
|
|
|
|
For the user-facing view of the per-user toggle, see [Two-Factor Authentication · SSO sign-in](/features/two-factor-authentication#sso-sign-in). For provider configuration and the per-provider toggle, see [SSO Authentication](/features/sso).
|
|
|
|
## What a reset changes in the database
|
|
|
|
For completeness, an administrator reset performs the following on the target user:
|
|
|
|
- Clears the stored TOTP secret and all remaining backup codes.
|
|
- Rotates the user's token version, invalidating any outstanding session cookies and Bearer tokens bound to that user.
|
|
- Leaves everything else untouched: the username, password hash, role, scoped permissions, and audit history are preserved.
|
|
|
|
Nothing about the user's SSO bindings changes. If the user was signing in with SSO plus enforced 2FA, they resume SSO-only sign-in after the reset (until they re-enrol, at which point the same toggles apply again).
|