| name | auth-and-authorization |
| description | Implement authentication with Laravel Sanctum and authorization with Policies and Gates. Use when setting up login/registration, implementing API token auth, SPA cookie auth, creating policies, defining gates, or building role-based access control. Triggers on authentication, authorization, login, Sanctum, policy, gate, RBAC, permission, or middleware.
|
Authentication & Authorization — Laravel Sanctum + Inertia + React
1. Sanctum SPA Authentication (Inertia Default)
Inertia apps use cookie-based session authentication by default. Sanctum provides the
EnsureFrontendRequestsAreStateful middleware that enables this for same-domain SPAs.
Configuration
return [
'stateful' => explode(',', env(
'SANCTUM_STATEFUL_DOMAINS',
'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1'
)),
'guard' => ['web'],
'expiration' => null,
];
Middleware Setup (Laravel 11)
use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;
return Application::configure(basePath: dirname(__DIR__))
->withMiddleware(function (Middleware $middleware) {
$middleware->statefulApi();
$middleware->web(append: [
\App\Http\Middleware\HandleInertiaRequests::class,
]);
})
->create();
Authentication Controller
namespace App\Http\Controllers\Auth;
use App\Http\Controllers\Controller;
use App\Http\Requests\Auth\LoginRequest;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Inertia\Inertia;
use Inertia\Response;
class AuthenticatedSessionController extends Controller
{
public function create(): Response
{
return Inertia::render('Auth/Login', [
'canResetPassword' => route('password.request') !== null,
=> (),
]);
}
{
->();
->()->();
()->(());
}
{
::()->();
->()->();
->()->();
();
}
}
Login Request with Rate Limiting
namespace App\Http\Requests\Auth;
use Illuminate\Auth\Events\Lockout;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\Str;
use Illuminate\Validation\ValidationException;
class LoginRequest extends FormRequest
{
public function rules(): array
{
return [
'email' => ['required', 'string', 'email'],
'password' => ['required', 'string'],
];
}
public function ():
{
->();
(! ::(->(, ), ->())) {
::(->());
::([
=> (),
]);
}
::(->());
}
{
(! ::(->(), )) {
;
}
( ());
= ::(->());
::([
=> (, [
=> ,
=> ( / ),
]),
]);
}
{
::(::(->())..->());
}
}
React Login Page
import { useForm, Head } from '@inertiajs/react';
import { FormEventHandler } from 'react';
interface LoginProps {
canResetPassword: boolean;
status?: string;
}
export default function Login({ canResetPassword, status }: LoginProps) {
const { data, setData, post, processing, errors, reset } = useForm({
email: '',
password: '',
remember: false,
});
const submit: FormEventHandler = (e) => {
e.preventDefault();
post(route('login'), {
onFinish: () => reset('password'),
});
};
return (
<>
<Head title="Log in" />
{status && <div className=>{status}}
Email
setData('email', e.target.value)}
autoFocus
/>
{errors.email && {errors.email}}
Password
setData('password', e.target.value)}
/>
{errors.password && {errors.password}}
setData('remember', e.target.checked)}
/>
Remember me
Log in
);
}
2. Sanctum API Token Authentication
Use token-based auth for mobile apps or third-party API consumers that cannot share cookies.
Setup
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, HasFactory, Notifiable;
}
Token Creation with Abilities
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
class TokenController extends Controller
{
public function store(Request $request): JsonResponse
{
$request->validate([
'email' => 'required|email',
'password' => 'required',
'device_name' => 'required|string',
'abilities' => 'sometimes|array',
]);
$user = User::where('email', $request->email)->first();
if (! $user || ! Hash::check($request->password, ->password)) {
::([
=> [],
]);
}
= ->(, []);
= ->(->device_name, );
()->([
=> ->plainTextToken,
=> ,
]);
}
{
->()->()->();
()->([ => ]);
}
}
Protecting API Routes
Route::middleware('auth:sanctum')->group(function () {
Route::get('/user', fn (Request $request) => $request->user());
Route::apiResource('projects', ProjectController::class);
});
public function update(Request $request, Project $project)
{
if ($request->user()->tokenCan('project:update')) {
}
abort(403);
}
3. Policies
Policies encapsulate authorization logic for a specific model. Laravel auto-discovers policies
when they follow the App\Policies\{Model}Policy convention.
Full CRUD Policy Template
namespace App\Policies;
use App\Enums\Role;
use App\Models\Project;
use App\Models\User;
use Illuminate\Auth\Access\HandlesAuthorization;
class ProjectPolicy
{
use HandlesAuthorization;
public function before(User $user, string $ability): ?bool
{
if ($user->role === Role::SuperAdmin) {
return true;
}
return null;
}
public function viewAny(User $user): bool
{
return true;
}
{
->id === ->user_id
|| ->team->users->();
}
{
->role !== ::;
}
{
->id === ->user_id;
}
{
->id === ->user_id;
}
{
->id === ->user_id;
}
{
->role === :: && ->id === ->user_id;
}
}
Using Policies in Controllers
public function update(UpdateProjectRequest $request, Project $project)
{
$this->authorize('update', $project);
$project->update($request->validated());
return back()->with('success', 'Project updated.');
}
class ProjectController extends Controller
{
public function __construct()
{
$this->authorizeResource(Project::class, 'project');
}
}
Generating a Policy
php artisan make:policy ProjectPolicy --model=Project
4. Gates
Gates are closures that determine if a user can perform a given action. Use gates for actions
that are not tied to a specific model (e.g., "access admin panel").
use Illuminate\Support\Facades\Gate;
public function boot(): void
{
Gate::define('access-admin', function (User $user): bool {
return in_array($user->role, [Role::Admin, Role::SuperAdmin]);
});
Gate::define('view-reports', function (User $user): bool {
return $user->hasPermission('reports.view');
});
}
Using Gates
if (Gate::allows('access-admin')) {
}
Gate::authorize('access-admin');
Route::get('/admin', AdminController::class)->middleware('can:access-admin');
When to Use Gates vs Policies
| Use Case | Mechanism |
|---|
| Model-level CRUD permissions | Policy |
| Non-model actions (access panel, export data) | Gate |
| Complex resource ownership rules | Policy |
| Simple boolean checks | Gate |
5. Role-Based Access Control (RBAC)
Enum-Based Roles
namespace App\Enums;
enum Role: string
{
case SuperAdmin = 'super_admin';
case Admin = 'admin';
case Editor = 'editor';
case Viewer = 'viewer';
public function label(): string
{
return match ($this) {
self::SuperAdmin => 'Super Admin',
self::Admin => 'Admin',
self::Editor => 'Editor',
self::Viewer => 'Viewer',
};
}
public function level(): int
{
return match ($this) {
self::Viewer => 0,
self::Editor => ,
:: => ,
:: => ,
};
}
{
->() >= ->();
}
}
Spatie Laravel Permission Integration
composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan migrate
use Spatie\Permission\Traits\HasRoles;
class User extends Authenticatable
{
use HasApiTokens, HasFactory, HasRoles, Notifiable;
}
$adminRole = Role::create(['name' => 'admin']);
$adminRole->givePermissionTo([
'projects.create', 'projects.edit', 'projects.delete',
'users.manage',
]);
$user->assignRole('admin');
$user->hasPermissionTo('projects.create');
Sharing Permissions to Inertia Frontend
public function share(Request $request): array
{
return [
...parent::share($request),
'auth' => [
'user' => $request->user() ? [
'id' => $request->user()->id,
'name' => $request->user()->name,
'email' => $request->user()->email,
'role' => $request->user()->role,
'permissions' => $request->user()->getAllPermissions()
->pluck('name')
->toArray(),
] : null,
],
];
}
Frontend Permission Checking
import { usePage } from '@inertiajs/react';
interface AuthUser {
id: number;
name: string;
email: string;
role: string;
permissions: string[];
}
interface PageProps {
auth: {
user: AuthUser | null;
};
}
export function usePermission() {
const { auth } = usePage<PageProps>().props;
const can = (permission: string): boolean => {
return auth.user?.permissions.includes(permission) ?? false;
};
const hasRole = (role: string): boolean => {
return auth.user?.role === role;
};
const hasAnyRole = (...roles: string[]): boolean => {
roles.(auth.?. ?? );
};
{ can, hasRole, hasAnyRole, : auth. };
}
() {
{ can } = ();
(
);
}
6. Frontend Auth Patterns
Accessing Auth Data in Inertia
export interface User {
id: number;
name: string;
email: string;
email_verified_at?: string;
role: string;
permissions: string[];
}
export type PageProps<T extends Record<string, unknown> = Record<string, unknown>> = T & {
auth: {
user: User;
};
flash: {
success?: string;
error?: string;
};
};
Protecting Routes with Middleware
Route::middleware(['auth', 'verified'])->group(function () {
Route::get('/dashboard', [DashboardController::class, 'index'])->name('dashboard');
Route::resource('projects', ProjectController::class);
});
Route::middleware(['auth', 'role:admin'])->prefix('admin')->group(function () {
Route::get('/users', [UserController::class, 'index']);
});
Custom Role Middleware
namespace App\Http\Middleware;
use App\Enums\Role;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class EnsureUserHasRole
{
public function handle(Request $request, Closure $next, string ...$roles): Response
{
$userRole = $request->user()?->role;
if (! $userRole || ! collect($roles)->contains(fn ($r) => $userRole === Role::from($r))) {
abort(403, 'Insufficient role.');
}
return $next($request);
}
}
7. Password Reset & Email Verification
Using Laravel Fortify (Headless)
composer require laravel/fortify
php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"
use Laravel\Fortify\Fortify;
use Inertia\Inertia;
public function boot(): void
{
Fortify::loginView(fn () => Inertia::render('Auth/Login'));
Fortify::registerView(fn () => Inertia::render('Auth/Register'));
Fortify::requestPasswordResetLinkView(fn () => Inertia::render('Auth/ForgotPassword'));
Fortify::resetPasswordView(fn ($request) => Inertia::render('Auth/ResetPassword', [
'email' => $request->email,
'token' => $request->route('token'),
]));
Fortify::verifyEmailView(fn () => Inertia::render('Auth/VerifyEmail'));
}
Email Verification
class User extends Authenticatable implements MustVerifyEmail
{
}
Route::middleware(['auth', 'verified'])->group(function () {
});
8. Testing Authentication & Authorization
Testing Login Flow
use App\Models\User;
it('renders the login page', function () {
$this->get('/login')
->assertOk()
->assertInertia(fn ($page) => $page->component('Auth/Login'));
});
it('authenticates a user with valid credentials', function () {
$user = User::factory()->create();
$this->post('/login', [
'email' => $user->email,
'password' => 'password',
])->assertRedirect('/dashboard');
$this->assertAuthenticated();
});
it('rejects invalid credentials', function () {
$user = User::factory()->create();
$this->post('/login', [
'email' => $user->email,
'password' => 'wrong-password',
]);
->();
});
Testing Policies
use App\Enums\Role;
use App\Models\Project;
use App\Models\User;
use App\Policies\ProjectPolicy;
it('allows the owner to update a project', function () {
$user = User::factory()->create();
$project = Project::factory()->for($user)->create();
$policy = new ProjectPolicy();
expect($policy->update($user, $project))->toBeTrue();
});
it('denies non-owners from updating a project', function () {
$owner = User::factory()->create();
$other = User::factory()->create();
$project = Project::()->()->();
= ();
(->(, ))->();
});
(, function () {
= ::()->([ => ::]);
= ::()->();
= ();
(->(, ))->();
});
Testing Middleware Authorization
it('prevents unauthorized access to admin routes', function () {
$user = User::factory()->create(['role' => Role::Viewer]);
$this->actingAs($user)
->get('/admin/users')
->assertForbidden();
});
it('allows admins to access admin routes', function () {
$admin = User::factory()->create(['role' => Role::Admin]);
$this->actingAs($admin)
->get('/admin/users')
->assertOk();
});
