# Users and Two-Factor Auth

This page covers local user accounts, passwords and two-factor authentication. Single sign-on is described separately in [Single Sign-On (SSO)](/documentation/single-sign-on).

> **Roles:** Managing users and resetting authenticators is for `admin` only. Any signed-in user can change their own password on the Profile page.

## Creating the first administrator

Bootstrap the first `admin` from the command line:

```bash
docker compose exec docs-hub docs-hub --create-user \
  --user-login admin --user-password change-me --user-role admin
```

You can pass `--user-password-hash` (a bcrypt hash) instead of a plain password for non-interactive provisioning. See [CLI Reference](/documentation/cli-reference).

## Managing users in the UI

Open **Users** in the top menu (`/users`). The table lists existing users with **Edit** and **Delete** actions, and a **Create user** button opens a form. The list can be filtered by login (substring), role (`admin`, `editor`, `reader`) and status (`active`, `disabled`). The **Sign-in** column shows each user's sign-in methods.

- Passwords are stored only as bcrypt hashes.
- A user can be **disabled**. The account stays but cannot sign in, which is useful to revoke access temporarily.
- Editing a user to `admin` clears team memberships, because admins are exempt from team scoping.
- Creating users is limited by the `max_users` limit of your license.

## Signing in

Sign-in uses `/login`. A successful login returns a signed token that the browser stores and sends as a bearer token on later requests. Signing out forgets the token. Wrong login and wrong password return the same generic error, and repeated attempts are rate-limited per login and client IP.

"Remember me" on the login form lengthens the token lifetime from `session_timeout` (8 hours by default) to `remember_me_timeout` (30 days). It applies to password sign-in only.

## Two-factor authentication

An administrator can switch on two-factor authentication (TOTP, for example Google Authenticator) per user:

1. The administrator enables it for the user in the Users section.
2. At the next login the user is asked to pair an authenticator: scan the QR code, enter a confirmation code and save the one-time backup codes.
3. From then on the user enters a code after the password on every login.

An administrator can also **reset** a user's authenticator, for example after a lost phone. The secrets are stored encrypted with a key derived from `session_secret`. If you change that secret, existing secrets become unreadable and you must reset those users' authenticators.

Users who sign in through an SSO provider with **Trust the provider's MFA** enabled skip the local code.

## Profile page

Every signed-in user has a **Profile** page (`/profile`, from the menu or by clicking the user at the bottom of the sidebar). It shows login, role and teams. In **Sign-in methods** a user can set or change the password (8–72 bytes) and link or unlink SSO providers. The last remaining way to sign in cannot be removed.

## Next steps

- [Roles and Permissions](/documentation/roles-and-permissions)
- [Teams](/documentation/teams)
- [Single Sign-On (SSO)](/documentation/single-sign-on)

---
Source: https://selfdochub.com/documentation/users-and-two-factor
