Security Guard Laravel Package

Getting Started

Start by installing symfony/security-guard via Composer (note: deprecated and archived; consider alternatives like custom authenticators in Symfony 5.3+ with AbstractPreLoadAuthenticator). In legacy apps ( Symfony 3.x–4.x), add the package and create a class implementing GuardAuthenticatorInterface. Implement key methods: getCredentials(), getUser(), checkCredentials(), and optionally onAuthenticationSuccess()/onAuthenticationFailure().

First use case: add custom API key authentication to a stateless firewall. Define a guard that extracts the X-API-Key header, looks up the user by key, and validates it — all within a single, testable class.

Implementation Patterns

• Separate concerns: Each authenticator handles one login method (e.g., ApiKeyAuthenticator, OAuthAuthenticator). Keeps logic modular and reusable.
• Stateless flows: For APIs, omit supports() checks on session and return early from onAuthenticationSuccess() to avoid redirects.
• Use remember_me support: Implement supportsRememberMe() and integrate with the remember_me firewalls to persist tokens.
• Hybrid handling: Chain multiple guards in one firewall (via guard config) to try multiple auth methods in order (e.g., API key → Bearer token → form login).
• Unit test first: Write tests for checkCredentials() with mock request/test tokens before wiring into controllers.

Gotchas and Tips

• ⚠️ Archived & deprecated: Use only in legacy Symfony <5.3 apps. New projects should use AbstractPreLoadAuthenticator (no security-guard dependency) with the “authenticator-based” security system.
• supports() must be cheap: This method runs on every request for matching firewalls — avoid database calls or heavy logic here.
• Order matters in guard config: Guards are tried sequentially; place most specific (e.g., API key) before fallback (e.g., form login).
• Debug with debug:firewall: Run php bin/console debug:firewall to verify guard integration and order.
• Remember-me pitfalls: If using remember_me, ensure remember_me.secret is set, and implement supportsRememberMe() correctly. Misconfigurations silently break persistence.
• Return null from onAuthenticationSuccess() for stateless APIs to skip redirect behavior — returning a Response overrides default behavior.