Multi-Factor Authentication

Multi-factor authentication (MFA) adds a second authentication factor to the login process. A user who has completed the primary login is sent a one-time code and must enter it before their session becomes usable.

MFA is enabled per user. The code can be delivered by email or by SMS.

Enabling MFA for a user

Two fields control MFA on a user:

Login Using MFA: whether MFA is enabled for this user.
MFA Expiration Period (in minutes): how long the one-time code remains valid. If it is left empty, the default is 15 minutes.

Both fields appear on the form when you add or edit a user, and both take their initial value from the user's template. In the template, the fields are found under General Fields for caregivers and organization users, and under Sign Up/In Fields for patients.

Setting a default on a template applies to users created from that point on; it does not change users who already exist.

How the code is delivered

The delivery channel, email or SMS, is configured once for the whole environment. To set the channel for your environment, contact BioT Support.

🚧
SMS requires registration with an SMS provider
To deliver MFA codes by SMS, SMS services must first be enabled for your environment. Registering a phone number with the SMS provider is a regulatory process that can take several weeks, so start early. See Sending and Receiving SMS Messages.

A user needs an email address to receive codes by email, or a phone number to receive them by SMS. A user who receives codes by SMS can't have their phone number removed while MFA is enabled for them.

🚧
Changing the channel does not move existing users
Each user keeps the channel that was in effect when MFA was turned on for them. This applies in both directions: if the channel changes from SMS to email, existing users continue to receive codes by SMS, and if it changes from email to SMS, existing users continue to receive them by email. To move a user to the current channel, turn MFA off for them and turn it on again. A user moving to SMS must have a phone number first.

Entering the code

After signing in, the user is asked to enter the code. The code is valid for the user's MFA Expiration Period. A code is invalidated after a number of failed attempts (five by default), after which the user must request a new one. This limit can be changed or disabled, see Password Policy.

MFA in your own application

If you have built your own login screen rather than using a BioT portal, the response of the login API (POST /ums/v2/users/login, see Login APIs) tells you when MFA is required:

"mfaRequired": true,
"mfaExpiration": "2024-12-03T12:48:30.979Z"

When mfaRequired is true, the session is not yet usable. Collect the code from the user and submit it using the MFA login API.

Your application does not choose the delivery channel and does not need to handle email and SMS differently.

Through the API, the two MFA fields on a user are _mfa.enabled and _mfa.expirationInMinutes.

MFA and OTP login

MFA is not the same as OTP login. OTP login replaces the password with a one-time code sent by SMS. MFA is a second factor for users who sign in with a password, and it cannot be enabled for users with OTP credentials.