HomeGuidesChangelog
Guides

Multi-Factor Authentication (MFA)

Suggest Edits

Multi-Factor Authentication (MFA) in RegScale

This guide explains how Multi-Factor Authentication works in RegScale and provides step-by-step instructions for configuring MFA for end users.

Overview

RegScale implements Time-based One-Time Password (TOTP) authentication, the same standard used by Google, Microsoft, and GitHub. Users authenticate with their password plus a 6-digit code from an authenticator app.

Supported Authenticator Apps

Any TOTP-compatible authenticator app works with RegScale:

  • Google Authenticator (iOS/Android)
  • Microsoft Authenticator (iOS/Android)
  • Authy (iOS/Android/Desktop)
  • 1Password (with TOTP support)
  • FreeOTP (iOS/Android)

How MFA Works

Authentication Flow

┌─────────────────────────────────────────────────────────────┐
│                      LOGIN PROCESS                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Enter Username                                          │
│         ↓                                                   │
│  2. System checks if MFA is required for your tenant        │
│         ↓                                                   │
│  3. Enter Password + 6-digit code from authenticator app    │
│         ↓                                                   │
│  4. System validates both credentials                       │
│         ↓                                                   │
│  5. Access granted                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Technical Details

  • Code Duration: Each 6-digit code is valid for 30 seconds
  • Algorithm: TOTP (RFC 6238) with SHA-1
  • Secret Storage: Encrypted at rest using AES-256
  • Validation: Strict time-window matching

Administrator Configuration

Enabling MFA for a Tenant

Administrators can require MFA for all local users in a tenant:

  1. Navigate to Admin → Tenant Settings
  2. Locate the Security section
  3. Toggle "Require Multi-Factor Authentication (MFA) for All Local User Accounts" to ON
  4. Optionally, set an MFA Prefix (e.g., your company name)
    • This appears in the authenticator app as the issuer name
    • Example: "Acme Corp - [email protected]"
  5. Save changes

Note: When MFA is enabled at the tenant level, all local users must configure MFA before they can log in.

Configuration Options

SettingDescriptionDefault
Force Multi-FactorRequires MFA for all local usersOff
MFA PrefixCustom issuer name in authenticator apps"RegScale"

End User Setup Guide

Prerequisites

Before setting up MFA, ensure you have:

  • Access to your registered email address
  • An authenticator app installed on your mobile device
  • Your RegScale username and password

Step-by-Step Setup

Step 1: Request QR Code

  1. Go to the RegScale login page
  2. Enter your username (do not submit yet)
  3. Click "Generate QR Code for Authenticator App"
  4. You will receive an email with a one-time access token

Step 2: Retrieve Access Token

  1. Check your email for a message from RegScale
  2. Copy the access token from the email
  3. This token is valid for 1 hour

Step 3: Generate QR Code

  1. Return to the RegScale login page
  2. Click the QR Code modal/button
  3. Paste the access token from your email
  4. Click "Generate QR Code"
  5. A QR code will appear on screen

Step 4: Scan with Authenticator App

  1. Open your authenticator app
  2. Tap "Add Account" or the "+" button
  3. Select "Scan QR Code"
  4. Point your camera at the QR code on screen
  5. The account will be added to your app

Your authenticator app will now display:

RegScale - [email protected]
123 456

(The 6-digit code changes every 30 seconds)

Step 5: Verify Setup

  1. Enter your username and password
  2. Enter the current 6-digit code from your authenticator app
  3. Click Login
  4. If successful, MFA is configured!

Logging In with MFA

Once MFA is configured, follow these steps each time you log in:

  1. Enter your username
  2. Enter your password
  3. Open your authenticator app
  4. Enter the current 6-digit code displayed for RegScale
  5. Click Login

Tip: Enter the code quickly - codes expire every 30 seconds. If your code expires, wait for the next one.

Troubleshooting

"Invalid MFA Token" Error

Cause: The 6-digit code doesn't match.

Solutions:

  1. Ensure you're entering the code for the correct RegScale account
  2. Wait for the next code if the current one is about to expire
  3. Verify your device's time is accurate (TOTP depends on synchronized clocks)

Code Always Rejected

Cause: Your device's clock is out of sync.

Solutions:

  1. iOS: Settings → General → Date & Time → Enable "Set Automatically"
  2. Android: Settings → System → Date & Time → Enable "Automatic date & time"

Lost Access to Authenticator App

Solutions:

  1. Contact your RegScale administrator
  2. Administrator can reset your MFA settings
  3. You will need to set up MFA again from scratch

QR Code Won't Scan

Solutions:

  1. Ensure adequate lighting
  2. Hold your phone steady
  3. Try zooming in slightly
  4. Manually enter the setup key if your app supports it

Access Token Expired

Cause: The email token is only valid for 1 hour.

Solution: Request a new QR code by clicking "Generate QR Code" again on the login page.

Security Best Practices

For End Users

  1. Secure your authenticator app with biometric or PIN lock
  2. Back up your authenticator - apps like Authy support cloud backup
  3. Never share your codes - they are single-use and time-sensitive
  4. Keep your device time accurate - automatic time sync is recommended
  5. Don't screenshot QR codes - treat them as passwords

For Administrators

  1. Enable MFA at tenant level for security-sensitive environments
  2. Set a recognizable MFA prefix so users can identify the correct account
  3. Document recovery procedures for users who lose authenticator access
  4. Monitor failed login attempts through security audit logs
  5. Consider MFA for all admin accounts regardless of tenant settings

Frequently Asked Questions

Can I use multiple authenticator apps?

Yes. When you scan the QR code, you can scan it with multiple authenticator apps. Each app will generate the same codes.

Does MFA work with SSO/SAML?

MFA in RegScale applies to local accounts only. If you use SSO (SAML, OAuth, LDAP), MFA is handled by your identity provider.

Can I disable MFA once it's enabled?

Individual users cannot disable MFA through the UI. Contact your administrator if MFA needs to be disabled for your account.

What happens if I get a new phone?

You'll need to set up MFA again:

  1. Contact your administrator to reset your MFA
  2. Follow the setup process on your new device
  3. If using Authy with cloud backup, your accounts transfer automatically

Is SMS or email-based MFA supported?

Currently, RegScale only supports TOTP (authenticator app). SMS and email codes are not available.

Related Documentation

Updated 2 days ago