Aidbox supports Two Factor Authentication with TOTP (time-based one-time passwords). This article explains how to enable 2FA for a user, login with one-time password, and get an access token for your application. Familiarity with OAuth 2.0 and TOTP is suggested. All examples are executable in Aidbox REST console.
We have to create three resources to implement 2FA: User, Client, and AuthConfig. Client is needed to enable desired OAuth 2.0 flow for your application and AuthConfig stores 2FA settings. Refer to the specific OAuth flow article to understand how to create Client resource suitable for your use case.
PUT AuthConfig/myconfigtwoFactor:issuerName: my-appvalidPastTokensCount: 3webhook:endpoint: https://my-app.comtimeout: 500
PUT /Client/mywebappsecret: verysecretfirst_party: truegrant_types:- codeauth:authorization_code:redirect_uri: 'http://localhost:3001'access_token_expiration: 360token_format: jwtsecret_required: truerefresh_token: true
PUT /User/my-userid: my-userpassword: password
Name of the TOTP token issuer that is shown in authenticator
Number of previous tokens that are considered valid. Used to improve user experience if standard 30 seconds token lifetime is not enough.
Endpoint to send the TOTP token to during login. Used to support scenarios when it's not possible to use the mobile authenticator. For instance, a service integrated with twilio may listen on this address.
Timeout for webhook in milliseconds
Key-value headers for webhook
URL to external stylesheet to customise how the authentication form looks like
Title to use on the authentication form
Application name to display on the authentication page
Redirect the user to the following URL to establish TOTP authentication. The user should already be logged into Aidbox.
When the user scans the QR code and enters the token, they will get redirected to the 2FA settings page. Aidbox saves that 2Fa is enabled for this user into the User.twoFactor attribute.
Next time when the user logins into the system, the TOTP authentication page will be shown. Using the mobile authenticator (or any other transport) the user enters the code and gets redirected to your application. You can configure which OAuth 2.0 flow to use by changing Client configuration and login endpoint query parameters. Refer to the specific OAuth flow article if you need further explanation.
Redirect the user to the following URL to disable 2FA. When the user enters a token, they get redirected to 2FA settings page. Aidbox sets User.twoFactor.enabled to false.