Admin Security Bundle Laravel Package

Getting Started

This bundle is not standalone — it only makes sense on top of a working fsi-open/admin-bundle setup. Treat "install the admin bundle, then add security" as the required order.

1. Install dependencies — you need fsi/admin-bundle configured and, in practice, friendsofsymfony/user-bundle (FOSUserBundle), since this package layers authentication/authorization on top of it:

   composer require fsi/admin-security-bundle
   

2. Register the bundle in AppKernel.php (or config/bundles.php on newer Symfony) after FSiAdminBundle and FOSUserBundle.
3. Point the bundle at your user entity in config.yml — the package expects a user class implementing its admin-user interface (usually by extending the shipped AdminUser entity):

   fsi_admin_security:
       user_class: AppBundle\Entity\User
   

4. Wire the firewall in security.yml for the admin prefix — a form_login firewall, a logout, and an access_control rule forcing ROLE_ADMIN on /admin:

   security:
       firewalls:
           admin:
               pattern: ^/admin
               form_login:   { login_path: /admin/login, check_path: /admin/login_check }
               logout:       { path: /admin/logout, target: /admin/login }
               anonymous:    ~
       access_control:
           - { path: ^/admin/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
           - { path: ^/admin,       roles: ROLE_ADMIN }
   

Where to look first: the bundle's Resources/config (service wiring and the fsi_admin_security config tree) and its Entity/AdminUser base class — those two tell you exactly what the package expects from your app. Then look at the shipped admin elements (e.g. ChangePassword, admin-user management) to see how it plugs into the admin panel.

First use case: log in at /admin/login, land on the admin dashboard, and add the ChangePassword element so the logged-in admin can rotate their password without an external tool. That single flow exercises the whole stack — user provider, firewall, voter, and admin element registration.

Implementation Patterns

• Extend the provided user entity rather than starting from scratch. Subclass the bundle's AdminUser (or implement its interface on your existing FOSUser entity) so the bundle's voters and elements can rely on a stable contract. Add your domain fields on the subclass and keep the roles column.
• Drive panel visibility from roles. Because authorization is role-based, the usual pattern is: define ROLE_ADMIN, ROLE_SUPER_ADMIN, and narrower roles per admin section, set them on the user entity, and let the firewall plus the bundle's voter hide/deny elements the user shouldn't see. Put the hierarchy in security.yml so ROLE_SUPER_ADMIN inherits everything.
• Register admin elements normally. The security elements (ChangePassword, admin-user CRUD) are registered like any other fsi/admin-bundle element — add them to the admin element list in your config/extension. The admin-user element becomes your day-to-day "manage other admins" screen; the change-password element is the self-service screen.
• Custom voters for fine-grained control. When roles aren't granular enough (e.g. "editors can edit articles they own"), write a voter and check isGranted() in your admin element's isAllowed/controller logic. The bundle's own voter is a good template — copy its supportsClass/supportsAttribute shape.
• Password reset flow. Configure the from-address and email template in fsi_admin_security and expose the reset routes; the bundle handles token generation and mail. Override the template only after the default flow works end-to-end.
• Keep authentication and authorization separate. FOSUserBundle handles credentials/sessions; this bundle handles "is this user allowed into the admin panel and which parts." Don't conflate the two when debugging — check the profiler's Security panel to see which layer rejected the request.

Gotchas and Tips

• It's a small, low-traffic package (4 stars, no dependents). Documentation is thin and examples are few — budget time to read the source, especially the DI extension and the voter. Don't expect Stack Overflow answers.
• Version lock-in is the biggest risk. This bundle is built for the Symfony 2.8/3.x + FOSUserBundle era. On Symfony 4+ the FOSUser dependency is itself deprecated; on Symfony 5/6 expect to either pin old versions or port the firewall/user-provider glue yourself. Check composer why-not before committing.
• user_class must match exactly. A typo or a class that doesn't implement the expected interface produces confusing container/voter errors rather than a clear "wrong class" message.
• Forgetting access_control is the classic failure: the firewall authenticates fine but every admin URL is anonymously reachable. Add the catch-all ^/admin → ROLE_ADMIN rule after the login exception.
• 403 with a valid login usually means the role hierarchy or voter, not the password. Use debug:router and the profiler's security panel; check that the user actually carries ROLE_ADMIN (roles are often stored serialized — a stale session after a role change needs re-login or a session invalidation).
• Doctrine mapping for the base entity. If you extend AdminUser, make sure your entity is the mapped one and that the bundle isn't trying to map its own base class; use the standard "extend + override mapping" pattern.
• Password encoding config drift. The encoder in security.yml must match how users were created; a bcrypt/plaintext mismatch manifests as "always invalid credentials" with no other error.
• Extension points to reach for first: a custom voter, a custom user class, an overridden password-reset email template, and (if needed) overriding the bundle's routes/controllers via a compiler pass. Prefer these over forking — the package is small enough that a fork is tempting but hard to keep in sync.