Admin Auth Laravel Package

Getting Started

This is a thin authentication layer for brackets/admin-ui — it supplies the login/logout/password-reset screens and controllers that the admin panel expects, not a full auth system of its own. Treat it as glue: it wires Laravel's native auth into the admin UI's guard and layout.

Minimal path to a working login screen:

1. composer require brackets/admin-auth (it is normally pulled in automatically by brackets/admin-ui; install it standalone only if you're wiring the admin panel manually).
2. Publish what the package offers and read it before running anything:

   php artisan vendor:publish --provider="Brackets\AdminAuth\AdminAuthServiceProvider"
   

   Look first at config/admin-auth.php — that file tells you which guard, which user model, and which routes the package assumes.
3. Confirm the guard in config/auth.php exists and points at your admin user model. The package does not create a user model for you; it authenticates whatever model admin-auth.gproviders / your guard names.
4. Run any migrations the package ships (usually adding remember_token, password-reset columns, or an activated flag to the admin users table) — check database/migrations in the package vendor directory, don't assume migrate picked them up.
5. Visit /admin/login (or whatever admin-auth.route.prefix resolves to) and log in.

First real use case: you have a stock Laravel app and a brackets/admin-ui panel installed, and you need the panel gated. Get one admin user seeded (php artisan tinker → create a user with a hashed password), confirm login works, then start customizing.

Because the package is small and low-traffic (7 stars, no dependents, last release Oct 2023), spend the first ten minutes reading vendor/brackets/admin-auth/src end to end. It's short, and there is no community knowledge base to fall back on.

Implementation Patterns

Guard-scoped auth, not the default web guard. Keep a dedicated admin guard and provider in config/auth.php and point admin-auth at it. This lets you run a normal front-end web session alongside the panel without the two trampling each other's Auth::user(). Every admin route group should carry middleware => ['web', 'admin']-style protection that names the guard explicitly.

Wrap the package routes rather than editing them. The service provider registers routes for you; if you need different middleware, a different prefix, or a rate limiter, prefer toggling the package's route/prefix config and appending your own group in RouteServiceProvider, instead of overriding controllers. Overriding controllers means you inherit maintenance for every future patch.

Subclass the login controller for behaviour changes. Typical needs — logging successful and failed attempts, blocking deactivated accounts, forcing a redirect target, adding a captcha. Extend the package controller, override login()/authenticated(), and rebind the route to your subclass. This is the cleanest extension point the package offers.

Custom user model via config, not code. If your admins live in a table other than the default, change the provider's model in config/auth.php and make sure that model implements Authenticatable and (if password resets are used) CanResetPassword. The package resolves the model through the provider — don't hardcode it.

Publish views for branding, keep logic out of them. Copy the published blade views into resources/views/vendor/brackets/admin-auth/ and change copy, logo, and layout inheritance to point at your admin-ui master layout. Leave the form field names alone — the controllers validate those exact keys.

Pair with admin-ui middleware. In practice the workflow is: admin-auth handles the session, admin-ui/brackets/admin-ui middleware handles authorization and menu rendering. Ensure the auth middleware runs first in the group, otherwise the UI middleware sees a null user and throws instead of redirecting to login.

Environment-driven config. Guard name, route prefix, and "remember me" toggling belong in config/admin-auth.php reading from env(), so staging can use a /manage prefix without a code change.

Gotchas and Tips

• The 2023 release date is the main risk. Pin the version in composer.json and check it against your Laravel major. If you're on a Laravel released after late 2023, verify the service provider and any Str/Hash/PasswordBroker calls still match current signatures before building on it. Nothing upstream will fix it for you — no dependents means no crowd-testing.
• Guard mismatch is the #1 failure mode. Symptoms: login "succeeds" but immediately redirects back to the login page. That's almost always Auth::attempt() on the web guard while the middleware checks admin. Grep the config for the guard name and confirm it matches everywhere.
• Route cache staleness. If the package registers routes conditionally, php artisan route:cache can freeze a config you later change. Clear cache after touching admin-auth.php config; better, don't cache routes in local.
• Published views shadow vendor updates. After composer update, published blade files stay at the old version and can silently break against changed controller variables. Note the publish date in a comment and diff against vendor on upgrades.
• Password reset needs a broker. The reset flow fails quietly if config/auth.php has no passwords entry for your admin provider. Add one with its own table and expiry — sharing the front-end users' reset table will let front-end tokens reset admin passwords.
• Missing remember_token column. "Remember me" writes to that column; if the package migration didn't run, login succeeds but the checkbox throws or silently no-ops. Check the schema, not the code.
• Throttling and lockout. If login attempts are throttled, a locked-out admin has no self-service path. Know where the limiter is configured and how to clear it (cache:clear if it's the cache-backed limiter) before you go to production.
• Debugging auth failures: log inside attemptToLogin/authenticated with Auth::guard('admin')->check() and the resolved guard name, rather than guessing from redirects. php artisan route:list --path=admin confirms which controller and middleware actually serve the login POST.
• Extension points, in order of safety: config → published views → subclassed controller → event listeners on Laravel's Login/Failed events. Avoid editing anything under vendor/.