Control CoreDocs

MFA and Passkeys

Audience: Administrators, Security Officers
Time: ~15 min
Prerequisites: Control Plane access as Super Administrator; authenticator app (Google Authenticator, Microsoft Authenticator) or FIDO2 security key / platform passkey

Multi-factor authentication (MFA) and passkeys reduce credential theft risk for Control Plane operators.

TOTP MFA

Per-user enrollment

  1. Open Settings → Users and select a user.
  2. Choose Enable MFA and scan the QR code with a TOTP authenticator app.
  3. Enter the 6-digit code to confirm enrollment.

Enrolled users are always challenged at password login.

Organization-wide enforcement

Set environment variable AUTH_REQUIRE_MFA=true on the Control Plane API deployment. Users without MFA cannot sign in until they enroll. The built-in administrator account is exempt so bootstrap access is never lost.

Troubleshooting: If login returns Multi-factor authentication code required with header X-MFA-Required: true, supply mfa_code in the login request or complete enrollment. If codes are rejected, verify device time sync (NTP) — TOTP windows are 30 seconds.

Passkeys (WebAuthn / FIDO2)

Passkeys provide phishing-resistant, passwordless sign-in using platform authenticators (Touch ID, Windows Hello) or roaming security keys.

Enable passkeys

  1. Open Settings → Users → Authentication Methods.
  2. Enable Passkey authentication.
  3. Ensure PASSKEY_RP_ID matches your Control Plane hostname (derived from FRONTEND_URL by default).

Register a passkey

  1. Sign in with password or SSO.
  2. Open Settings → Users → Passkeys (or follow the post-login prompt).
  3. Complete the browser WebAuthn ceremony when prompted.

Sign in with passkey

On the login page, choose Sign in with passkey. The Control Plane issues a usernameless challenge so credential IDs cannot be enumerated by unauthenticated callers.

Troubleshooting: Registration challenge expired — retry within 5 minutes; challenges are single-use. RP ID mismatch — set PASSKEY_RP_ID to the exact host users visit (no port). For multi-origin deployments, configure PASSKEY_ALLOWED_ORIGINS as a comma-separated HTTPS list.

Upcoming enhancements

  • Shared Redis challenge store for multi-replica Control Plane deployments
  • Step-up passkey authentication before high-risk actions (production control promotion, signing-key rotation)

Best practices

ScenarioRecommendation
Remote administratorsRequire MFA or passkeys; disable password-only for standard users
Break-glassRetain one MFA-enrolled administrator account with recovery procedure documented
Shared workstationsPrefer roaming FIDO2 keys over platform passkeys

Next steps