MFA and TOTP Enrolment¶

Section: Security | Article 23
Audience: System Administrators, End Users
Last Updated: 2026-04-07

Overview¶

RP-PAM supports Time-based One-Time Password (TOTP) multi-factor authentication. When MFA is enabled, users must provide both their password and a 6-digit code from an authenticator app to log in.

Supported Authenticator Apps¶

Any TOTP-compatible authenticator app works with RP-PAM:

App	Platform
Microsoft Authenticator	iOS, Android
Google Authenticator	iOS, Android
Authy	iOS, Android, Desktop
1Password	iOS, Android, Desktop, Browser
Bitwarden	iOS, Android, Desktop, Browser
KeePassXC	Desktop

Prerequisites¶

Requirement	Detail
RP-PAM running	At least one node with the web portal accessible
Admin account	A `pam_admin` role account to configure MFA policy
Authenticator app	Installed on your phone or desktop
Clock sync	TOTP requires accurate clocks; ensure NTP is configured on the RP-PAM server

Step 1: Enable the MFA Policy¶

MFA enforcement is controlled by a policy. By default, MFA is disabled after initial installation.

Using the Web Portal¶

Log in to the RP-PAM web portal as a pam_admin.
Navigate to Settings > Security Policies.
Find the Multi-Factor Authentication section.
Set MFA Requirement to one of:

Setting	Effect
Disabled	No MFA required for any user
Optional	Users can enrol in MFA voluntarily
Required for Admins	All users with `pam_admin` or `pam_approver` roles must use MFA
Required for All	Every user must enrol in MFA at next login

Click Save.

Using the API¶

Linux:

curl -s -X PUT http://localhost:7101/api/v1/settings/security/mfa \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "mfaRequirement": "required_for_all",
    "totpIssuer": "RP-PAM",
    "totpDigits": 6,
    "totpPeriodSeconds": 30,
    "backupCodeCount": 10
  }' | jq .

PowerShell:

$body = @{
    mfaRequirement   = "required_for_all"
    totpIssuer       = "RP-PAM"
    totpDigits       = 6
    totpPeriodSeconds = 30
    backupCodeCount  = 10
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:7101/api/v1/settings/security/mfa" `
  -Method Put `
  -Headers @{ Authorization = "Bearer $adminJwt" } `
  -ContentType "application/json" `
  -Body $body

MFA Policy Configuration Fields¶

Field	Description	Default
`mfaRequirement`	`disabled`, `optional`, `required_for_admins`, `required_for_all`	`disabled`
`totpIssuer`	The name shown in the authenticator app (e.g., "RP-PAM" or "Corp PAM")	`RP-PAM`
`totpDigits`	Number of digits in the TOTP code	`6`
`totpPeriodSeconds`	How often the code changes	`30`
`backupCodeCount`	Number of one-time backup codes generated during enrolment	`10`

Step 2: Enrol in MFA (End User Steps)¶

When MFA is required, users are prompted to enrol at their next login. The process can also be initiated manually.

Navigate to the RP-PAM web portal and enter your username and password.
If MFA is required and you have not yet enrolled, the portal displays the MFA Enrolment screen.
A QR code is displayed.
Open your authenticator app and select Add Account or Scan QR Code.
Scan the QR code with your phone's camera.
The authenticator app creates an entry labelled with the issuer name (e.g., "RP-PAM") and your username.
Enter the 6-digit code currently displayed in your authenticator app into the portal.
Click Verify.
If the code is correct, the portal displays your backup codes (see Step 3).
Complete the login.

Manual Enrolment (Before Being Forced)¶

Users with MFA set to "Optional" can enrol proactively:

Log in to the portal normally (password only).
Click your profile icon (top right) > Security Settings.
Under Multi-Factor Authentication, click Enable MFA.
Follow the QR code scanning process described above.

Via API (Initiate Enrolment)¶

Linux:

# Start enrolment — returns a TOTP secret and QR code URL
curl -s -X POST http://localhost:7101/api/v1/users/me/mfa/enrol \
  -H "Authorization: Bearer $USER_JWT" | jq .

PowerShell:

$enrol = Invoke-RestMethod -Uri "http://localhost:7101/api/v1/users/me/mfa/enrol" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $userJwt" }
$enrol | ConvertTo-Json
# Returns: totpSecret, qrCodeDataUrl, backupCodes

Response:

{
  "totpSecret": "JBSWY3DPEHPK3PXP",
  "qrCodeDataUrl": "data:image/png;base64,...",
  "status": "pending_verification"
}

If users cannot scan a QR code, they can manually enter the totpSecret into their authenticator app.

Verify Enrolment¶

After scanning the QR code, submit a verification code to activate MFA:

Linux:

curl -s -X POST http://localhost:7101/api/v1/users/me/mfa/verify \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }' | jq .

PowerShell:

Invoke-RestMethod -Uri "http://localhost:7101/api/v1/users/me/mfa/verify" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $userJwt" } `
  -ContentType "application/json" `
  -Body '{ "code": "123456" }'

Step 3: Backup Codes¶

When MFA enrolment is completed, RP-PAM generates a set of one-time backup codes. These are emergency codes that can be used if the user loses access to their authenticator app.

Important Rules¶

Each backup code can be used exactly once.
Once used, the code is invalidated.
The default is 10 backup codes; this is configurable via backupCodeCount.
Backup codes are displayed only once during enrolment. They are not retrievable later.

Example Backup Codes¶

BACKUP CODES — Save these in a secure location

  1. A7K2-M9P3-X4B1
  2. C3N8-R2F5-H6J4
  3. D5Q1-L7T9-W2K8
  4. F9B4-P6C3-Y1M7
  5. G2H8-S5A1-V3D6
  6. J4L7-T9W2-B8F5
  7. K6N3-X1C8-M4R2
  8. L8P5-A3G7-Q9S1
  9. N1R4-D6H2-J5T8
  10. Q3S9-F7K4-C2B6

Each code can be used once. Store these securely.
Do NOT store them on the same device as your authenticator app.

Security recommendation: Print these codes and store them in a locked drawer or safe. Do not store them digitally on the same device as your authenticator app.

Step 4: Logging In With MFA¶

After enrolment, every login requires the TOTP code:

Enter username and password.
Click Sign In.
The portal prompts for a 6-digit verification code.
Open your authenticator app, find the RP-PAM entry, and enter the current code.
Click Verify.
If the code is correct, you are logged in.

Using a Backup Code¶

If you cannot access your authenticator app:

On the MFA verification screen, click Use a backup code.
Enter one of your unused backup codes.
Click Verify.
The backup code is consumed and cannot be used again.

What Happens If a User Is Locked Out¶

If a user has lost their authenticator app and all backup codes, they cannot log in. An administrator must reset their MFA.

Administrator MFA Reset¶

Using the Web Portal: 1. Log in as a pam_admin. 2. Navigate to Users and find the locked-out user. 3. Click the user's name to open their profile. 4. Under Security, click Reset MFA. 5. Confirm the reset. 6. The user's MFA enrolment is removed. At their next login, they will be prompted to re-enrol.

Using the API:

Linux:

curl -s -X POST http://localhost:7101/api/v1/users/{userId}/mfa/reset \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

PowerShell:

Invoke-RestMethod -Uri "http://localhost:7101/api/v1/users/$userId/mfa/reset" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $adminJwt" }

Using the CLI:

Linux:

sudo /opt/rppam/tools/rppam-migrate reset-mfa --username "jsmith"

PowerShell:

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-migrate.exe" reset-mfa --username "jsmith"

Audit note: MFA resets are logged as high-priority audit events. The reset includes the admin who performed it, the timestamp, and the affected user.

Regenerate Backup Codes¶

Users who have used most of their backup codes can generate a new set:

Log in to the portal.
Go to profile icon > Security Settings.
Under MFA, click Regenerate Backup Codes.
Enter your current TOTP code to confirm.
A new set of backup codes is displayed. The old codes are immediately invalidated.

Troubleshooting¶

Problem	Cause	Solution
TOTP code is always rejected	Clock drift between server and authenticator device	Ensure NTP is running on the RP-PAM server (`timedatectl status` on Linux, `w32tm /query /status` on Windows); ensure the phone's time is set to automatic
QR code does not scan	Screen resolution or camera issue	Use the manual entry method — enter the `totpSecret` string directly into the authenticator app
"MFA is required" but user was not prompted	Browser cached the old login flow	Clear browser cache and cookies, then try again
Backup codes exhausted	All codes used	Log in with TOTP and regenerate backup codes from Security Settings
Admin cannot reset user MFA	Admin lacks `pam_admin` role	Only `pam_admin` users can reset others' MFA
MFA enrolment stuck in "pending"	User started enrolment but did not verify	The user should re-initiate enrolment; the pending enrolment expires after 10 minutes

Next Steps¶

Web Portal Access and Navigation -- Learn the portal interface
Break-Glass Emergency Access -- Emergency access when MFA is unavailable
Configuration Reference -- Full list of MFA configuration options

MFA and TOTP Enrolment¶

Overview¶

Supported Authenticator Apps¶

Prerequisites¶

Step 1: Enable the MFA Policy¶

Using the Web Portal¶

Using the API¶

MFA Policy Configuration Fields¶

Step 2: Enrol in MFA (End User Steps)¶

During Login (Automatic Prompt)¶

Manual Enrolment (Before Being Forced)¶

Via API (Initiate Enrolment)¶

Verify Enrolment¶

Step 3: Backup Codes¶

Important Rules¶

Example Backup Codes¶

Step 4: Logging In With MFA¶

Using a Backup Code¶

What Happens If a User Is Locked Out¶

Administrator MFA Reset¶

Regenerate Backup Codes¶

Troubleshooting¶

Next Steps¶