Skip to content
GitHub

Sign-in and security

Use this guide to sign in, protect your account with an authenticator and understand password rules. Two-factor is required when enabled on your account or enforced by an administrator.

For devices, idle timeouts and forced sign-out, see Session management. For setting names and defaults, see Security configuration.

Preview the sign-in page
Sign-in page: password, SMS and third-party sign-in
  • Sign-in page (/sign-in): everyone can open it.
  • Profile (/profile): change your password, bind a phone or authenticator, link third-party accounts, and review recent sign-ins.
  • System → Users (/system/user): superusers reset passwords and two-factor for others.
  • System → Config (/plugins/config): change policies with sys:config:edit.
  • Logs → Sign-in log (/log/login): inspect attempts with log:login:list.

Password and two-factor resets require a superuser, regardless of menu permissions.

MethodBefore you sign in
Username and passwordEnter your account, password and the image captcha enabled by default
SMS codeThe SMS plugin must be installed; first verify and bind your number in Profile
GitHub / GoogleThe OAuth2 plugin must be configured; sign in with your password first and link your account in Profile

An admin-entered or imported phone number cannot be used for SMS sign-in until its owner verifies it. Unknown third-party accounts are refused by default; automatic registration settings must be enabled explicitly.

There is no self-service password recovery: the sign-in page says “Ask an admin to reset your password”.

An administrator first sets MFA_SECRET_KEY in apps/api/backend/.env and restarts the API. It must be 64 hex characters; generate it with:

终端窗口
python -c "import os;print(os.urandom(32).hex())"

An empty key prevents enabling or requiring two-factor. This is a server secret; keep it out of shared documentation and screenshots.

  1. Open Profile → Two-factor authentication and start setup.
  2. Scan the QR code with an authenticator such as Google Authenticator, Microsoft Authenticator or 1Password.
  3. Enter a current code to confirm and save the 10 recovery codes shown next.

With a current code, you can also turn two-factor off or regenerate recovery codes in Profile, unless policy requires it.

Expected result: after signing out and back in, you are asked for a code at the second step. SMS and third-party sign-in use this step too when two-factor applies.

Under System → Config → Sign-in policy, set Require two-factor:

ValueResult
offEach user chooses whether to enable it
superuserRequired for superusers
allRequired for everyone

An unenrolled user must bind an authenticator during the next web sign-in before entering the system. Required users cannot turn it off. The mobile app accepts codes, but initial enrollment must be completed on the web.

RuleDefaultAllowed range
Length6–32 characters1–128
Must contain a special characterNo—
Cannot repeat one of the last N passwords30–24
Valid for365 days (0 = never expires)0–3650
Reminder lead time7 days (0 = no reminder)0–365

Change your password under Profile. Administrators adjust these rules under System → Config → Passwords & lockout; the backend enforces the same ranges.

Changing your own password, or having it reset by an admin, ends every session of that account (reason: password changed), including the current one.

How many wrong passwords before a lockout?

Section titled “How many wrong passwords before a lockout?”

By default, 5 consecutive failures lock an account for 5 minutes. Across accounts, 30 failures from one IP lock it for 15 minutes. Messages do not reveal whether an account exists or is locked.

Account thresholds are under System → Config → Passwords & lockout; per-IP limits are configured in .env. Behind a reverse proxy, set TRUSTED_PROXIES so IP-based protection uses the correct address. See Security configuration for keys and rate limits.

Superusers view and revoke sessions under Monitoring → Active sessions. The Session management guide covers device limits, idle timeouts and each sign-out message.

  • The only second factors are TOTP and recovery codes: no passkeys (WebAuthn), no hardware keys, and SMS is not offered as a second factor.
  • No self-service password recovery or self-registration (except third-party sign-in with auto-registration explicitly turned on).
  • The password expiry reminder is not shown in the web client yet, and an expired password cannot be changed by its owner; see above.
  • Session operations use single-instance Redis Lua scripts; Redis Cluster has not been tested. See Session management.
  • Security configuration: all settings, extension points, source links and existing test coverage.
  • Try session management: observe two sessions on the shared demo. Test MFA locally; the demo may not have a key configured.