Auth Bundle Laravel Package

Getting Started

First, confirm the stack match. Despite the task framing, this is not a Laravel package. It is a Symfony bundle (superadmin/auth-bundle) built around API Platform and JWT — in practice almost certainly leaning on lexik/jwt-authentication-bundle and api-platform/core. There is no service provider, no config/auth.php, no Auth::guard(). If your day job is Laravel, the honest assessment is that this package is only indirectly useful: read it as a reference implementation for wiring API Platform + JWT, and port the ideas (firewall config, token issuance, role checks in security expressions) rather than installing it.

If you are on Symfony, the minimal path is:

1. composer require superadmin/auth-bundle — but before that, open the repo's composer.json and read the require block. That is the single most informative file here: it tells you the PHP version floor, the Symfony major version, and whether API Platform 3 vs 2 is assumed. With 0 stars and 0 dependents, version constraints are your main compatibility risk.
2. Register the bundle in config/bundles.php (confirm the class name in src/ — it typically ends in Bundle and lives under a SuperAdmin\Auth\... namespace).
3. Ensure the JWT prerequisites exist: lexik/jwt-authentication-bundle, generated keypair (bin/console lexik:jwt:generate-keypair), and JWT_PASSPHRASE in .env.
4. Wire the firewall in config/packages/security.yaml — the bundle's job is normally to expose a firewall/provider preset or a DI extension that configures the token authenticator.
5. Run bin/console config:dump-reference <alias> to discover the actual config tree. The extension alias is not documented here; bin/console debug:config and config:dump-reference are how you learn it without a README.

Where to look first, in order: composer.json → README (may not exist) → src/DependencyInjection/*Extension.php (the real config surface) → src/Security/ or src/Authenticator/ (the token flow) → Resources/config/services.* → tests/ (if present, this doubles as usage docs).

First use case: protect a single API Platform resource. Create a user, hit the login endpoint to get a JWT, then call a resource operation annotated with security: "is_granted('ROLE_USER')" and confirm the token is accepted. Do this before anything else — it validates the whole chain (keys, firewall, provider, encoder) in one pass.

Implementation Patterns

Firewall-scoped, not global. The pattern that works is registering a stateless firewall for the API prefix and letting the bundle's authenticator handle Authorization: Bearer. Keep stateless: true; mixing session auth into an API Platform app is where most of the pain comes from.

Two-tier security config. Put coarse rules in security.yaml (access_control on path prefixes) and fine-grained rules on API Platform operations (security attribute on the operation). Trying to express resource-level ownership rules in the firewall leads to unmaintainable regex.

Token issuance as a service, not a controller concern. If the bundle exposes a token manager/service, inject it into your own login controller rather than copying its logic. If it does not, treat the bundle as the validator and issue tokens yourself via Lexik's JWTTokenManagerInterface. This keeps you able to swap the bundle out later — worth doing given the maintenance signal.

User provider integration. The bundle will assume a user class. Subclass or extend it rather than fighting it, and implement UserInterface + PasswordAuthenticatedUserInterface on your entity. Keep the password encoder configured explicitly (auto is fine, bcrypt/argon2id if you need determinism across environments).

Test with a real token, not mocks. In ApiTestCase, authenticate by requesting a token in setUp and storing it, then attach it via the client's default headers. Mocking the authenticator tests nothing you care about.

Environment parity for keys. Generate the keypair in CI and in local setup scripts. A JWT_PASSPHRASE that exists in .env but not in .env.test is a classic half-day debugging session.

Gotchas and Tips

• It is not a Laravel package. No facade, no publishable config, no php artisan. If you found this while searching for Laravel auth bundles, stop here.
• Zero social proof means you own the bugs. 0 stars, 0 dependents, score 0. Pin the exact version in composer.json ("superadmin/auth-bundle": "0.x.y"), vendor it or fork it into your VCS, and read the diff before every update. Do not rely on GitHub issues for answers.
• The bundle may be a thin wrapper. Very likely the substantive work is done by Lexik and API Platform, with this bundle providing a preset firewall + a user entity. If so, you can replicate it in ~40 lines of security.yaml and skip the dependency entirely. Check src/ size first — if it is a handful of files, inline the config.
• Firewall ordering is load-bearing. Firewalls match top-down in security.yaml. A dev firewall or a main firewall above your API firewall will silently swallow requests and produce 401s that look like token failures.
• Keypair permissions. JWT private keys must be readable by the PHP-FPM user. A key generated as root with 0600 fails at runtime with a misleading "signature could not be verified" or a 500 on login.
• Clock skew and TTL. lexik defaults are short. If you see intermittent 401s in long-running frontend sessions, check token_ttl and whether refresh tokens are configured before blaming the bundle.
• Debugging sequence: bin/console debug:config <alias> (is my config actually merged?) → bin/console debug:firewall <name> (which firewall matched? which authenticator?) → bin/console debug:router (is my login route registered?) → check var/log/ for JWT entries. That ordering resolves most integration failures.
• Extension points are the escape hatch. If the DI extension is not flexible enough, override the service definition in config/services.yaml after the bundle's — Symfony's container lets you replace any service it registers. Also check for a compiler pass; a *Pass.php in src/DependencyInjection/Compiler/ usually signals an intended customization seam.
• CORS before you debug auth. API Platform's CORS handler and the bundle's error responses interact badly; a preflight 401 often looks like a credential problem. Configure nelmio/cors-bundle (or API Platform's CORS) first.
• Missing tests are a red flag, not a blocker. With no dependents, assume no one has exercised the edge paths. Budget time for one end-to-end integration test of your own (login → token → protected resource → expiry) and keep it in CI — it is your only regression safety net for future bundle updates.