Skip to content
RAMP Documentation

Multi-Factor Authentication (MFA)

Multi-Factor Authentication (MFA) adds an extra layer of security by requiring a time-based one-time password (TOTP) in addition to your username and password.

Features

Section titled “Features”
  • TOTP-based authentication (RFC 6238)
  • Compatible with Google Authenticator, Microsoft Authenticator, Authy
  • 10 single-use backup codes
  • Admin-configurable policies (None/Optional/Required)
  • QR code setup for easy enrollment

Availability

Section titled “Availability”

For Users: Enabling MFA

Section titled “For Users: Enabling MFA”
  1. Section titled “Navigate to MFA Setup”
    1. Log in to RAMP
    2. Click your profile icon (top right)
    3. Select Settings -> Security
    4. Click Enable Multi-Factor Authentication

  2. Scan QR Code

    Section titled “Scan QR Code”

    Open your authenticator app:

    • Google Authenticator (iOS/Android)
    • Microsoft Authenticator (iOS/Android)
    • Authy (iOS/Android/Desktop)

    Scan the QR code displayed on screen. Your app will generate a 6-digit code.

  3. Verify Setup

    Section titled “Verify Setup”

    Enter the 6-digit code from your authenticator app and click Verify and Enable MFA. If successful, you’ll see 10 backup codes.

  4. Save Backup Codes

    Section titled “Save Backup Codes”

    Critical: Save your backup codes in a secure location!

    • Print and store in a safe place
    • Save to a password manager
    • Store in an encrypted file

    Backup codes are single-use — each code can only be used once.

  5. Test MFA Login

    Section titled “Test MFA Login”
    1. Log out of RAMP
    2. Log in with your username and password
    3. Enter the 6-digit code from your authenticator app
    4. Click Verify

For Users: Using MFA

Section titled “For Users: Using MFA”

Normal Login Flow

Section titled “Normal Login Flow”
  1. Enter username and password
  2. Click Sign In
  3. Enter 6-digit code from authenticator app
  4. Click Verify

Using Backup Codes

Section titled “Using Backup Codes”

If you don’t have access to your authenticator app:

  1. Enter username and password
  2. Click Use Backup Code instead of entering TOTP
  3. Enter one of your backup codes
  4. Code is consumed and won’t work again

For Users: Disabling MFA

Section titled “For Users: Disabling MFA”
  1. Navigate to Settings -> Security
  2. Click Disable Multi-Factor Authentication
  3. Enter current 6-digit MFA code to confirm
  4. Click Disable

For Administrators: MFA Policies

Section titled “For Administrators: MFA Policies”

Administrators can configure MFA policies for the entire system or individual users.

MFA Policy Levels

Section titled “MFA Policy Levels”
PolicyDescriptionUser Experience
NoneMFA disabledUsers cannot enable MFA
OptionalUsers can chooseMFA enrollment available in Settings
RequiredAll users must use MFAForced enrollment on next login

Set User-Specific MFA Policy

Section titled “Set User-Specific MFA Policy”
  1. Navigate to Admin -> Users
  2. Click on a user
  3. Click MFA Policy
  4. Select policy:
    • None — User cannot use MFA
    • Optional — User can enable if desired (default)
    • Required — User must configure MFA
  5. Click Save

Force MFA Enrollment

Section titled “Force MFA Enrollment”

When a user’s policy is set to Required:

  1. User logs in with username/password
  2. User is redirected to MFA setup page
  3. User must complete MFA setup before accessing RAMP
  4. User cannot skip or dismiss the setup

For Administrators: Managing User MFA

Section titled “For Administrators: Managing User MFA”

Reset User MFA

Section titled “Reset User MFA”

If a user loses access to their authenticator app:

  1. Navigate to Admin -> Users
  2. Click on the user
  3. Click Reset MFA
  4. Confirm the action
  5. User’s MFA is disabled and they can re-enroll

Regenerate Backup Codes

Section titled “Regenerate Backup Codes”

If a user uses all backup codes:

  1. Navigate to Admin -> Users
  2. Click on the user
  3. Click Regenerate Backup Codes
  4. 10 new backup codes are generated
  5. Provide codes to user securely (email, in-person)

API Endpoints (For Developers)

Section titled “API Endpoints (For Developers)”

User MFA Endpoints

Section titled “User MFA Endpoints”
EndpointMethodDescription
/_api/auth/mfa/setupPOSTGenerate MFA secret and QR code
/_api/auth/mfa/setup/verifyPOSTVerify and enable MFA
/_api/auth/mfa/disableDELETEDisable MFA (requires OTP)
/_api/auth/mfa/verifyPOSTVerify MFA code during login

Admin MFA Endpoints

Section titled “Admin MFA Endpoints”
EndpointMethodDescription
/_api/users/{id}/mfa-policyPOSTSet user MFA policy
/_api/users/{id}/mfaDELETEReset user MFA
/_api/users/{id}/mfa/backup-codes/regeneratePOSTRegenerate backup codes

Troubleshooting

Section titled “Troubleshooting”

MFA codes not working

Section titled “MFA codes not working”

Check 1: Verify time sync

  • Authenticator apps rely on accurate device time
  • Ensure your device time is set to automatic
  • Small time differences can cause code mismatches

Check 2: Wait for next code

  • Codes refresh every 30 seconds
  • If you’re near the end of a 30-second window, wait for the next code

Check 3: Use backup code

  • If you have backup codes, use one to log in
  • Then re-enroll MFA with a new QR code

Lost access to authenticator app

Section titled “Lost access to authenticator app”

Option 1: Use backup code

  • Each backup code can be used once
  • After login, you can disable and re-enroll MFA

Option 2: Contact administrator

  • Admin can reset your MFA
  • You’ll need to re-enroll with a new QR code

QR code won’t scan

Section titled “QR code won’t scan”

Try manual entry:

  1. Click “Manual Entry” on MFA setup page
  2. Copy the secret key
  3. In authenticator app, choose “Manual Entry”
  4. Enter:
    • Account name: RAMP - your@email.com
    • Secret key: (paste from RAMP)
    • Type: Time-based
  5. Save in authenticator app

Backup codes not working

Section titled “Backup codes not working”

Check 1: Verify code is unused — each backup code works only once

Check 2: Check for typos — backup codes are case-sensitive, ensure no extra spaces

Check 3: Contact administrator — admin can regenerate new backup codes (old codes will be invalidated)

Security Best Practices

Section titled “Security Best Practices”

For Users

Section titled “For Users”
  1. Secure backup codes — Store in password manager, keep encrypted copy, don’t share via insecure channels
  2. Use trusted authenticator apps — Google Authenticator, Microsoft Authenticator, Authy (with cloud backup)
  3. Enable device lock — Protect your phone/tablet with PIN/biometric
  4. Don’t share MFA codes — NEVER share 6-digit codes with anyone; admins will NEVER ask for MFA codes

For Administrators

Section titled “For Administrators”
  1. Require MFA for admins — Set policy to “Required” for Administrator roles to reduce risk of account compromise
  2. Monitor MFA enrollment — Track which users have MFA enabled and encourage adoption
  3. Audit MFA resets — Review audit logs for MFA reset actions and verify legitimacy of reset requests
  4. Educate users — Provide MFA enrollment training and share this guide with users

Advanced Topics

Section titled “Advanced Topics”

MFA Implementation Details

Section titled “MFA Implementation Details”

RAMP uses:

  • TOTP Algorithm: RFC 6238 (Time-Based One-Time Password)
  • Hash Function: HMAC-SHA1
  • Code Length: 6 digits
  • Time Step: 30 seconds
  • Secret Length: 160 bits (32 base32 characters)
  • Backup Codes: 10 codes, 8 characters each, SHA256 hashed

Backup Code Security

Section titled “Backup Code Security”
  • Generated using cryptographically secure random number generator
  • Stored as SHA256 hashes (not reversible)
  • Single-use enforcement via database flag
  • Regeneration invalidates all previous codes

Secret Storage

Section titled “Secret Storage”
  • MFA secrets encrypted using ASP.NET Core Data Protection API
  • Encrypted at rest in database
  • Decrypted only during verification

Clock Skew Tolerance

Section titled “Clock Skew Tolerance”

RAMP accepts codes from:

  • Current time window (30 seconds)
  • Previous time window (30 seconds)
  • Next time window (30 seconds)

Total tolerance: plus or minus 30 seconds

Integration with Identity Providers

Section titled “Integration with Identity Providers”
ProviderMFA Support
RAMP NativeBuilt-in TOTP MFA
OIDCUse IdP’s MFA (Entra ID Conditional Access, etc.)
LDAPUse RAMP MFA or configure LDAP server MFA
Windows AuthUse AD policies or smart card auth
ADFSUse ADFS MFA providers (Azure MFA, Duo, etc.)

Frequently Asked Questions

Section titled “Frequently Asked Questions”

Can I use multiple devices?

Section titled “Can I use multiple devices?”

Yes! Scan the QR code with multiple authenticator apps during initial setup.

What if I get a new phone?

Section titled “What if I get a new phone?”
  1. Use backup code to log in
  2. Disable MFA
  3. Re-enroll with new device

Or, if using Authy with cloud backup:

  1. Install Authy on new phone
  2. Restore from cloud
  3. Codes automatically available

Can admins see my MFA codes?

Section titled “Can admins see my MFA codes?”

No. MFA secrets are encrypted and administrators cannot view your TOTP codes or backup codes (they’re hashed).

Does MFA work offline?

Section titled “Does MFA work offline?”

Yes. TOTP codes are generated locally on your device using time-based algorithm. No internet required.

Can I use hardware tokens (YubiKey)?

Section titled “Can I use hardware tokens (YubiKey)?”

Not currently. RAMP supports TOTP-based MFA only. Hardware token support is planned for future release.

Next Steps

Section titled “Next Steps”
Section titled “Related topics”
RAMP Native Authentication Configure username/password login with MFA, password reset, and lockout protection
Authentication Overview Compare all authentication methods and choose the right one