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).
Roles: Managing users and resetting authenticators is for
adminonly. 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:
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.
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
adminclears team memberships, because admins are exempt from team scoping. - Creating users is limited by the
max_userslimit 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:
- The administrator enables it for the user in the Users section.
- 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.
- 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.