Multi-Factor Authentication (MFA)

Who this guide is for: Tenant administrators who want to add a second sign-in factor (an authenticator-app code) for their organization, and Embay platform operators managing the platform-wide MFA policy.

EmbayLMS supports time-based one-time passwords (TOTP) with any standard authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, Authy, etc.), plus one-time backup codes for account recovery.

MFA is off by default. Nothing changes for your users until you enable it.

How the two configuration levels interact

Resolution order at sign-in: platform setting → tenant setting → role list.

Two important guarantees:

• A user is only challenged for a code if they have completed enrollment.
• A user whose role requires MFA but who has not enrolled yet is never locked out — they see a setup reminder on their account security page.

Enable MFA for your organization (tenant admin)

1. Sign in as a tenant admin.
2. Go to Settings → Security in the sidebar.
3. Turn on Enable MFA for this organization.
4. (Optional) Under Require MFA for these roles, select the roles that must enroll (e.g. Admin, Manager).
5. Click Save changes.

From this point, users who have enrolled an authenticator app are asked for a 6-digit code after entering their password. Users without one continue to sign in with just their password (unless their role is in the required list, in which case they are reminded to enroll).

Configuration reference

What users see (enrollment)

1. Users open their avatar menu → My Profile → Two-factor authentication → Manage (or go directly to /account/security).
2. They click Set up two-factor authentication, scan the QR code with their authenticator app, and confirm with a 6-digit code.
3. EmbayLMS shows 10 one-time backup codes exactly once. Users should store them safely — each code can replace an authenticator code at sign-in once (e.g. lost phone).

Recovering a locked-out user

If a user loses both their authenticator device and their backup codes, a tenant admin can disable MFA for that user (the mfa.disable operation requires the user:update permission). The user can then sign in with their password and re-enroll. The action is written to the audit log.

Security notes (SOC 2)

• TOTP seeds are stored AES-256-GCM-encrypted — never in plaintext.
• Backup codes are stored as bcrypt hashes and are strictly one-time.
• All enrollment, disablement, and policy changes are written to the append-only audit log (resource_type: user_mfa / tenant_config).
• Codes accepted with ±1 time-step (30 s) of clock drift.

Troubleshooting