AuthRocket supports the TOTP standard for two-factor authentication. Two-factor authentication (2FA) is also called multi-factor authentication (MFA).
TOTP stands for Time-based One-Time Passwords and is a published standard. AuthRocket’s implementation is compatible with the standard and with any app that properly implements the standard.
TOTP is used by Google Authenticator, MS Authenticator, and many other apps. Such apps are readily available on pretty much every platform. Many are free. Your users may use any compatible app with AuthRocket.
To enable 2FA for a given Realm, simple add the TOTP Auth Provider under Realm -> Settings -> Auth Providers -> 2FA: TOTP -> Add.
Once enabled, there’s nothing more to configure.
Each user must be individually enrolled in 2FA. Any user who has not enrolled in 2FA will continue to login normally.
Currently the only way for an individual user to self-enroll in 2FA is through your app. Your app should use the AuthRocket API to add a TOTP Credential (see below).
Additionally, you may administratively enroll a user using the AuthRocket management portal. This is useful for testing or when an account administrator is enrolling another employee (and can physically access their phone or other 2FA device).
To begin the enrollment process, Create a new Credential for the specific User. credential_type should be totp. You will need to provide the auth_provider_id of the TOTP Auth Provider for your Realm. Also provide a name for the device, such as Clyde's iPhone X. If you don’t want to prompt the user for a device name, just send a default value.
The new Credential will have a shared secret that is used to cryptographically generate the 6-digit verification codes. To ensure the user’s 2FA app and device are sync’d correctly, and to prevent the user from being locked out of their account, 2FA will not activate until a verification code is successfully verified the first time.
To provision the user’s app/device, there are two methods. The most common, and easiest for the user, is to show them a QR Code with everything embedded into it. The unactivated Credential returned by AuthRocket will include a provisioning_uri that has everything needed to create this QR Code. You can use any library capable of rendering a QR Code. Pass it the provisioning_uri as the string to render.
The alternative method is to have the user enter the value of otp_secret. This field is case-insensitive (all apps should automatically upper-case it).
Once the user’s app/device is configured, prompt them for a verification code and submit it back to AuthRocket using Verify a Credential. If successful, the 2FA credential will be automatically enabled for future logins.
To see an example of how this works in practice, try enabling 2FA on your own AuthRocket profile.
Enabling 2FA does affect the login flow. For non-2FA users, nothing changes. For 2FA-enabled users, a temporary token is returned instead of the full login token. This token must be resubmitted, along with the 2FA verification code, to complete the login.
2FA is triggered only for password logins. It is not used for social auth, as many social providers already provide their own 2FA.
If you are using hosting logins via LoginRocket, everything is handled automatically for you. Users with 2FA enabled will be automatically prompted for their 2FA verification code and logged in as normal.
With authrocket.js, AuthRocket.authenticate() will return {“result” : “needs_mfa”} along with a temporary token that indicates an incomplete 2FA login. Your authrocket.js login handler will need to catch this response and prompt the user for their 2FA verification code.
Make a second call to AuthRocket.authenticateCode() with the username, temporary token, and the verification code to complete the login. The response to authenticateCode() will be the same as authenticate() for non-2FA logins.
When processing logins directly with the AuthRocket API, the Authenticate using a password API call will return a temporary token (starting with kli_) for 2FA-enabled logins. This must be caught and the user prompted for their 2FA verification code.
Make a second call to Complete an MFA authentication with that temporary token and the verification code. A full login token will be returned on success, same as the standard Authenticate API for non-2FA.
Questions? Find a Typo? Get in touch.