Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.
TypeScript cloud-alternativecollaborationcollaborative-editingdropboxfile-serverfile-sharingfile-storagefile-syncfull-text-searchhomelabnextcloudon-premiseopen-sourceprivacy-firstprivate-cloudrealtimesecureself-hostedstorage-serverwebdav
docs(backend:auth): add two-factor authentication documentation
johaven904dd2b80b98
diff --git a/backend/src/authentication/providers/two-fa/two-fa.md b/backend/src/authentication/providers/two-fa/two-fa.mdnew file mode 100644index 00000000..cd78574c--- /dev/null+++ b/backend/src/authentication/providers/two-fa/two-fa.md@@ -0,0 +1,207 @@+# Two-Factor Authentication++Sync-in provides local two-factor authentication (2FA) through TOTP. This module is not selected by `auth.provider`; it is a shared step-up layer used+by local password authentication, LDAP authentication, selected account-management routes, administrator actions, API token issuance, and client+registration.++The current implementation supports:++- six-digit TOTP codes;+- QR-code setup from an `otpauth://` URL;+- pending setup secrets cached for five minutes;+- optional encryption of stored TOTP secrets and recovery codes with `auth.encryptionKey`;+- five single-use recovery codes generated when TOTP is enabled;+- browser login verification through a temporary 2FA cookie;+- bearer-token issuance with TOTP verification through a request header;+- current-password confirmation for enable, disable, and selected step-up routes;+- administrator reset of another user's TOTP after administrator step-up verification;+- local-password fallback for routes that require a step-up when the user has no active TOTP secret.++TOTP is controlled globally by `auth.mfa.totp.enabled`, which defaults to `true`. A user is considered TOTP-enabled when their stored secrets contain+`twoFaSecret`.++## Browser login flow++1. The client posts credentials to `/api/auth/login`.+2. The configured password provider validates the login and password.+3. If global TOTP is disabled or the user has no `twoFaSecret`, Sync-in issues the final local session cookies immediately.+4. If TOTP is required, Sync-in issues only temporary 2FA cookies and returns a response whose user payload contains `twoFaEnabled: true`.+5. The client posts a TOTP code or recovery code to `/api/auth/2fa/login/verify`.+6. Sync-in validates the temporary 2FA access cookie, CSRF header, account access, and verification code.+7. On success, Sync-in issues the final local session cookies and clears the temporary 2FA access cookie.++The temporary access cookie uses the same cookie name as the regular access cookie, but is scoped to `/api/auth/2fa/login/verify` and has token type+`access_2fa`. The temporary CSRF cookie uses the normal CSRF cookie name and is replaced by the final CSRF cookie after successful verification.++Temporary 2FA cookies expire after five minutes. The temporary JWT intentionally contains only the minimum identity data required to finish login:+user ID, login, language, role, and `twoFaEnabled: true`.++## Setup flow++TOTP setup starts with:++```text+GET /api/auth/2fa/enable+```++The route is authenticated and limited to regular users. It returns:++| Field | Description |+|-------------|---------------------------------------------------------------|+| `secret` | TOTP secret shown to the user for manual authenticator setup. |+| `qrDataUrl` | QR code data URL generated from the TOTP setup URL. |++Sync-in stores the pending setup secret in cache for five minutes. The response disables caching with `Cache-Control: no-store`.++The user completes setup with:++```text+POST /api/auth/2fa/enable+```++Body:++| Field | Required | Description |+|------------------|----------|-------------------------------------------------------------------------|+| `password` | Yes | Current local Sync-in password. |+| `code` | Yes | TOTP code generated from the pending secret. |+| `isRecoveryCode` | No | Shared verification flag; setup is normally completed with a TOTP code. |++When the password and code are valid, Sync-in stores the TOTP secret in user secrets, generates five recovery codes, removes the pending cache entry,+and sends an email notification when mail notifications are available. Recovery codes are returned only in this enable response.++If the pending secret has expired, setup fails and the user must start again with `GET /api/auth/2fa/enable`.++## Disable flow++TOTP is disabled with:++```text+POST /api/auth/2fa/disable+```++Body:++| Field | Required | Description |+|------------------|----------|-----------------------------------------------|+| `password` | Yes | Current local Sync-in password. |+| `code` | Yes | TOTP code or recovery code. |+| `isRecoveryCode` | No | Set to `true` when `code` is a recovery code. |++On success, Sync-in removes both `twoFaSecret` and `recoveryCodes` from user secrets and sends an email notification when mail notifications are+available.++## Recovery codes++Enabling TOTP generates five recovery codes. They are stored in user secrets after applying the same secret encryption rule as the TOTP secret.++Recovery codes are single-use. Validation is transactional: only the request that still finds the encrypted code in the latest user secrets can+consume it successfully. A consumed or unknown recovery code returns `Invalid code`.++Recovery codes can be used for:++- browser login verification;+- disabling TOTP;+- client registration when the user has TOTP enabled.++Step-up guards that read the `sync-in-two-fa-code` header validate that header as a TOTP code only; they do not set `isRecoveryCode`.++## Step-up guards++Some authenticated routes require a fresh 2FA or password step-up. Sync-in exposes three guard variants:++| Guard | Password header | TOTP header | Behavior |+|---------------------------------------------|-------------------------------------|-----------------------------------|-----------------------------------------------------------------------|+| `AuthTwoFaVerificationGuard` | Required | Required only when TOTP is active | Used for destructive administrator actions. |+| `AuthTwoFaVerificationWithoutPasswordGuard` | Not required | Required only when TOTP is active | Used when the request already proved the password or only needs TOTP. |+| `AuthTwoFaVerificationOrPasswordGuard` | Required only when TOTP is inactive | Required when TOTP is active | Used for app-password generation and revocation. |++The shared headers are:++```text+sync-in-two-fa-password+sync-in-two-fa-code+```++When global TOTP is disabled, or when the loaded user has no TOTP secret, guards that allow password fallback use the current local password instead+of a TOTP code. Guards without password fallback simply allow the request when TOTP is inactive.++Regular users whose current browser session was created through OIDC can skip the app-password step-up guard. Administrators cannot skip it; an OIDC+administrator with TOTP enabled must still pass TOTP verification for app-password step-up.++## API tokens and client registration++Bearer tokens are requested with:++```text+POST /api/auth/token+```++The password provider validates credentials first. If global TOTP is enabled and the user has a TOTP secret, the request must include:++```text+sync-in-two-fa-code: 123456+```++The token route does not require `sync-in-two-fa-password` because the password was already validated by the local authentication guard.++Desktop and CLI client registration also uses the configured password provider first. When TOTP is active for the user, the registration request must+include a `code` value. Sync-in first validates it as a TOTP code, then as a recovery code if TOTP validation fails.++WebDAV cannot complete an interactive TOTP challenge. When global TOTP is enabled and the user has a TOTP secret, WebDAV accepts only a valid+WebDAV-scoped app password, not the primary account password.++## Password attempts and account access++TOTP verification always reloads the user and applies the normal account-access checks. A missing user, inactive account, or account over the+password-attempt limit is rejected before code validation.++After a successful password step for a TOTP-enabled login, password attempts are preserved until the TOTP step succeeds. A successful TOTP step resets+attempts; a failed password or failed code increments attempts through the shared access tracking path.++Enable and disable requests verify the current local password before validating the code. A wrong password updates access tracking as a failed 2FA+operation and returns `Incorrect code or password`.++## Secret storage++If `auth.encryptionKey` is configured, Sync-in encrypts:++- pending setup secrets before storing them in cache;+- persisted `twoFaSecret` values;+- persisted recovery codes.++If `auth.encryptionKey` is not configured, these values are stored as plain secrets in the configured cache or database user secrets.++Changing or removing `auth.encryptionKey` after users enable TOTP makes existing TOTP secrets and recovery codes unreadable.++## Configuration reference++### TOTP settings++| Setting | Default | Description |+|-------------------------|-----------|----------------------------------------------------------------------------------|+| `auth.mfa.totp.enabled` | `true` | Enables local Sync-in TOTP enforcement for users with `twoFaSecret`. |+| `auth.mfa.totp.issuer` | `Sync-in` | Issuer label embedded in the TOTP setup URL and displayed by authenticator apps. |++### Related settings++| Setting | Default | Description |+|----------------------------|-----------------------------------|---------------------------------------------------------------------|+| `auth.encryptionKey` | Unset | Encrypts user secrets, including TOTP secrets and recovery codes. |+| `auth.token.access.secret` | Required | Also used as the signing secret for temporary `access_2fa` tokens. |+| `auth.token.csrf.secret` | Derived from refresh token config | Used to sign the CSRF cookie checked during 2FA login verification. |++The temporary `access_2fa` and `csrf_2fa` token configurations are derived at startup. They reuse the normal access and CSRF cookie names and use a+fixed five-minute expiration.++## Current boundaries++- Only TOTP is implemented; WebAuthn, passkeys, SMS, email OTP, and push approval are not implemented.+- TOTP settings are global; there is no per-provider or per-group TOTP policy.+- Recovery codes are generated only when TOTP is enabled and are returned only once.+- Step-up header verification validates `sync-in-two-fa-code` as a TOTP code only, not as a recovery code.+- OIDC browser login does not receive an additional Sync-in TOTP challenge after the OIDC callback; MFA for that path is expected to be enforced by+ the identity provider.+- Enable and disable flows require the current local Sync-in password, even when the current browser session was created by OIDC.+- TOTP secrets and recovery codes depend on `auth.encryptionKey` when encryption is enabled; changing that key requires a reset of existing user TOTP+ state.