buildwebproject / sylius-admin-two-factor-plugin
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
Type:sylius-plugin
pkg:composer/buildwebproject/sylius-admin-two-factor-plugin
Requires
- php: ^8.2
- ext-sodium: *
- bacon/bacon-qr-code: ^3.0
- sylius/sylius: ^2.0
- symfony/rate-limiter: ^6.4 || ^7.0
Requires (Dev)
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 11:34:29 UTC
README
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.
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: truemakes 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) |
|---|---|
![]() |
![]() |
| Setup with QR code | Backup codes |
|---|---|
![]() |
![]() |
| Code at sign-in | Wrong code |
|---|---|
![]() |
![]() |
| Account (on) | Lockout |
|---|---|
![]() |
![]() |
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
-
Require the plugin:
composer require buildwebproject/sylius-admin-two-factor-plugin
-
Register the bundle in
config/bundles.php(Symfony Flex does not do this for Sylius plugins):BuildWebProject\SyliusAdminTwoFactorPlugin\BuildWebProjectSyliusAdminTwoFactorPlugin::class => ['all' => true],
-
Create
config/packages/buildwebproject_sylius_admin_two_factor.yaml:imports: - { resource: "@BuildWebProjectSyliusAdminTwoFactorPlugin/config/config.yaml" } buildwebproject_sylius_admin_two_factor: enabled: true
-
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%
-
Run the migration and clear the cache:
bin/console doctrine:migrations:migrate -n bin/console cache:clear
-
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_SECRETfirst. The plugin derives its encryption key fromkernel.secretand refuses keys shorter than 16 characters. Sylius-Standard ships a committed.env.prodwith a placeholderAPP_SECRET, which overrides.env.localin 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
- An administrator signs in with the password as usual (the Sylius admin firewall is not replaced).
- Right after the firewall (
kernel.request, priority 7) the plugin checks the session. If the administrator has two-factor set up, orrequiredis on, every admin URL except the code / setup / logout pages redirects to the code page (401JSON for AJAX requests). - 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.
- 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 withbin/console cache:pool:clear cache.rate_limiter.
Security notes
- Secrets are encrypted with a key derived from
encryption_key(BLAKE2b, one key per purpose). RotatingAPP_SECRETtherefore 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-storeandX-Robots-Tag: noindex. - Events are logged on the
securitychannel: 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.







