Multi-Factor Authentication (MFA) | Medplum

Multi-Factor Authentication (MFA)

MFA adds an extra layer of security to user accounts by requiring a second authentication factor beyond a password. Medplum supports two MFA methods:

Authenticator app (TOTP) — a Time-based One-Time Password compatible with authenticator apps like Google Authenticator, Microsoft Authenticator, Authy, and others.
Email — a single-use 6-digit code emailed to the user's address each time it is needed.

By default, only the authenticator app (TOTP) method is offered. Email-based MFA must be enabled per Project via the allowedMfaMethods setting. Users may enroll in more than one method and choose which to use at login.

Configuring allowed MFA methods

The MFA methods that users in a Project can enroll in are controlled by the allowedMfaMethods setting on the Project resource. It is stored as a single Project.setting entry whose valueString is a comma-delimited list of method codes:

Value	Methods offered
(unset)	Authenticator app (TOTP) only — the historical default
`totp`	Authenticator app (TOTP) only
`email`	Email codes only
`totp,email`	Both — users choose which to enroll in and which to use at login

When the setting is missing, empty, or contains no recognized value, Medplum falls back to totp only.

Enabling email-based MFA

To allow users in a Project to use email-based MFA, set the allowedMfaMethods setting to include email. Project settings can be edited by a Project Admin, or in the Medplum App by a Super Admin on the Project edit page.

const project = await medplum.readResource('Project', projectId);
await medplum.updateResource({
  ...project,
  setting: [
    ...(project.setting ?? []).filter((s) => s.name !== 'allowedMfaMethods'),
    { name: 'allowedMfaMethods', valueString: 'totp,email' },
  ],
});

Branding MFA emails and authenticator apps

By default, MFA content names Medplum. A Project can white-label it with an appName Project.setting entry.

Self-Enrollment

Users can self-enroll in MFA through the Medplum App security settings. The methods offered depend on the Project's allowedMfaMethods setting.

Steps to Self-Enroll

Navigate to the Security page at https://app.medplum.com/security
You will see the "Multi Factor Auth" section showing your current enrollment status
Choose a method to enroll in:
- Authenticator app (TOTP)
- Email
  - Click "Add email-based MFA" — a 6-digit code is emailed to your account's address
  - Enter the code to verify control of your email and complete enrollment

Once enrolled, you will be required to provide an MFA code during login. When both methods are allowed, a user can enroll in both.

Requiring MFA

To require MFA for every user who signs in to a Project with a username and password, add an mfaRequired entry to Project.setting with valueBoolean: true.

Admin MFA Reset

Project admins can reset MFA for members who have lost access to a factor via the POST /admin/projects/:projectId/members/:membershipId/mfa/reset endpoint. The request body accepts an optional method field:

`method`	Effect
(omitted)	Resets `totp` — the backwards-compatible default
`totp`	Resets the authenticator app factor and rotates the TOTP secret
`email`	Resets the email factor; the TOTP secret is left untouched

Admin Password Reset

Project admins can send a member a password reset email via the POST /admin/projects/:projectId/members/:membershipId/resetpassword endpoint.

How email-based MFA works

Unlike the authenticator app method, which derives codes from a shared secret, email-based MFA issues a fresh single-use code each time one is needed.

Using Medplum's SignInForm Component

We recommend using Medplum's SignInForm React component for handling authentication flows that include MFA.