Multi-Factor Authentication (MFA)

Infracast supports TOTP-based multi-factor authentication to secure user accounts. MFA adds a second layer of protection beyond passwords.

Overview

When MFA is enabled, users must provide:

1. Password — Something they know
2. TOTP Code — Something they have (authenticator app)

Supported Authenticator Apps

Any TOTP-compatible authenticator works:

• Google Authenticator
• Microsoft Authenticator
• Authy
• 1Password
• Bitwarden

Setting Up MFA

For Users

1. Log in to Infracast
2. Navigate to Profile (user menu → Profile)
3. Click Enable MFA
4. Scan the QR code with your authenticator app
5. Enter the 6-digit code to verify
6. Save your backup codes — These are single-use recovery codes

Store Backup Codes Securely

Backup codes are only shown once. Store them in a password manager or secure location. If you lose access to your authenticator and backup codes, an admin must reset your MFA.

Via API

# 1. Initialize MFA setup
POST /api/v1/mfa/setup
Authorization: Bearer <token>

# Response:
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code": "data:image/png;base64,...",
  "backup_codes": ["12345678", "87654321", ...]
}

# 2. Verify and enable
POST /api/v1/mfa/verify
Authorization: Bearer <token>
Content-Type: application/json

{"code": "123456"}

Login with MFA

When MFA is enabled, login becomes a two-step process:

Step 1: Submit Credentials

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "...",
  "tenant_id": "demo"
}

# Response when MFA enabled:
{
  "mfa_required": true,
  "user": {...}
}

Step 2: Submit MFA Code

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "...",
  "tenant_id": "demo",
  "mfa_code": "123456"
}

# Success response:
{
  "token": "eyJ...",
  "user": {...}
}

Disabling MFA

Users can disable MFA from their Profile:

1. Go to Profile
2. Click Disable MFA
3. Enter your current TOTP code to confirm
4. MFA is disabled immediately

tip

Only disable MFA if you have another form of account protection, such as SSO with your identity provider's MFA.

Admin: Enforce MFA Organization-Wide

Admins can require MFA for all users in a tenant. When enforcement is active, users without MFA configured are blocked at login and redirected to the MFA enrollment flow.

Enable Enforcement

1. Go to Settings → Security
2. Toggle Require MFA for all users
3. Optionally set a Grace Period (e.g., 7 days) before enforcement kicks in for existing users
4. Click Save

Via API

PATCH /api/v1/tenants/{tenantID}/settings
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "mfa_required": true,
  "mfa_grace_period_days": 7
}

Enforcement Behavior

• New users: blocked immediately at first login until MFA is enrolled
• Existing users (grace period active): shown a warning banner with a countdown
• Existing users (grace period expired): blocked at login, redirected to enrollment
• Admin accounts: enforcement applies equally — no exceptions

MFA Enrollment Dashboard

Admins can track enrollment status under Settings → Security → MFA Status:

• Total users vs. MFA-enrolled users
• List of users without MFA
• One-click option to send enrollment reminder emails

Admin: Reset User MFA

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

1. Go to Settings → Users
2. Find the user
3. Click Reset MFA
4. User's MFA is disabled and they can set up new MFA

Via API

POST /api/v1/tenants/{tenantID}/users/{userID}/reset-mfa
Authorization: Bearer <admin-token>

Backup Codes

Backup codes are generated when MFA is enabled:

• 8-digit single-use codes
• Can be used instead of a TOTP code when logging in
• Each code works only once
• Regenerate by disabling and re-enabling MFA

Security Considerations

Best Practices

• ✅ Enforce MFA organization-wide via Settings → Security
• ✅ Require MFA for all admin accounts (enforced first)
• ✅ Store backup codes in a password manager
• ✅ Use a dedicated authenticator app (not SMS)
• ✅ Monitor enrollment status from the MFA Status dashboard
• ✅ Set a grace period when rolling out enforcement to existing users

MFA Does NOT Protect Against

• Session hijacking (if JWT token is stolen)
• Phishing attacks (if user enters code on fake site)
• Malware on the device running the authenticator

Compliance Mapping

Framework	Control
NIST 800-53	IA-2(1), IA-2(2) (Multi-Factor Authentication)
SOC 2	CC6.1 (Logical Access Controls)
CIS Controls	6.3, 6.4 (MFA Required)
PCI DSS	8.3 (Strong Authentication)
CMMC	IA.L2-3.5.3 (Multi-Factor Authentication)

Troubleshooting

"Invalid MFA code"

• Check your device clock is synced (TOTP is time-based, codes rotate every 30 seconds)
• Ensure you're using the correct account in your authenticator
• Try waiting for the next code cycle

Lost Authenticator Access

1. Try using a backup code to log in
2. Once logged in, disable MFA from Profile
3. Set up MFA again with your new device

No Backup Codes and Locked Out

Contact your tenant administrator to reset your MFA. They can do this from Settings → Users → Reset MFA.