2FA with 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).
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
- Add the
MFAValidatorclass, if not present, and set it to
NoteAt 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
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
NoteIf 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=falseto continue to allow your platform to manage sessions.
User management with 2FA
user database table includes some fields to support 2FA:
|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
false. The user is then required to re-enroll on their next login.
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.