mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
ce08a593d7
* refactor(settings): split System Limits and regroup the hub System Limits had grown into a grab-bag of host alert thresholds, Docker cleanup, and mesh data-plane controls under one mislabeled section. Split it into Host Alerts, Docker & Storage, and Fleet Mesh, and split Developer into Developer Diagnostics and Data Retention. Reorganize the sidebar into ten domain groups: Personal, Access, Infrastructure, Monitoring, Notifications, Automation, Organization, Security, Operations, Help. Each section now saves only its own keys, so a concurrent edit in one section no longer clobbers another. Data Retention sends the audit-log window only on a paid plan, matching the field's existing visibility, so a Community save no longer fails on a key the operator cannot set. NumberChip moves to a shared module and the toggle reuses the existing shared component. The /settings API is unchanged. * test(settings): cover registry structure and per-section save payloads Add structural invariants for the ten-group registry (every item maps to a real group, ids are unique, the System Limits and Developer splits land in the right groups with the right gates, renamed labels and the Registries paid gate hold) and per-section payload tests asserting each split section patches only its own keys, including the Community path where Data Retention omits the paid audit-log key. * docs(settings): document the regrouped settings hub Rewrite the settings reference for the ten-group layout, replace the System Limits page with Host Alerts, Docker & Storage, and Fleet Mesh, and document the prune-on-update, reclaimable-space banner, and mesh auto-recreate settings that were previously undocumented. Update the Settings navigation breadcrumbs across the feature docs and refresh the affected screenshots. * fix(settings): show Access sections as instance-global, not operator-scoped License, Users, SSO, and API Tokens are instance-global settings but the masthead scope label rendered them as operator-scoped because it keyed off the old Identity group. Only Personal sections (account, appearance) are operator/browser-scoped now; everything else reads as global. Also add a compile-time exhaustiveness guard to the section switch so a future SectionId added without a matching case fails the build instead of silently rendering a blank panel. * docs(settings): remap remaining settings breadcrumbs to the new groups Update the navigation breadcrumbs that still pointed at the removed Identity, Alerts, and Advanced groups: API Tokens and Users now sit under Access, Webhooks under Automation, Labels under Organization, App Store under Infrastructure, Appearance under Personal, and scan policies under Security > Vulnerability Scanning. Correct the settings reference scope note so Access reads as global. * docs(settings): remap renamed-section breadcrumbs across feature docs Sweep every feature, operations, getting-started, and reference page for navigation paths that still named the renamed settings sections, and point them at the current ones: Security becomes Security > Vulnerability Scanning, Notifications becomes Notifications > Channels, Routing becomes Notifications > Notification Routing, and Developer becomes Operations > Developer Diagnostics (with its retention windows under Operations > Data Retention). App Store moves under Infrastructure and the four-group overview in the getting-started intro is rewritten to the ten groups. Separators each page already used are preserved.
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 · Operations · Developer Diagnostics** 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), Community (Custom OIDC and preset 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).
|