You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 30e7d78
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: documentation/docs/tutorial/09-Plugins/02-TwoFactorsAuth.md
+104-1Lines changed: 104 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -393,7 +393,7 @@ A failed `verify` returns `{ error, code }`, and a failed `verifyAuto` returns `
393
393
|------|---------|
394
394
| `TWO_FACTOR_REQUIRED` | No verification result was passed, and the user is not excluded from 2FA or in the grace period. |
395
395
| `TWO_FACTOR_INVALID` | The TOTP code is wrong or expired, the code confirmation returned by the popup expired, or the passkey is invalid. |
396
-
| `TWO_FACTOR_RATE_LIMITED` | The user entered TOTP codes too often. Every TOTP check, at login and for step-up verification, counts as an attempt, and a user gets 30 attempts per minute, 300 per hour and 1000 per day. |
396
+
| `TWO_FACTOR_RATE_LIMITED` | The user entered TOTP codes too often. Every TOTP check, at login and for step-up verification, counts as an attempt, and by default a user gets 30 attempts per minute, 300 per hour and 1000 per day. See [TOTP code rate limit](#totp-code-rate-limit). |
397
397
| `TWO_FACTOR_NOT_SET_UP` | The user has not set up 2FA yet. |
398
398
| `USER_NOT_FOUND` | The user no longer exists. |
399
399
| `UNSUPPORTED_CONFIRMATION_MODE` | The verification result has an unknown `mode`. |
@@ -713,6 +713,109 @@ If your users don't have enough time to scan the QR code and enter the code (or
713
713
714
714
This value controls both the lifetime of the temporary login JWT and the expiry of the temporary cookie, so they stay in sync.
715
715
716
+
## TOTP code rate limit
717
+
718
+
The plugin limits how often each user can enter TOTP codes, to stop brute force of the code. The limit is counted by user, not by IP, so attempts from all IPs add up. Every TOTP check counts as an attempt: at login and for step-up verification. When the limit is reached, the check fails with the `TWO_FACTOR_RATE_LIMITED` code.
719
+
720
+
By default a user gets 30 attempts per minute, 300 per hour and 1000 per day. You can change it with the `totpRateLimit` option:
721
+
722
+
```tstitle='./adminuser.ts'
723
+
newTwoFactorsAuthPlugin ({
724
+
twoFaSecretFieldName: 'secret2fa',
725
+
...
726
+
//diff-add
727
+
totpRateLimit: ['10/1m', '100/1h', '300/1d'], // Default is ['30/1m', '300/1h', '1000/1d']
728
+
...
729
+
}),
730
+
```
731
+
732
+
Each limit has the format `attempts/period`, where period is `s`, `m`, `h` or `d`. An attempt is allowed only while all limits are not reached.
733
+
734
+
The limit by user works together with the login [rate limit by IP](/docs/tutorial/Customization/security#login-rate-limits) from `auth.rateLimit`, which also applies to entering the TOTP code at login.
735
+
736
+
## Hooks on TOTP check
737
+
738
+
The plugin calls `onOtpFailed` after a user entered a wrong TOTP code and `onOtpSucceeded` after a correct one. Both are called at login and for step-up verification, and receive:
739
+
740
+
- `pk`: primary key of the user who entered the code
741
+
- `dbUser`: record of the user from the users resource
742
+
- `adminforth`: AdminForth instance
743
+
- `extra`: HTTP information of the request, e.g. to get the client IP with `adminforth.auth.getClientIp(extra.headers)`. Not passed when `verify` is called without `extra`.
744
+
745
+
`onOtpFailed` is not called for attempts rejected by the [rate limit](#totp-code-rate-limit), because the code is not checked then, and for a code which was already used. The code entered while setting up 2FA does not call the hooks either.
746
+
747
+
The plugin does not block users by itself, so you can do it in your app. For example, to block a user after 10 wrong codes in a row, counted from all IPs, add columns for the counter and the block flag to the users table:
And deny blocked users in `auth.adminUserAuthorize`, which runs on every request with a fresh user record:
796
+
797
+
```tstitle='./index.ts'
798
+
auth: {
799
+
...
800
+
//diff-add
801
+
adminUserAuthorize: async ({ adminUser }) => {
802
+
//diff-add
803
+
if (adminUser.dbUser.is_blocked) {
804
+
//diff-add
805
+
return { allowed: false, error: 'Your account is blocked, contact an administrator' };
806
+
//diff-add
807
+
}
808
+
//diff-add
809
+
return { allowed: true };
810
+
//diff-add
811
+
},
812
+
},
813
+
```
814
+
815
+
Check the block in `adminUserAuthorize` and not only in `beforeLoginConfirmation`: a user who passed the password step before the block can still enter a correct code on the 2FA page and get a session. `adminUserAuthorize` also denies requests of sessions which were open before the block.
816
+
817
+
To unblock the user, another admin sets `is_blocked` to `false` and `failed_otp_attempts` to `0`, e.g. with a custom action on the users resource.
818
+
716
819
## Passkeys setup (WebAuthn) alongside TOTP
717
820
718
821
If you want to use both passkeys and TOTP simultaneously, you can set them up as follows:
0 commit comments