2FA with Twilio Verify

Secure uzERP user logins with multi-factor authentication using Twilio Verify

Available Since release 1.31.0

What is Twilio Verify

Twilio Verify is a service that validates users after they have logged into uzERP with their username and password. Twilio Verify supports verification via SMS, voice, push message, etc. but uzERP only implements time-based one-time passwords (TOTP).

With TOTP, users enroll with Twilio and then use codes obtained from an app on their phone, computer or tablet. Some suitable apps are Authy and Google Authenticator.

Before configuring uzERP you will need to create an account and a Verify service with Twilio.

Configure uzERP for TOTP 2FA with Twilio

Set injector classes

Set the LoginHandler class to HTMLFormLoginHandlerMFA.
Add the MFAValidator class, if not present, and set it to TWValidator.

Note

At the time of writing, editing and creation of system-wide injector classes is not supported in the web UI and should be done in the database, via SQL.

Add Twilio settings to the uzERP configuration file

Add the Twilio secrets to the config/.env file in uzERP:

# Example settings

TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TWILIO_AUTH_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TWILIO_SERVICE_SID="VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Update PHP session management settings (optional)

Twilio will charge your account for each successful validation. uzERP session management can be configured with an appropriate user activity timeout and max age in seconds in the config/.env file.

The above settings should be chosen carefully to balance user convenience, security and cost based on your threat model.

# Example settings

# Let uzERP manage user session timeout and maximum age.
# If included and true, uzERP manages session age.

UZERP_MANAGE_USER_SESSIONS=true

# If UZERP_MANAGE_USER_SESSIONS is true, the following
# variables must be set.

USER_ACTIVITY_TIMEOUT_SECS=28800 #30 Mins = 1800
USER_SESSION_MAX_AGE_SECS=28800 #8 hours

Note

If the platform that you run uzERP on manages PHP session clean-up, like Ubuntu, then you will need to turn off your platform’s PHP session management to allow uzERP to manage sessions or set UZERP_MANAGE_USER_SESSIONS=false to continue to allow your platform to manage sessions.

User management with 2FA

The user database table includes some fields to support 2FA:

Field Name	Description
uuid	Unique user id, used to reference the user with the 2FA service to avoid providing any personal information.
mfa_sid	Identifies the factor to be verified so that the service can select the correct secret to validate the user’s token.
mfa_enrolled	The user has successfully been enrolled for 2FA.
mfa_enabled	Indicates that 2FA is enabled for the account.

Verification can be disabled for the next user login from the Web UI and is automatically re-enabled once the user has been validated.

A user’s 2FA status can also be reset, which removes the mfa_sid and sets mfa_enrolled and mfa_enabled to false. The user is then required to re-enroll on their next login.

User enrollment

Once 2FA is enabled users will be required to enroll with the service using their chosen app.

When an un-enrolled user logs in with their usual username and password uzERP will obtain a new TOTP secret from Twilio and present a QR code and plaintext secret that the user can use to set-up their app. The app will then provide a code that the user must enter into uzERP for verification.

After successful verification the user will be logged in to uzERP. Once enrolled the user will need to enter a code from their app each time they login to uzERP.