Multi-factor authentication

MisterShell supports None, Email, and Authenticator app (TOTP) MFA for Local and LDAP providers. Administrators choose one method per provider. The built-in admin@mistershell.local recovery account remains exempt; an LDAP account with the same email is not exempt.

Authenticator enrollment is mandatory when the provider requires TOTP. At sign-in, scan the QR code or enter the setup key, confirm a six-digit code, then copy or download the ten one-time recovery codes. MisterShell creates the session only after you confirm that the recovery codes are saved. Each recovery code works once.

Open My Account > Account Security > Authenticator App to see enrollment status and the number of unused recovery codes. You can replace an authenticator or regenerate recovery codes after re-entering your Local or LDAP password and proving the current authenticator or a recovery code. Replacing the authenticator invalidates existing MFA session proof and signs you out. Regenerating codes invalidates the old code set.

Administrators with user-write permission can use Reset MFA enrollment in the Users table. Resetting enrollment does not disable the provider requirement; the user must enroll again on the next sign-in. Password resets do not remove MFA enrollment.

Disabling an LDAP provider stops new sign-ins but does not erase its MFA policy from existing sessions. Those sessions continue to require the stored method and revisions until their normal expiry or another policy change invalidates them. If the provider is deleted or is no longer LDAP, its policy cannot be verified and affected sessions fail closed.

Changing a provider from TOTP to None or Email retains its users’ authenticator enrollments and unused recovery codes. If TOTP is enabled again, those users verify with their existing authenticator. Use Reset MFA enrollment to require a new setup.

Deleting a user removes their enrollment and recovery codes. Deleting an LDAP provider removes all authenticator enrollments tied to that provider while preserving the user accounts. Historical security audit evidence remains subject to the configured retention policy.