README

Time-based one-time password (TOTP) two-factor authentication for both backend users and frontend users.

What It Supports

• Backend user 2FA enrollment, verification, and recovery-code flow
• Frontend user 2FA enrollment, verification, and recovery-code flow
• Global enforcement middleware for authenticated backend and frontend sessions
• Configurable enforcement modes:
  • backend: off, all, roles
  • frontend: off, enrolled, all
• Admin management in Security tabs for both user types (permission-gated)
• Self-service panel for backend users on their own profile
• Admin actions:
  • force reset enrollment
  • invalidate active 2FA session
  • regenerate recovery codes

Requirements

• Winter CMS 1.3 (Laravel 12)
• PHP >= 8.2
• Composer packages:
  • pragmarx/google2fa
  • bacon/bacon-qr-code

Installation

composer require mercator/totp2fa
php artisan winter:up

Permissions

• mercator.totp2fa.manage_settings
• mercator.totp2fa.manage_backend_user_2fa
• mercator.totp2fa.manage_frontend_user_2fa

Settings

Backend Settings page:

Settings -> Security -> TOTP 2FA

Important options:

• require_mode for backend users (off|all|roles)
• require_roles for role-based backend enforcement
• require_frontend_mode for frontend users (off|enrolled|all)
• frontend_challenge_url for the frontend challenge page URL (defaults to /totp2fa/challenge and may resolve to a CMS page such as /totp-challenge)

Backend users can also self-manage TOTP 2FA from:

Settings -> My Settings -> Manage TOTP 2FA

This opens the backend My Account page, where TOTP is managed inline in the Security tab.

Usage Hints

• Backend users who are required to use 2FA are redirected into enrollment or challenge automatically after login.
• Frontend users should have a dedicated challenge page that contains the totpFrontendChallenge component.
• If you use a custom frontend challenge CMS page, set frontend_challenge_url to that page URL so middleware and login redirects stay consistent.
• To offer self-service management on the frontend, place the totpFrontendManager component on a CMS page such as /totp-manage.
• The frontend manager can show a sign-in form when no frontend user is logged in, then continue into challenge or setup as required.
• Recovery codes are intended to be shown once immediately after enrollment or regeneration, so users should save them right away.
• Admins can manage backend users and frontend users from the backend Security tab when they have the corresponding TOTP permissions.