Users
The Users page manages all user accounts in the system. Users can authenticate via local password, external SSO (OIDC), or both. Each user is assigned one or more roles that determine their permissions. The Owner account is created during initial setup and cannot be modified or deleted.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Username | Display name for the user | Non-empty string | — |
Email | Email address used for login and notifications | Valid email address | — |
Password | Local authentication password | Any string (required unless auth method is SSO-only) | — |
Auth Method | How the user authenticates | Local, SSO, SSO + Local | Local |
Roles | Roles assigned to the user (determines permissions) | One or more existing roles | — |
Fields & columns
| Name | Description |
|---|---|
Username | The user display name (not editable inline) |
Email | Editable inline — the user email address |
Auth | Editable inline — authentication method (Local, SSO, or SSO + Local) |
Roles | Combined list of assigned roles, with Owner highlighted in yellow |
How to
Create a new user
- Navigate to Admin > Identity > Users.
- Click Create User.
- Enter the username, email, and initial password.
- Assign one or more roles.
- Click Save to create the account.
Reset a user's MFA (lost authenticator)
- Confirm the user has genuinely lost their second factor and exhausted their recovery codes.
- Navigate to Admin > Identity > Users and find the user row.
- Use the Reset MFA action for that user.
- This clears their TOTP secret and all recovery codes; the user is forced to enroll a fresh second factor on next login.
- The reset is audited and emits an mfa.admin_reset security event recording who reset whom.
Gotchas
- The Owner account cannot be modified or deleted — it bypasses all scope checks.
- SSO-only users do not have a local password and can only log in through the external identity provider.
- Deleting a user is permanent and removes all role assignments for that user.
- Passwords must be at least 12 characters (NIST SP 800-63B aligned). Account lockout triggers after 10 consecutive failed login attempts, lasting 15 minutes.
- Resetting MFA wipes a user's TOTP secret and all recovery codes, forcing fresh enrollment on next login. Reserved for genuinely locked-out users — it lowers their authentication bar until they re-enroll.
- The Owner account's MFA cannot be reset from this page (403). An owner is the Day-0 break-glass account, so its MFA is cleared only via the host-access break-glass CLI (scripts/ops/mfa-break-glass.ts, run with docker compose exec), where host trust is the control.
API calls (7)
| Method | Path | Description |
|---|---|---|
| GET | /api/admin/identity/users | List all users with their roles |
| POST | /api/admin/identity/users | Create a new user |
| PUT | /api/admin/identity/users/:id | Update user email or auth method |
| DELETE | /api/admin/identity/users/:id | Delete a user |
| POST | /api/admin/identity/users/:userId/roles/:roleId | Assign a role to a user |
| DELETE | /api/admin/identity/users/:userId/roles/:roleId | Remove a role from a user |
| POST | /api/admin/identity/users/:id/mfa/reset | Reset a user's MFA (clears TOTP + recovery codes; owners are reset via the break-glass CLI, not this route) |
Related
- Roles — Roles define the scopes (permissions) assigned to users
- OIDC — Configure the external identity provider for SSO users
- Auth Events — Tracks login attempts by these user accounts