Two Factor Authentication

Request GET /auth/login. User enters credentials and logs in.

Request GET /auth/two-factor. User receives a form with an "Enable" button. After clicking the button, they receive the OTPAuth URL encoded as a QR code.

Encoded OTPAuth URL (QR) has the following structure:

otpauth://totp/<LABEL>?secret=<SECRET>&issuer=<ISSUER>

• LABEL - consists of two parts <Issuer>:<UserEmailOrId>. Issuer in label is the same as in issuer.
• SECRET - random byte sequence encoded in Base32. Secret is stored in the User resource under the User.twoFactor.secret attribute.
• ISSUER - same as in LABEL. Default value is Aidbox, but can be configured via AuthConfig.twoFactor.issuerName.

User scans this QR code with their authenticator app. After scanning, the app generates a confirmation token that the user enters. If successful, 2FA is enabled for this user and the User resource stores User.twoFactor.enabled = true.

{
 "password": "<password>",
 "twoFactor": {
  "enabled": true,
  "secretKey": "<secret-key>"
 },
 "id": "<user-id>",
 "resourceType": "User"
}

Request GET /auth/login. User enters credentials and logs in.

Request GET /auth/two-factor. User receives a form with a "Disable" button. After clicking the button, they receive a confirmation form.

User enters a TOTP code from their authenticator app to confirm disabling. If successful, 2FA is disabled for this user and the User resource stores User.twoFactor.enabled = false.

{
 "password": "<password>",
 "twoFactor": {
  "enabled": false,
  "secretKey": "<secret-key>"
 },
 "id": "<user-id>",
 "resourceType": "User"
}