# Sign-in and security

> Choose a sign-in method, enable two-factor authentication and manage password rules. Session management and configuration have their own guides.

Source: https://yile2020.github.io/fastapi-react-admin/en/features/login-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](https://yile2020.github.io/fastapi-react-admin/en/features/login-sessions/). For setting names and defaults, see [Security configuration](https://yile2020.github.io/fastapi-react-admin/en/reference/security-config/).

<details>
<summary>Preview the sign-in page</summary>

</details>

## Where is it in the UI?

- **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.

## Which sign-in methods are there?

| Method | Before you sign in |
|---|---|
| Username and password | Enter your account, password and the image captcha enabled by default |
| SMS code | The SMS plugin must be installed; first verify and bind your number in Profile |
| GitHub / Google | The 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](https://yile2020.github.io/fastapi-react-admin/en/reference/security-config/#change-settings-in-env) must be enabled explicitly.

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

## How does two-factor (MFA) work?

### 1. Prepare the server key

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:

```bash
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.

### 2. Bind an authenticator

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.

:::caution[Save recovery codes at setup]
Recovery codes are shown only once and each works once. Generating a new batch invalidates the previous batch. If you lose your authenticator, use an unused recovery code or ask a superuser to reset two-factor under Users.
:::

### 3. Require it for your team, if needed

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

| Value | Result |
|---|---|
| `off` | Each user chooses whether to enable it |
| `superuser` | Required for superusers |
| `all` | Required 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.

## What are the password rules?

| Rule | Default | Allowed range |
|---|---|---|
| Length | 6–32 characters | 1–128 |
| Must contain a special character | No | — |
| Cannot repeat one of the last N passwords | 3 | 0–24 |
| Valid for | 365 days (0 = never expires) | 0–3650 |
| Reminder lead time | 7 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.

:::caution[Two gaps around password expiry]
- Once the reminder window starts, the sign-in response includes `password_expire_days_remaining`, but **the web client does not show it yet**.
- After expiry, password and SMS sign-in are both refused (third-party sign-in does not check password age). The message says to change the password and sign in again, but the user can no longer sign in to do so; only a superuser can reset it under Users.
:::

## 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](https://yile2020.github.io/fastapi-react-admin/en/reference/security-config/) for keys and rate limits.

<span id="how-many-devices-can-one-account-use-and-when-does-an-idle-session-end"></span>

<span id="what-does-a-signed-out-person-see"></span>

## Manage signed-in devices

Superusers view and revoke sessions under **Monitoring → Active sessions**. The [Session management guide](https://yile2020.github.io/fastapi-react-admin/en/features/login-sessions/) covers device limits, idle timeouts and each sign-out message.

## What it does not do

- 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](#what-are-the-password-rules).
- Session operations use single-instance Redis Lua scripts; Redis Cluster has not been tested. See [Session management](https://yile2020.github.io/fastapi-react-admin/en/features/login-sessions/).

<span id="which-settings-are-there"></span>

<span id="what-to-watch-when-adding-a-sign-in-method-or-a-way-to-sign-someone-out"></span>

<span id="where-is-the-code"></span>

<span id="how-is-it-tested"></span>

<span id="try-it-on-the-demo"></span>

## Configuration and development reference

- [Security configuration](https://yile2020.github.io/fastapi-react-admin/en/reference/security-config/): all settings, extension points, source links and existing test coverage.
- [Try session management](https://yile2020.github.io/fastapi-react-admin/en/features/login-sessions/#try-it-on-the-demo): observe two sessions on the shared demo. Test MFA locally; the demo may not have a key configured.
