/experience-ui-bundle-mfa-configure

name: experience-ui-bundle-mfa-configure
description: "Configure Multi-Factor Authentication (MFA) for Salesforce Experience Site users. TRIGGER when: user wants to enable MFA on a community, enforce two-factor authentication for portal users, add MFA to a React Experience Site / Web App, configure ForceTwoFactor permission, create MFA permission sets for external users, or troubleshoot MFA not appearing on login. Also triggers on: MFA community, two-factor portal, ForceTwoFactor permission set, MFA Experience Cloud, MFA React site, identity verification community, MFA experience site, ForceTwoFactor permissionset-meta.xml, MFA permissionset-meta.xml. DO NOT TRIGGER when: configuring org-wide MFA for internal users (that's Setup > Identity Verification), building custom login UI components (use experience-ui-bundle-frontend-generate), or generating generic permission sets without MFA context (use platform-permission-set-generate)."
metadata:
  version: "1.1"
  domains: ["Experience"]
  minApiVersion: "47.0"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.0.0"
  accessCheck: "OrgPermissions.Networks"
  relatedSkills:
    - "dx-org-permission-set-assign"
    - "experience-ui-bundle-deploy"
    - "experience-ui-bundle-frontend-generate"
    - "platform-metadata-deploy"
    - "platform-permission-set-generate"

Enabling MFA on Experience Sites

Enable Multi-Factor Authentication for Experience Site (Community) users by deploying the correct permission sets and verifying the platform-handled MFA challenge flow.

Scope

**In scope:**

• Deploying `ForceTwoFactor` permission set for community users
• Deploying `ApiEnabled` permission set (required for post-login API calls)
• Assigning permission sets to community users
• Troubleshooting MFA not appearing on login
• Customizing MFA/login page branding via NetworkBranding metadata

**Out of scope — delegate elsewhere:**

• Building custom login UI → `experience-ui-bundle-frontend-generate`
• Creating generic permission sets → `platform-permission-set-generate`
• Assigning permission sets (if already deployed) → `dx-org-permission-set-assign`
• Deploying metadata to org → `platform-metadata-deploy`
• Org-wide MFA for internal Salesforce users → Setup > Identity Verification (not a skill)

---

Prerequisites

Before using this skill, 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 | | **Community users exist** (or will self-register) | Permission sets are assigned to community users; the site must have a community-enabled profile | | **Customer Community or Customer Community Login license enabled** | Required for community user profiles — without it, user creation and profile deployment will fail | | **Network/Site published at least once** | The site must be reachable at its URL for login + MFA challenge to appear |

> **Note:** This skill does NOT handle org setup, license provisioning, or Experience Cloud site creation. If these prerequisites are missing, set them up first via Setup > Digital Experiences > All Sites > New, or deploy your site's base app bundle.

---

Required Inputs

Gather before acting:

| Input | How to determine | |-------|-----------------| | **Target org** | Org alias for `sf` CLI commands | | **Site name** | Experience Site (Network) name — resolve via `SELECT Id, Name FROM Network` (see Step 1); this is the site/Network name, NOT the `uiBundles/` app name | | **Community users** | Which users or profiles to assign MFA to |

---

Critical Domain Knowledge

These facts are non-obvious and frequently cause confusion:

| Fact | Detail | |------|--------| | **No custom UI needed** | Platform renders the MFA challenge page — no React/LWC component required | | **ForceTwoFactor permission** | The ONLY way to enforce MFA for community users at login | | **Org Identity Verification checkbox** | Does NOT enforce MFA for community/portal users — only for internal users | | **vforcesite domain** | MFA challenge page is always served from the underlying Force.com Site domain — this is expected | | **Always deploy ApiEnabled** | React Experience Sites make post-login REST/Connect API calls (`sdk.graphql`, `sdk.fetch`); without `ApiEnabled` they fail with `API_DISABLED_FOR_ORG` | | **Social Login / SSO is separate from MFA** | React sites render configured Auth Providers via the built-in Social Login component (shipped in 264) — driven by Auth Provider setup, not by the MFA permission sets. See `references/social-login.md`. | | **Login-page branding works for React sites** | Since 264, the NetworkBranding "Login & Registration" section is shown in Setup for Site Containers, so logo/color/footer can be customized in the UI — Metadata API still works too. |

---

Workflow

Step 1: Resolve the target site (Network)

These are React Experience Sites, so **both** permission sets are always deployed — `ForceTwoFactor` (enforces MFA) and `ApiEnabled` (React sites make post-login API calls).

Resolve the Experience Site's real name and Id from the org — do **not** assume the `uiBundles/` app folder name is the site name. They are frequently different, and the site name must come from the org (the deploy target), not the local project. `<site-name>` and `<NETWORK_ID>` below come from here:

sf data query --target-org <org-alias> \
  --query "SELECT Id, Name FROM Network" --json

• One site → use its `Name` as `<site-name>` and `Id` as `<NETWORK_ID>`.
• Multiple sites → ask the user which one (show the names).
• Zero sites → the site isn't deployed yet; stop and tell the user (see Prerequisites).

Step 2: Generate permission set files

First, detect the project's source directory:

jq -r '.packageDirectories[0].path + "/main/default"' sfdx-project.json

Use the result as `<source-dir>` (e