feature-react-mfa

Enable Multi-Factor Authentication (MFA) for React-based Experience Cloud sites.

What it does

Deploys two permission sets that enable platform-handled MFA for community users:

| Permission Set | Permission | Purpose | | ---------------------------- | ---------------- | --------------------------------------- | | MFA_Required_For_Community | ForceTwoFactor | Enforces MFA challenge at login | | API_Enabled_For_Community | ApiEnabled | Enables REST API access for React sites |

How MFA works on Experience Sites

The Salesforce platform handles the entire MFA flow:

1. User logs in via the site login page
2. Platform detects ForceTwoFactor permission on the user
3. Platform renders an MFA challenge page (on the vforcesite domain)
4. User completes verification (TOTP, Authenticator, WebAuthn, SMS, or Email)
5. User is redirected to the React app, fully authenticated

No custom React UI is needed. The platform handles the challenge page rendering.

Prerequisites

Before installing this feature, ensure the following are already in place:

| Prerequisite | Why | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | Experience Cloud site deployed and active | MFA applies to community login — no site means no login flow to protect | | Customer Community or Customer Community Login license enabled | Required for community user profiles — without it, user creation and profile deployment will fail | | Community users exist (or will self-register) | Permission sets are assigned to community users; the site must have a community-enabled profile | | Network/Site published at least once | The site must be reachable at its URL for login + MFA challenge to appear | | Target org accessible via sf CLI | Deployment and assignment commands require CLI authentication |

Note: This feature does NOT handle org setup, license provisioning, or Experience Cloud site creation. If these prerequisites are missing, deploy the base app template (e.g. propertyrentalapp) first, then enable the Community license in Setup > Feature Settings > Digital Experiences.

Installation

Via features-cli (recommended)

npx @salesforce/ui-bundle-features install mfa --ui-bundle-dir <your-ui-bundle-name>

Via patches (build-time composition)

Add to your app's patches.ts:

dependencies: ["packages/template/feature/feature-react-mfa"];

Post-Install Setup

After installing the permission set metadata:

1. Deploy to your org:

   sf project deploy start --source-dir force-app/main/default/permissionsets \
     --target-org <org-alias> --test-level NoTestRun --wait 10

   Or deploy and verify manually:

   sf project deploy start --source-dir force-app/main/default/permissionsets \
     --target-org <org-alias> --test-level NoTestRun
   
   # Wait for deployment to complete, then verify
   sf project deploy report --target-org <org-alias>

2. Verify deployment succeeded:

   sf org list metadata --metadata-type PermissionSet --target-org <org-alias> | grep MFA

3. Assign permission sets to community users:

   sf org assign permset --name MFA_Required_For_Community --target-org <org-alias>
   sf org assign permset --name API_Enabled_For_Community --target-org <org-alias>

4. Publish the site:

   sf community publish --name "<site-name>" --target-org <org-alias>

5. Verify: Open an incognito browser, navigate to the site, log in, and confirm the MFA challenge page appears.

6. (Optional) Customize MFA/login page branding: For site containers, use the Setup UI (Administration → Branding) once the platform fix (W-23140888) ships. For headless LWR sites, deploy NetworkBranding metadata via Metadata API to customize logo, colors, and footer text on the platform-rendered MFA challenge page.

Verification Methods

The platform supports these MFA verification methods (configured at the org level):

• Authenticator App (TOTP)
• Salesforce Authenticator
• WebAuthn Platform (Touch ID / Face ID)
• WebAuthn Roaming (Security Key)
• SMS
• Email OTP

Troubleshooting

| Problem | Solution | | ---------------------------------- | ------------------------------------------------------------------ | | No MFA challenge appears | Verify MFA_Required_For_Community is assigned to the user | | API_DISABLED_FOR_ORG after login | Assign API_Enabled_For_Community permission set | | MFA page shows default branding | Deploy NetworkBranding metadata via Metadata API | | vforcesite in MFA page URL | Expected behavior — platform serves MFA from Force.com Site domain |

Emergency Rollback

If MFA breaks site login and locks out all community users, follow these steps to quickly disable MFA:

Option 1: Remove Permission Set Assignments (Fastest)

# List assignment record Ids for users with MFA permission set assigned
sf data query --query "SELECT Id, AssigneeId, Assignee.Username FROM PermissionSetAssignment WHERE PermissionSet.Name = 'MFA_Required_For_Community'" --target-org <org-alias>

# Remove the assignment for each affected user (sf org assign permset has no --unassign flag;
# deleting the PermissionSetAssignment record is the supported way to unassign)
sf data delete record --sobject PermissionSetAssignment --record-id <assignment-id> --target-org <org-alias>

For bulk removal, use Data Loader:

1. Export PermissionSetAssignment records where PermissionSet.Name = 'MFA_Required_For_Community'
2. Delete those records via Data Loader

Option 2: Delete the Permission Set Metadata

# Delete from org
sf project delete source --metadata PermissionSet:MFA_Required_For_Community --target-org <org-alias> --no-prompt

# Remove from source (if needed)
rm -rf force-app/main/default/permissionsets/MFA_Required_For_Community.permissionset-meta.xml

Prevention Checklist

Before deploying MFA to production:

• [ ] Verify at least one MFA verification method is enabled in Setup → Identity → Multi-Factor Authentication
• [ ] Test with a dedicated test community user (NOT your admin account)
• [ ] Ensure test user has registered an MFA verification method
• [ ] Document your rollback plan and share with team
• [ ] Have a System Admin ready to execute rollback if needed