MFA (Multi-Factor Authentication)

MFA implements TOTP-based two-factor authentication for all Kiwire admin accounts, requiring a 6-digit time-based code from an authenticator app in addition to the password on every login. Compliant with ISO 27001 A.9.4.2.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/mfa/overview.png

What MFA Does

After entering their username and password, an admin must also enter a 6-digit one-time code generated by their authenticator app. The code changes every 30 seconds and is unique to the admin's enrolled device. This means that even if a password is compromised, an attacker cannot log in without also having physical access to the admin's authenticator device.

Kiwire uses the standard RFC 6238 TOTP algorithm. Any authenticator app that supports TOTP works: Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden, and others.

Enrolment Flow

1. Admin logs in with username and password.
2. If MFA is not yet enrolled, the admin is redirected to the MFA Setup page before they can access anything else.
3. The setup page shows a QR code. Open an authenticator app on a mobile device and scan the QR code.
4. The app adds a new entry labelled with the Kiwire host and the admin's email address.
5. Enter the 6-digit code currently shown in the app to confirm that enrolment is correct.
6. MFA is now active. Subsequent logins will request the TOTP code after the password step.

Verification on Login

After each successful password authentication, the admin is presented with a TOTP verification page. Enter the 6-digit code from the authenticator app and submit. The code is valid for the current 30-second window plus a one-step tolerance to account for slight clock drift between the server and the authenticator device.

Resetting MFA

If an admin loses access to their authenticator app (lost phone, factory reset, app deleted), their MFA enrolment must be reset by another admin:

• An admin with the update-admins permission can reset any other admin's MFA from the Admin Users module.
• After the reset, the admin must re-enrol by scanning a new QR code on their next login.
• Admins can also initiate a self-service MFA reset by verifying their identity via a link sent to their registered email address.

Enforcement

MFA enforcement is applied to all authenticated admin routes. Its behaviour depends on the global MFA enforcement setting:

• Force MFA enabled — all admins are redirected to MFA setup before accessing any page. No grace period.
• Force MFA disabled — admins who have already enrolled are still required to verify on every login, but admins without enrolment can access the panel without MFA.
• Grace period — if configured in Login Config, newly created admins have N days before MFA enrolment is enforced.

Disabling MFA

An admin can disable MFA for their own account from their profile settings by entering their current password. However:

• If Force MFA is enabled globally, disabling MFA is blocked.
• Disabling MFA triggers a high-severity security alert email to the configured security alert address.

Recovery Procedure

If an admin is locked out because they lost their authenticator and no other admin can reset it:

1. Contact a superuser admin to reset MFA via the Admin Users module.
2. If no admin is available, contact Kiwire support or your system administrator with server access to perform an emergency MFA reset. Document this action for audit purposes.

Technical Details

• Algorithm: RFC 6238 TOTP (Time-based One-Time Password)
• Code length: 6 digits
• Time step: 30 seconds
• Tolerance: ±1 step (allows up to 30 seconds of clock drift)
• QR URI issuer: the live Kiwire hostname
• Implementation: pure-PHP TOTP (no external API dependency)

Required Permissions

All admins manage their own MFA from their profile. update-admins permission is required to reset another admin's MFA.