README

Enterprise Security Plugin

3BRS Enterprise Security

Password Policy
Password History
Password Expiration
Password Change Notifications
Two-Factor Authentication
3rd-party OAuth (Social Login)
Magic Link Login
Passkey Login (WebAuthn / FIDO2)
Account Lockout & Rate Limiting
Session Management & Login Notifications
Centralized Security Settings UI
Self-Service Account Deletion (GDPR)
Admin IP Whitelist
Admin IP Blacklist
Admin Customer Management
Password Login

Features

Most features ship disabled by default — enable and tune the ones you need (each linked doc covers its options and defaults). Two are active out of the box: Password Login, which is on so existing stores keep working, and Password Policy, which has no on/off switch and applies as soon as the plugin is installed (customers: minimum 8 characters; admins: minimum 12, with an uppercase letter, a lowercase letter, a number and a special character).

Feature	What it does	Doc
Password Policy	Configurable password complexity (min/max length + uppercase / lowercase / number / special-character rules), separately per customer and admin group; overrides Sylius's weak 3-character default.	password-policy
Password History	Prevents reuse of recent passwords, with a configurable remembered count per group; customer and admin history stored separately.	password-history
Password Expiration	Forces a password change after a configurable number of days, with an optional `force_change` on next login; independent for customers and admins. Existing accounts are measured from their creation date until the first change, so enabling it won't reset everyone at once.	password-expiration
Password Change Notifications	Emails the user on every password change (account settings, forgot-password reset, admin-initiated) with the timestamp, IP address and a secure-account link.	password-change-notifications
Two-Factor Authentication	TOTP 2FA (Google Authenticator, Authy, 1Password, …) with QR-code setup, single-use recovery codes, trusted devices and per-group `disabled` / `allowed` / `enforced` modes. Built on `scheb/2fa-bundle`.	two-factor-authentication
3rd-party OAuth (Social Login)	Google, Apple and Microsoft sign-in per group, with account-link takeover protection (a single-use, time-limited emailed code), optional domain-gated auto-registration and an extensible provider registry.	oauth-social-login
Magic Link Login	Passwordless email sign-in with single-use, hashed, time-limited tokens, anti-enumeration, timing-attack padding and rate limiting. As a passwordless method it bypasses 2FA (the second factor guards password login only).	magic-link-login
Passkey Login (WebAuthn / FIDO2)	Passwordless passkeys (Touch ID / Windows Hello / Android lock / hardware keys), multiple labelled keys per user, built on `web-auth/webauthn-lib`. As a passwordless method it bypasses 2FA (the second factor guards password login only).	passkey-login
Account Lockout & Rate Limiting	Persistent per-user account lockout after N failed sign-ins (auto- or admin-unlock) plus ephemeral request rate limiting (login, password reset and magic link for both groups; registration for customers).	account-lockout-rate-limiting
Session Management & Login Notifications	Active-session listing with manual revocation (single or all-other), plus optional email alerts on sign-in from a previously unseen device; pluggable GeoIP lookup.	session-management-login-notifications
Centralized Security Settings UI	A single admin page (`/admin/security-settings`) to configure every feature at runtime — values persist in the database and apply on the next request, no YAML edits or redeploys.	centralized-security-settings-ui
Self-Service Account Deletion (GDPR)	Customer-driven erasure (GDPR right to be forgotten) with a configurable grace period, admin-side cancellation and a cron that anonymizes name / email / phone / address.	account-deletion-gdpr
Admin IP Whitelist	Restrict admin-panel access to allowed IPs / CIDR ranges, with a team-wide global list plus optional per-admin lists.	admin-ip-whitelist
Admin IP Blacklist	Block specific IPs / CIDR ranges from the admin panel with a global deny-list — always wins over the whitelist, is identity-agnostic, and fails open when empty.	admin-ip-blacklist
Admin Customer Management	A Security section on the Sylius customer detail page — force password reset, block / unblock, sign out of all or individual sessions, plus active-sessions and login-history tables.	admin-customer-management
Password Login	Global per-group (customer / admin) switch — on by default — for classic email + password sign-in and registration. Turn it off for a group and its login / registration forms are hidden (including the checkout inline sign-in), its forgotten-password pages are closed, the admin panel creates that group's accounts without a password, everyone must use a magic link, passkey or social login, and that group's password expiration / force-change pause too.	password-login

Installation

This section is for consuming the plugin in your own Sylius project — you register the bundle/plugin and wire the config yourself. If you instead want to work on the plugin itself, skip to Development below: its bundled test application already has the bundle, plugin and routes registered, so you don't repeat these steps.

This plugin requires the standalone 3brs/enterprise-security-bundle package and does not work without it. The bundle is the framework-agnostic core (security validators, services, entity contracts); the plugin is the thin Sylius integration layer on top (admin / shop UI, controllers, routes, fixtures). That's why step 1 installs both packages (the bundle comes in as a dependency of the plugin) and step 2 registers them, and the entity traits in step 5 implement interfaces that live in the bundle.

Almost every feature ships disabled by default (see each feature's doc under docs/). Password Login is on so existing stores keep working, and Password Policy applies from installation with no on/off switch. You enable only what you need in step 3, and the firewall / entity wiring in steps 5–6 is only required for the features you turn on.

Require the plugin (its standalone bundle and the Scheb 2FA bundle are pulled in automatically as dependencies):
```
composer require 3brs/sylius-enterprise-security-plugin
```

return [
    // ...
    Scheb\TwoFactorBundle\SchebTwoFactorBundle::class => ['all' => true],
    ThreeBRS\EnterpriseSecurityBundle\ThreeBRSEnterpriseSecurityBundle::class => ['all' => true],
    ThreeBRS\SyliusEnterpriseSecurityPlugin\ThreeBRSSyliusEnterpriseSecurityPlugin::class => ['all' => true],
];

Import the plugin configuration and enable the features you want by creating config/packages/threebrs_sylius_enterprise_security_plugin.yaml:

imports:
    - { resource: "@ThreeBRSSyliusEnterpriseSecurityPlugin/config/config.yaml" }

three_brs_sylius_enterprise_security:
    # Turn on and tune the features you need — each feature's doc under
    # docs/ documents its options and defaults (everything is off by default,
    # except Password Login, which is on).

Import the plugin routes by creating config/routes/three_brs_enterprise_security.yaml (without this none of the plugin endpoints — passkey, magic link, 2FA setup, OAuth, account deletion, settings UI — are registered):
```
three_brs_enterprise_security:
    resource: "@ThreeBRSSyliusEnterpriseSecurityPlugin/config/routes.yaml"
```

Add the relevant traits to your ShopUser and AdminUser entities. Include the traits for the features you enabled — TwoFactorAuth* (Two-Factor Authentication), Lockable* (Account Lockout) — and PasswordExpiration* whichever way you configure Password Expiration: Force password reset in admin customer management has no on/off switch of its own, and the button is shown to administrators whether or not the feature is on. (Password Expiration also reads the account creation date via getCreatedAt() as its fallback for users who have never changed their password — Sylius's base ShopUser / AdminUser already expose it, so no extra wiring is needed here.) The full set:

// src/Entity/User/ShopUser.php
use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Core\Model\ShopUser as BaseShopUser;
use ThreeBRS\EnterpriseSecurityBundle\Lockout\LockableShopUserInterface;
use ThreeBRS\EnterpriseSecurityBundle\PasswordExpiration\PasswordExpirationShopUserInterface;
use ThreeBRS\EnterpriseSecurityBundle\TwoFactor\TwoFactorAuthShopUserInterface;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\LockableShopUserTrait;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\PasswordExpirationShopUserTrait;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\TwoFactorAuthShopUserTrait;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_shop_user')]
class ShopUser extends BaseShopUser implements PasswordExpirationShopUserInterface, TwoFactorAuthShopUserInterface, LockableShopUserInterface
{
    use PasswordExpirationShopUserTrait;
    use TwoFactorAuthShopUserTrait;
    use LockableShopUserTrait;
}

// src/Entity/User/AdminUser.php
use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Core\Model\AdminUser as BaseAdminUser;
use ThreeBRS\EnterpriseSecurityBundle\Lockout\LockableAdminUserInterface;
use ThreeBRS\EnterpriseSecurityBundle\PasswordExpiration\PasswordExpirationAdminUserInterface;
use ThreeBRS\EnterpriseSecurityBundle\TwoFactor\TwoFactorAuthAdminUserInterface;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\LockableAdminUserTrait;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\PasswordExpirationAdminUserTrait;
use ThreeBRS\SyliusEnterpriseSecurityPlugin\Model\TwoFactorAuthAdminUserTrait;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_admin_user')]
class AdminUser extends BaseAdminUser implements PasswordExpirationAdminUserInterface, TwoFactorAuthAdminUserInterface, LockableAdminUserInterface
{
    use PasswordExpirationAdminUserTrait;
    use TwoFactorAuthAdminUserTrait;
    use LockableAdminUserTrait;
}

The traits add mapped columns, so both classes must be Doctrine entities registered as your application's shop and admin user models — which is how a standard Sylius application already ships them. Step 7 creates the columns from that mapping.

Magic link, passkey, OAuth, session management, login notifications and account deletion keep their data in their own tables (foreign-keyed to ShopUser / AdminUser) and need no traits.

Configure the firewall for the features you enabled, in config/packages/security.yaml (and config/packages/scheb_2fa.yaml for 2FA). Each feature's doc under docs/ contains the exact block to copy:
- Two-Factor Authentication — the scheb_2fa.yaml config, the shop success_handler, the two_factor blocks on the shop / admin firewalls, and the two access_control entries granting IS_AUTHENTICATED_2FA_IN_PROGRESS on the challenge pages. Without those, a token still awaiting its second factor cannot reach the page that asks for it.
- 3rd-party OAuth, Magic Link Login, Passkey Login — the PUBLIC_ACCESS access_control entries that expose their login endpoints.
Update the database schema to create the plugin tables (three_brs_*) and the trait columns added in step 5:
```
bin/console doctrine:schema:update --complete --force
```
The plugin ships no Doctrine migrations. The command above reads the entity mapping and applies it directly, which suits development. For production, generate a migration from the same mapping with bin/console doctrine:migrations:diff (once the bundle and the step 5 traits are in place) and run it through your usual deployment workflow, likewise for any later upgrade that adds tables or columns.
Install the bundled assets (e.g. the passkey browser script):
```
bin/console assets:install
```

Troubleshooting

`Cannot create union with both "object" and class type` during cache clear / warmup

If bin/console cache:clear (or any route / API metadata warmup) fails with:

Cannot create union with both "object" and class type.

this is an upstream api-platform regression, not a plugin bug. API Platform's property-metadata scanner (Symfony's PhpStanExtractor → TypeInfo) chokes on generic @template T of object PHPDoc present in some of the plugin's transitive dependencies (e.g. web-auth/webauthn-lib), trying to build an object|SomeClass union that TypeInfo rejects. Because API Platform is enabled by default in Sylius 2, you hit it right after installing the plugin.

It affects api-platform 4.3.x (reproduced on 4.3.5–4.3.7 and still on 4.3.17; no fixed release exists at the time of writing). Until an upstream fix ships, work around it by decorating the property-info extractors with a wrapper that swallows the TypeInfo exception.

Add the decorator class to your application — use the plugin's SafePhpStanExtractor as a reference implementation. It implements every property-info extractor interface (on Symfony 7.3+ also ConstructorArgumentTypeExtractorInterface) and returns null whenever the inner extractor throws Symfony\Component\TypeInfo\Exception\InvalidArgumentException. Then register it over both Symfony's and API Platform's extractor services:

# config/services.yaml
services:
    App\PropertyInfo\SafePhpStanExtractor:
        arguments: { $inner: '@.inner' }
        decorates: property_info.phpstan_extractor
        decoration_on_invalid: ignore

    app.property_info.safe_php_doc_extractor:
        class: App\PropertyInfo\SafePhpStanExtractor
        arguments: { $inner: '@.inner' }
        decorates: property_info.php_doc_extractor
        decoration_on_invalid: ignore

    app.property_info.safe_reflection_extractor:
        class: App\PropertyInfo\SafePhpStanExtractor
        arguments: { $inner: '@.inner' }
        decorates: property_info.reflection_extractor
        decoration_on_invalid: ignore

    # API Platform registers its own parallel extractor services — decorate those too:
    app.property_info.api_platform_safe_phpstan_extractor:
        class: App\PropertyInfo\SafePhpStanExtractor
        arguments: { $inner: '@.inner' }
        decorates: api_platform.property_info.phpstan_extractor
        decoration_on_invalid: ignore

    app.property_info.api_platform_safe_php_doc_extractor:
        class: App\PropertyInfo\SafePhpStanExtractor
        arguments: { $inner: '@.inner' }
        decorates: api_platform.property_info.php_doc_extractor
        decoration_on_invalid: ignore

    app.property_info.api_platform_safe_reflection_extractor:
        class: App\PropertyInfo\SafePhpStanExtractor
        arguments: { $inner: '@.inner' }
        decorates: api_platform.property_info.reflection_extractor
        decoration_on_invalid: ignore

The decorator is harmless once the upstream bug is fixed (it only catches an exception that no longer fires), but remove it after you upgrade to a fixed api-platform release to keep your container clean.

`Unable to generate an IRI for the item of type ...` on API responses

If, after adding the decorator above, an API endpoint that embeds related resources fails with a 400 such as:

Unable to generate an IRI for the item of type "App\Entity\Product\ProductImage"

— for example GET /api/v2/shop/products (embedded product images) or GET /api/v2/admin/product-variants/{code} (embedded channel pricings) — disable API Platform's constructor property-info extractor:

# config/packages/property_info.yaml
framework:
    property_info:
        with_constructor_extractor: false

On api-platform 4.3.x this extractor runs before Doctrine's and resolves relation properties such as Image::$owner to a bare object (from their @var object|null PHPDoc), hiding the concrete related class that API Platform needs to build nested IRIs like /shop/products/{code}/images/{id}. Turning it off lets the Doctrine extractor resolve the concrete class again. false is also Symfony's current default for this setting, so this only makes it explicit (and silences the related Symfony 7.3 deprecation); the Symfony recipe ships it pre-enabled, which is why you may need to flip it.

Development

This section is only for contributing to / developing the plugin — not for installing it into your own app (that's the Installation section above). The bundled test application under tests/Application/ already has the bundle, plugin, routes and feature config registered (it's part of this repo), so you do not repeat the Installation steps — make init brings the whole stack up ready to go.

Usage

Develop the plugin in /src; the framework-agnostic core lives in the separate 3brs/enterprise-security-bundle package (its own repository)
See bin/ and Makefile for useful commands

Bootstrapping the dev environment

Spin up the dockerized test application (DB, PHP, schema, assets, fixtures wiring) in one go:

make init

This builds the containers, runs composer install, creates the database, applies the schema with doctrine:schema:update --complete --force and builds the frontend assets. Use make init-tests for the test environment.

In the dev environment the Google, Apple and Microsoft OAuth providers are all swapped for a fake in-memory one, and GeoIP lookup is swapped for a fake that resolves Docker/local addresses so the Active Sessions UI shows a location without a MaxMind database (see tests/Application/config/services_dev.yaml). The social-login buttons therefore work end-to-end without any external credentials. To exercise a real provider flow locally, comment out its FakeOAuthProvider override and fill in your credentials in tests/Application/.env.local.

Testing

After your changes you must ensure that the tests are still passing.

make ci

License

MIT License. See LICENSE for details.

Credits

Developed by 3BRS

3brs / sylius-enterprise-security-plugin

Package info

Security

Statistics

README

Enterprise Security Plugin

3BRS Enterprise Security

Features

Installation

Troubleshooting

`Cannot create union with both "object" and class type` during cache clear / warmup

`Unable to generate an IRI for the item of type ...` on API responses

Development

Usage

Bootstrapping the dev environment

Testing

License

Credits

3brs / sylius-enterprise-security-plugin

Package info

Security

Statistics

README

Enterprise Security Plugin

3BRS Enterprise Security

Features

Installation

Troubleshooting

Cannot create union with both "object" and class type during cache clear / warmup

Unable to generate an IRI for the item of type ... on API responses

Development

Usage

Bootstrapping the dev environment

Testing

License

Credits

`Cannot create union with both "object" and class type` during cache clear / warmup

`Unable to generate an IRI for the item of type ...` on API responses