MfaService
class MfaService (View source)
Methods
MfaService constructor
Get the user MFA repository
Get user's MFA settings
Get or create MFA settings for a user
Generate a new secret key for authenticator app-based MFA
Check if a secret key is valid for TOTP authentication
Generate a simple numeric verification code for email-based MFA
Disable MFA for a user
Consume the supplied code if it is one of the user's recovery codes.
Verify a TOTP code, email code, or recovery code for a user
Burn the pending email code so it cannot be guessed any further.
Generate a QR code SVG for MFA setup
Send verification code via email for email-based MFA
Generates a new verification code if the existing one has expired
Check if MFA is enforced for a user
Check if MFA setup is required for a user
Check if MFA is enabled for a user
Get MFA type for a user
Get recovery codes for a user
Generate new recovery codes for a user
Update MFA secret for a user after successful verification
Details
__construct(UserMfaRepositoryInterface $userMfaRepository, ConfigurationManager $configManager, MailService $mailService, LoggerInterface|null $logger = null, UserTimezoneService|null $userTimezoneService = null)
MfaService constructor
UserMfaRepositoryInterface
getUserMfaRepository()
Get the user MFA repository
UserMfa|null
getUserMfa(int $userId)
Get user's MFA settings
This method only retrieves the MFA settings and does not create a new record.
UserMfa|null
getOrCreateUserMfa(int $userId)
Get or create MFA settings for a user
This method will create a new MFA record if one doesn't exist.
string
generateSecretKey(int $length = 16)
Generate a new secret key for authenticator app-based MFA
This method generates a proper Base32-encoded secret key that is compatible with Google Authenticator, Microsoft Authenticator, and other TOTP apps
bool
isValidTotpSecret(string|null $secret)
Check if a secret key is valid for TOTP authentication
This method checks if a secret key meets the requirements for use with TOTP authenticator apps (proper Base32 encoding)
string
generateEmailVerificationCode()
Generate a simple numeric verification code for email-based MFA
UserMfa
enableMfa(int $userId, string $type = UserMfa::TYPE_APP)
Enable MFA for a user
UserMfa|null
disableMfa(int $userId)
Disable MFA for a user
bool
consumeRecoveryCode(int $userId, string $code)
Consume the supplied code if it is one of the user's recovery codes.
A recovery code is the documented way back into a locked account, so callers may check it before any lockout gate.
bool
verifyCode(int $userId, string $code)
Verify a TOTP code, email code, or recovery code for a user
void
invalidatePendingEmailCode(int $userId)
Burn the pending email code so it cannot be guessed any further.
Called when a user trips the second-factor attempt limit: the lockout window can be configured shorter than the code lifetime, and without this the same code would still be live when the lockout lifts.
string
generateQrCodeSvg(string $email, string $secret)
Generate a QR code SVG for MFA setup
string
sendEmailVerificationCode(int $userId, string $email)
Send verification code via email for email-based MFA
Generates a new verification code, saves it to the database, and sends it via email. For email-based MFA, the secret field is used to store the most recent verification code. The code is temporary and should be regenerated for each verification attempt.
string|null
refreshEmailVerificationCodeIfNeeded(int $userId, string $email)
Generates a new verification code if the existing one has expired
This is useful for generating a new code when a user tries to log in again after their previous code has expired.
bool
isMfaEnforced(int $userId, object $db, string|null $authMethod = null)
Check if MFA is enforced for a user
This checks:
- Global mfa.enabled setting (MFA feature must be available)
- Global mfa.enforced setting (enforcement must be enabled)
- mfa.skip_for_external_auth exemption for external IdP logins
- User or group has user_enforce_mfa permission
bool
isMfaSetupRequired(int $userId, object $db, string|null $authMethod = null)
Check if MFA setup is required for a user
Returns true if MFA is enforced for the user but they haven't set it up yet.
bool
isMfaEnabled(int $userId)
Check if MFA is enabled for a user
string|null
getMfaType(int $userId)
Get MFA type for a user
array
getRecoveryCodes(int $userId)
Get recovery codes for a user
array
regenerateRecoveryCodes(int $userId)
Generate new recovery codes for a user
void
updateMfaSecretAfterLogin(int $userId, string|null $email = null)
Update MFA secret for a user after successful verification
For email-based MFA: Generates a new verification code for security For app-based MFA: Preserves the existing secret (must not change or app codes won't work)