Skip to content

Commit 30e7d78

Browse files
committed
docs: update docs for the 2fa
1 parent 4a2a1b5 commit 30e7d78

1 file changed

Lines changed: 104 additions & 1 deletion

File tree

‎documentation/docs/tutorial/09-Plugins/02-TwoFactorsAuth.md‎

Lines changed: 104 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -393,7 +393,7 @@ A failed `verify` returns `{ error, code }`, and a failed `verifyAuto` returns `
393393
|------|---------|
394394
| `TWO_FACTOR_REQUIRED` | No verification result was passed, and the user is not excluded from 2FA or in the grace period. |
395395
| `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). |
397397
| `TWO_FACTOR_NOT_SET_UP` | The user has not set up 2FA yet. |
398398
| `USER_NOT_FOUND` | The user no longer exists. |
399399
| `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
713713
714714
This value controls both the lifetime of the temporary login JWT and the expiry of the temporary cookie, so they stay in sync.
715715
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+
```ts title='./adminuser.ts'
723+
new TwoFactorsAuthPlugin ({
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:
748+
749+
```prisma title='./schema.prisma'
750+
model adminuser {
751+
...
752+
//diff-add
753+
failed_otp_attempts Int @default(0)
754+
//diff-add
755+
is_blocked Boolean @default(false)
756+
}
757+
```
758+
759+
Count failures in the hooks:
760+
761+
```ts title='./adminuser.ts'
762+
const MAX_FAILED_OTP_ATTEMPTS = 10;
763+
764+
...
765+
new TwoFactorsAuthPlugin ({
766+
twoFaSecretFieldName: 'secret2fa',
767+
...
768+
//diff-add
769+
onOtpFailed: async ({ pk, dbUser, adminforth }) => {
770+
//diff-add
771+
const failedAttempts = dbUser.failed_otp_attempts + 1;
772+
//diff-add
773+
await adminforth.resource('adminuser').update(pk, {
774+
//diff-add
775+
failed_otp_attempts: failedAttempts,
776+
//diff-add
777+
is_blocked: failedAttempts >= MAX_FAILED_OTP_ATTEMPTS,
778+
//diff-add
779+
});
780+
//diff-add
781+
},
782+
//diff-add
783+
onOtpSucceeded: async ({ pk, dbUser, adminforth }) => {
784+
//diff-add
785+
if (dbUser.failed_otp_attempts > 0) {
786+
//diff-add
787+
await adminforth.resource('adminuser').update(pk, { failed_otp_attempts: 0 });
788+
//diff-add
789+
}
790+
//diff-add
791+
},
792+
}),
793+
```
794+
795+
And deny blocked users in `auth.adminUserAuthorize`, which runs on every request with a fresh user record:
796+
797+
```ts title='./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+
716819
## Passkeys setup (WebAuthn) alongside TOTP
717820
718821
If you want to use both passkeys and TOTP simultaneously, you can set them up as follows:

0 commit comments

Comments
 (0)