Search by

buildwebproject / sylius-admin-two-factor-plugin

buildwebproject

Two-factor sign-in (TOTP authenticator app + one-time backup codes) for the Sylius 2 admin panel, with lockout, optional enforcement for every administrator and admin API protection.

Package info

github.com/buildwebproject/sylius-admin-two-factor-plugin

Homepage

Type:sylius-plugin

pkg:composer/buildwebproject/sylius-admin-two-factor-plugin

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-16 11:33 UTC

This package is auto-updated.

Last update: 2026-11-16 11:34:29 UTC


README

BuildWebProject

Sylius Admin Two-Factor Plugin

Two-factor sign-in for the Sylius 2 admin panel: authenticator-app codes (TOTP), one-time backup codes, lockout after wrong codes, optional enforcement for every administrator and protection of the password-only admin API.

Latest version MIT license Sylius 2 PHP 8.2+

Features

  • Works with every authenticator app: Google Authenticator, Microsoft Authenticator, 1Password, Authy, Bitwarden… (RFC 6238, SHA-1, 6 digits, 30 seconds).
  • QR code generated on your server (SVG, bacon/bacon-qr-code): the secret is never sent to a third-party image service.
  • One-time backup codes (8 by default), shown once with a download button, usable once each, and replaceable at any time.
  • Each code works only once: a used authenticator code cannot be replayed, even inside its 30-second window.
  • Lockout: too many wrong codes (5 per administrator and IP within 15 minutes by default) sign the session out.
  • Optional enforcement: required: true makes every administrator set it up at their next page and blocks turning it off.
  • Admin API protection: the Sylius admin API signs in with a password only, so the plugin refuses the API token for administrators who use (or must use) two-factor. Without this, the API would be a way around the second factor.
  • Encrypted at rest: authenticator secrets are encrypted (libsodium XSalsa20-Poly1305) and backup codes stored only as keyed hashes (HMAC-SHA256).
  • Native Sylius 2 admin UI: Tabler design, Twig Hooks, translations, a shield icon in the admin navbar.
  • No changes to your entities: setups live in a separate table linked to sylius_admin_user, removed automatically with the administrator.
  • Recovery command for an administrator who lost both phone and backup codes.

Screenshots

Navbar Account (off)
Shield icon in the admin navbar Two-factor account page, off
Setup with QR code Backup codes
Setup page with QR code Backup codes shown once
Code at sign-in Wrong code
Verify page Wrong code message
Account (on) Lockout
Two-factor account page, on Signed out after too many wrong codes

Requirements

Version
PHP 8.2 or newer, with ext-sodium
Sylius 2.x (tested on 2.3.2)
Symfony 6.4 or 7.x (tested on 7.4)
Database MySQL / MariaDB (migration provided)

Installation

  1. Require the plugin:

    composer require buildwebproject/sylius-admin-two-factor-plugin
  2. Register the bundle in config/bundles.php (Symfony Flex does not do this for Sylius plugins):

    BuildWebProject\SyliusAdminTwoFactorPlugin\BuildWebProjectSyliusAdminTwoFactorPlugin::class => ['all' => true],
  3. Create config/packages/buildwebproject_sylius_admin_two_factor.yaml:

    imports:
        - { resource: "@BuildWebProjectSyliusAdminTwoFactorPlugin/config/config.yaml" }
    
    buildwebproject_sylius_admin_two_factor:
        enabled: true
  4. Create config/routes/buildwebproject_sylius_admin_two_factor.yaml:

    buildwebproject_sylius_admin_two_factor:
        resource: "@BuildWebProjectSyliusAdminTwoFactorPlugin/config/routes/admin.yaml"
        prefix: /%sylius_admin.path_name%
  5. Run the migration and clear the cache:

    bin/console doctrine:migrations:migrate -n
    bin/console cache:clear
  6. Sign in to the admin panel, click the shield icon in the top bar and choose Set up two-factor sign-in.

Check your APP_SECRET first. The plugin derives its encryption key from kernel.secret and refuses keys shorter than 16 characters. Sylius-Standard ships a committed .env.prod with a placeholder APP_SECRET, which overrides .env.local in production. Put your real secret in .env.prod.local (or a real environment variable / Symfony secret).

Configuration

All options with their defaults:

buildwebproject_sylius_admin_two_factor:
    # Turn the whole feature on or off. Saved setups are kept while off.
    enabled: true

    # Every administrator must set up two-factor at the next page and cannot turn it off.
    required: false

    # Name shown in the authenticator app. Defaults to the request host.
    issuer: null

    # Number of one-time backup codes (4-20).
    backup_codes: 8

    # Wrong codes allowed per administrator + IP within lock_interval before the session is signed out (3-20).
    max_attempts: 5
    lock_interval: '15 minutes'

    # "deny": refuse the password-only admin API token for administrators who use (or must use) two-factor.
    # "allow": keep the admin API open (not recommended).
    admin_api: deny
    admin_api_firewall: api_admin

    # Key material for encryption/hashing (min. 16 characters). Changing it makes saved setups unreadable.
    encryption_key: '%kernel.secret%'

The plugin uses Symfony configuration only; no environment variables of its own. Use %env(...)% in this file if you want per-environment values.

How it works

  1. An administrator signs in with the password as usual (the Sylius admin firewall is not replaced).
  2. Right after the firewall (kernel.request, priority 7) the plugin checks the session. If the administrator has two-factor set up, or required is on, every admin URL except the code / setup / logout pages redirects to the code page (401 JSON for AJAX requests).
  3. A correct authenticator or backup code marks the session as passed and migrates the session id (protection against session fixation). A remember-me sign-in starts a new session, so it asks for a code again.
  4. Wrong codes are counted with the Symfony Rate Limiter (limiter.buildwebproject_admin_two_factor) per administrator and IP. When the limit is reached the session is signed out and a flash message explains why.

Routes

Route Path Purpose
buildwebproject_admin_two_factor_account /admin/two-factor Status, new backup codes, turn off
buildwebproject_admin_two_factor_setup /admin/two-factor/setup QR code and first code
buildwebproject_admin_two_factor_verify /admin/two-factor/verify Code at sign-in

Database

Table bwp_admin_two_factor (admin_user_id unique, ON DELETE CASCADE), created by migration BuildWebProject\SyliusAdminTwoFactorPlugin\Migrations\Version20261116120000.

Twig hooks

Hook Name Template
sylius_admin.common.component.navbar.items buildwebproject_two_factor @BuildWebProjectSyliusAdminTwoFactorPlugin/admin/navbar/two_factor.html.twig
buildwebproject_admin_two_factor.account sidebar, navbar, content Standard admin frame around the account page
buildwebproject_admin_two_factor.account.content flashes, body Account page content

Override any template the usual Symfony way in templates/bundles/BuildWebProjectSyliusAdminTwoFactorPlugin/, or disable the navbar icon with enabled: false on that hook.

Translations

English messages are in translations/messages.en.yaml and translations/flashes.en.yaml under the buildwebproject_sylius_admin_two_factor.ui.* keys. Add messages.<locale>.yaml files in your application to translate.

Lost access

  • Lost phone: sign in with one of the backup codes, then turn two-factor off and on again (or create new backup codes).

  • Lost phone and backup codes: on the server, remove the setup:

    bin/console buildwebproject:admin-two-factor:reset admin@example.com
  • Locked out after wrong codes: wait for lock_interval, or clear the limiter right away with bin/console cache:pool:clear cache.rate_limiter.

Security notes

  • Secrets are encrypted with a key derived from encryption_key (BLAKE2b, one key per purpose). Rotating APP_SECRET therefore requires resetting every administrator's setup.
  • Codes are compared in constant time; all three accepted time steps are always checked.
  • The setup pages send Cache-Control: no-store and X-Robots-Tag: noindex.
  • Events are logged on the security channel: two-factor turned on/off, lockouts (with IP).
  • Please report security issues privately to buildwebproject@gmail.com, not in public issues.

Testing

composer install
vendor/bin/phpunit

Unit tests cover the RFC 6238 reference vectors, replay protection, clock drift, encryption tamper detection and backup code hashing. Each release is also tested end-to-end in a Sylius 2.3 shop: setup, sign-in, wrong codes, backup codes, replay, lockout, required mode and admin API protection.

License

MIT. See LICENSE.

Made by BuildWebProject, a Sylius e-commerce studio from India. Need a custom Sylius plugin or a complete store? Get in touch.