Zoomed Image
USA
800 691 9120
UK
01225 704844

MFA Setup Guide

xAssets Configuration Guide
Security

MFA Setup Guide

This page is a companion to the Multi-factor Authentication reference page. It provides step-by-step instructions for administrators deploying MFA and for end users enrolling their authenticator apps. If you have not yet decided which MFA method to use, read the reference page first.

Prerequisites

  • Administrator access to xAssets (to enable MFA settings)
  • For authenticator app MFA: users must have a smartphone with an authenticator app installed (Microsoft Authenticator, Google Authenticator, Authy, or any TOTP-compatible app)
  • For email MFA: every user must have a valid email address on their Custodian record
  • A working SMTP configuration in xAssets (required for email MFA and for backup code delivery)

Planning Your Rollout

Before enabling MFA, consider the following:

Decision Recommendation
Which method? Authenticator app (TOTP) is more secure and works offline. Email MFA is simpler but depends on email availability at login time.
Risk-based or always? Risk-based (mode 1) is less disruptive for daily users. Always (mode 2) is appropriate for high-security environments or external-facing instances.
Time interval For risk-based mode, the default 720 hours (30 days) is reasonable. Consider 168 hours (7 days) for sensitive environments.
Pilot group Consider enabling MFA for administrators first, then rolling out to all users after confirming the process works smoothly.

Step 1: Enable MFA in Settings

  1. Navigate to Admin > Settings.
  2. Search for the appropriate setting:
    • AUTHENTICATIONMFA for authenticator app (TOTP)
    • AUTHENTICATIONMFAEMAIL for email-based MFA
  3. Set the value to 1 (risk-based) or 2 (always).
  4. Optionally adjust AUTHENTICATIONMFATIME to set the re-authentication interval in hours (default: 720).
  5. Save the settings.

Tip: You can enable both methods simultaneously. When both are active, users who have enrolled an authenticator app will use that method; users who have not enrolled will receive an email code instead.

Step 2: Communicate to Users

Notify your users before their next login. Include the following information:

  • MFA is being enabled and why
  • Which authenticator app to install (if using TOTP)
  • That they will see a QR code on their next login and must scan it to complete enrollment
  • That they should save their backup codes in a secure location
  • Who to contact if they have trouble enrolling

Step 3: User Enrollment (Authenticator App)

When a user logs in for the first time after TOTP MFA is enabled, the following enrollment flow occurs:

  1. The user enters their username and password as normal.
  2. A QR code is displayed on screen along with a manual entry key.
  3. The user opens their authenticator app and scans the QR code (or enters the manual key).
  4. The authenticator app generates a six-digit code that refreshes every 30 seconds.
  5. The user enters the current code from the app into xAssets.
  6. If the code is correct, enrollment is complete and the user is logged in.

Important: The QR code is only shown once, during initial enrollment. If the user does not scan it at this point, they will need an administrator to reset their MFA enrollment (see Resetting a User's MFA below).

Manual Key Entry

If the user cannot scan the QR code (for example, if using the same device for both the browser and the authenticator app), a text-based key is displayed below the QR code. The user can enter this key manually in their authenticator app by choosing the "Enter a setup key" option.

Step 4: User Enrollment (Email MFA)

Email MFA does not require a separate enrollment step:

  1. The user enters their username and password.
  2. xAssets sends a one-time code to the email address on the user's Custodian record.
  3. The user checks their email and enters the code.
  4. If the code is correct, the user is logged in.

Warning: If the user's Custodian record does not have a valid email address, they will be unable to complete login. Verify all email addresses before enabling email MFA.

Backup Codes

When authenticator app MFA is enabled, users should generate backup codes to use if they lose access to their authenticator device. Backup codes are single-use codes that bypass the authenticator step.

To generate backup codes:

  1. Navigate to the MFA settings area within your user profile or account settings to generate backup codes.
  2. Each code can only be used once.
  3. Store backup codes in a secure location (password manager, printed in a locked drawer).

Tip: Advise users to generate backup codes immediately after enrollment, before they need them in an emergency.

Resetting a User's MFA

If a user loses their phone, gets a new device, or cannot complete MFA for any reason, an administrator can reset their enrollment:

  1. Navigate to Admin > Users.
  2. Find and open the affected user's record.
  3. Clear or reset the user's MFA enrolment using the MFA reset option on the user record.
  4. Save the record.
  5. On their next login, the user will see the QR code enrollment screen again and can pair their new device.

Important: After resetting a user's MFA, verify their identity through an out-of-band channel (phone call, in-person) before performing the reset. MFA resets are a common target for social engineering attacks.

What Happens When a User Loses Their Device

If a user loses access to their authenticator app and has no backup codes:

  1. The user contacts their xAssets administrator.
  2. The administrator verifies the user's identity through an independent channel.
  3. The administrator resets the user's MFA enrollment (see above).
  4. The user logs in and re-enrolls with their new or replacement device.
  5. The user generates new backup codes.

If email MFA is also enabled as a fallback, the user may be able to log in using the email code instead, bypassing the lost authenticator temporarily.

Troubleshooting

Problem Cause Solution
Code rejected during enrollment Clock on user's phone is not synchronised Ensure the phone's time is set to automatic (network time). TOTP codes are time-sensitive.
Email code never arrives SMTP not configured, or email address invalid Check SMTP settings and verify the user's Custodian email address. Check spam folders.
User locked out after enabling MFA User has no email address and did not complete TOTP enrollment Administrator must reset the user's MFA enrollment.
QR code not displaying Browser blocking images or JavaScript disabled Try a different browser. Ensure JavaScript is enabled.
Code works once then fails on next login Backup code was used (single-use) instead of authenticator code Use the rotating code from the authenticator app, not a backup code.