Laravel's authorization system lets you implement fine-grained access control in your applications. The built-in features cover most cases, but some projects need more advanced role-based access control (RBAC), which third-party packages like Spatie's Laravel Permission provide.

In this guide, we'll walk through the process of setting up fine-grained authorization in a Laravel application using Lakebase Postgres. We'll start with Laravel's native authorization features, including Gates and Policies, and then add Spatie's Laravel Permission package for roles and permissions.

Prerequisites

Before we begin, make sure you have the following:

  • PHP 8.1 or higher installed on your system
  • Composer for managing PHP dependencies
  • A Neon account for database hosting
  • Basic knowledge of Laravel and its authentication system

Setting up the project

Let's start by creating a new Laravel project and configuring it to use Lakebase Postgres.

Creating a new Laravel project

Open your terminal and run the following command to create a new Laravel project:

composer create-project laravel/laravel laravel-auth-demo
cd laravel-auth-demo

This will create a new Laravel project in a directory named laravel-auth-demo and navigate you into the project directory.

Connecting to your database on Neon

Update your .env file with the details from your Neon connection string. Click Connect in the Neon Console nav to find them:

DB_CONNECTION=pgsql
DB_HOST=your-neon-hostname.neon.tech
DB_PORT=5432
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

Replace the placeholders with your own values.

Laravel's authorization system

Laravel's authorization system is built on two main concepts: Gates and Policies.

  • Gates are Closure-based authorization checks. They suit simple checks that don't relate to a specific model or resource, and you can use them anywhere in your application.

  • Policies are classes that organize authorization logic around a particular model or resource. They're useful when you have multiple authorization checks related to a single model.

For fine-grained authorization, we'll focus on Policies, which group the authorization logic for each model in one place.

Gates are still useful for broader, application-wide permissions that aren't tied to a specific model. You might use Gates for actions like "access admin dashboard" or "manage site settings".

Laravel's authorization system is integrated with its authentication system, so you can check a user's permissions in your controllers, views, and database queries.

Implementing fine-grained authorization

Let's implement a fine-grained authorization system for a blog application where users can create, read, update, and delete posts.

Setting up the Post model and migration

For this guide, we'll create a Post model with basic fields like title, content, and is_published. We'll also associate each post with a user.

First, let's create a Post model with its migration:

php artisan make:model Post -m

Update the migration file in database/migrations to define the structure of our posts table:

public function up()
{
    Schema::create('posts', function (Blueprint $table) {
        $table->id();
        $table->foreignId('user_id')->constrained()->onDelete('cascade');
        $table->string('title');
        $table->text('content');
        $table->boolean('is_published')->default(false);
        $table->timestamps();
    });
}

Run the migration:

php artisan migrate

This will create a posts table in your Lakebase Postgres database.

Creating a policy for posts

Now, let's create a policy for the Post model:

php artisan make:policy PostPolicy --model=Post

This command creates a new policy class in app/Policies/PostPolicy.php. Let's update it with our authorization logic:

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\HandlesAuthorization;

class PostPolicy
{
    use HandlesAuthorization;

    public function viewAny(User $user)
    {
        return true; // Allow all users to view the list of posts
    }

    public function view(User $user, Post $post)
    {
        return true; // Allow all users to view individual posts
    }

    public function create(User $user)
    {
        return true; // Allow all authenticated users to create posts
    }

    public function update(User $user, Post $post)
    {
        return $user->id === $post->user_id; // Allow only the author to update the post
    }

    public function delete(User $user, Post $post)
    {
        return $user->id === $post->user_id; // Allow only the author to delete the post
    }

    public function publish(User $user, Post $post)
    {
        // Allow only the author or an admin to publish the post
        return $user->id === $post->user_id || $user->is_admin;
    }
}

Rundown of the PostPolicy class:

  1. viewAny method: This allows all users to view the list of posts. This could be useful for a public blog where anyone can see the list of available posts.

  2. view method: Similar to viewAny, this allows all users to view individual posts. Again, this is suitable for a public blog where post content is accessible to everyone.

  3. create method: This permits all authenticated users to create posts. It assumes that any logged-in user should be able to write a post.

  4. update method: This method only allows the author of the post to update it. It compares the ID of the current user with the user ID associated with the post.

  5. delete method: Similar to update, this method restricts deletion to the author of the post. This ensures that users can only delete their own posts.

  6. publish method: This method allows either the author of the post or an admin user to publish the post. This is useful for blogs where posts might need approval before being made public.

Each method in this policy corresponds to a specific action that can be performed on a Post model. The methods return boolean values: true if the action is allowed, and false if it's not.

This policy controls each post-related action, so users can only perform actions they're authorized to do.

Registering the policy

By default, Laravel 11.x and later versions automatically discover policies. However, if you're using an older version, you might need to manually register the policy in the AuthServiceProvider.

To automatically discover policies, your policies should be in the app/Policies directory and follow the naming convention of ModelNamePolicy. Laravel will automatically associate the policy with the corresponding model.

To manually register the policy, add the following line to the boot method of your AuthServiceProvider:

use App\Models\Post;
use App\Policies\PostPolicy;

public function boot(): void
{
    Gate::policy(Post::class, PostPolicy::class);
}

This line tells Laravel to use the PostPolicy class for authorization checks related to the Post model.

Implementing role-based access control

To support our is_admin flag and implement basic role-based access control, let's update our users table.

To do that, create a new migration to add the is_admin column:

php artisan make:migration add_is_admin_to_users_table

Update the migration file:

public function up()
{
    Schema::table('users', function (Blueprint $table) {
        $table->boolean('is_admin')->default(false);
    });
}

public function down()
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn('is_admin');
    });
}

Run the migration to add the is_admin column to the users table:

php artisan migrate

This column will allow us to differentiate between regular users and administrators.

Using authorization in controllers

Now that we have our policy set up, let's use it in a controller. Create a new PostController:

php artisan make:controller PostController --resource

Update the PostController with authorization checks:

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Post::class, 'post');
    }

    public function index()
    {
        $posts = Post::all();
        return view('posts.index', compact('posts'));
    }

    public function show(Post $post)
    {
        return view('posts.show', compact('post'));
    }

    public function create()
    {
        return view('posts.create');
    }

    public function store(Request $request)
    {
        $validatedData = $request->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);

        $post = auth()->user()->posts()->create($validatedData);

        return redirect()->route('posts.show', $post);
    }

    public function edit(Post $post)
    {
        return view('posts.edit', compact('post'));
    }

    public function update(Request $request, Post $post)
    {
        $validatedData = $request->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);

        $post->update($validatedData);

        return redirect()->route('posts.show', $post);
    }

    public function destroy(Post $post)
    {
        $post->delete();

        return redirect()->route('posts.index');
    }

    public function publish(Post $post)
    {
        $this->authorize('publish', $post);

        $post->update(['is_published' => true]);

        return redirect()->route('posts.show', $post);
    }
}

The __construct method uses the authorizeResource method to automatically authorize resource controller methods. We've also added a publish method with a manual authorization check.

Alternatively, you can use the authorize method within each controller method to perform authorization checks manually. This method takes the name of the policy method to call and the model to authorize against:

$this->authorize('publish', $post);

This line checks if the current user is authorized to publish the post. If not, Laravel will throw an AuthorizationException preventing the action from being executed.

Using authorization in views

In your Blade views, you can use the @can directive to conditionally show or hide elements based on the user's permissions. For example, in resources/views/posts/show.blade.php:

<h1>{{ $post->title }}</h1>
<p>{{ $post->content }}</p>

@can('update', $post)
<a href="{{ route('posts.edit', $post) }}">Edit Post</a>
@endcan @can('delete', $post)
<form action="{{ route('posts.destroy', $post) }}" method="POST">
  @csrf @method('DELETE')
  <button type="submit">Delete Post</button>
</form>
@endcan @can('publish', $post) @if(!$post->is_published)
<form action="{{ route('posts.publish', $post) }}" method="POST">
  @csrf
  <button type="submit">Publish Post</button>
</form>
@endif @endcan

Rundown of the Blade view:

  1. The view starts by displaying the post's title and content, which are accessible to all users as per our policy.

  2. @can('update', $post) directive: This checks if the current user is authorized to update the post. If true, it displays an "Edit Post" link. This corresponds to the update method in our PostPolicy.

  3. @can('delete', $post) directive: Similar to the update check, this verifies if the user can delete the post. If authorized, it shows a delete form with a submit button. This uses the delete method from our policy.

  4. @can('publish', $post) directive: This checks if the user can publish the post, corresponding to the publish method in our policy.

  5. Inside the publish check, there's an additional @if(!$post->is_published) condition. This ensures the publish button only appears if the post isn't already published.

  6. Each form includes a @csrf directive for CSRF protection, which is a security feature in Laravel to prevent cross-site request forgery attacks.

  7. The delete form also includes @method('DELETE'), which is Laravel's way of spoofing HTTP methods that aren't supported by HTML forms (like DELETE, PUT, PATCH).

With these directives, each user only sees the actions their role allows.

Integrating Spatie's Laravel Permission for advanced RBAC

Laravel's built-in authorization system is a good foundation, but you might need more complex role and permission structures. Spatie's Laravel Permission package adds roles and permissions stored in your database.

Installing Spatie Laravel Permission

First, let's install the package using Composer:

composer require spatie/laravel-permission

After installation, publish the package's configuration and migration files:

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

This command will create a config/permission.php file and a migration file in your database/migrations directory.

Run the migrations to create the necessary tables in your Lakebase Postgres database:

php artisan migrate

This will create the permissions, roles, and model_has_roles tables in your database.

Configuring the package

The package's configuration file is located at config/permission.php. The default configuration works for most use cases, but you can customize it based on your needs. For example, you can change the table names or add a cache expiration time.

Setting up roles and permissions

Let's create some roles and permissions for our blog application. We'll do this in a seeder for easy setup and testing.

Create a new seeder:

php artisan make:seeder RolesAndPermissionsSeeder

Update the seeder file (database/seeders/RolesAndPermissionsSeeder.php):

<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

class RolesAndPermissionsSeeder extends Seeder
{
    public function run()
    {
        // Reset cached roles and permissions
        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();

        // Create permissions
        Permission::create(['name' => 'view posts']);
        Permission::create(['name' => 'create posts']);
        Permission::create(['name' => 'edit posts']);
        Permission::create(['name' => 'delete posts']);
        Permission::create(['name' => 'publish posts']);
        Permission::create(['name' => 'unpublish posts']);

        // Create roles and assign permissions
        $role = Role::create(['name' => 'writer']);
        $role->givePermissionTo(['view posts', 'create posts', 'edit posts', 'delete posts']);

        $role = Role::create(['name' => 'editor']);
        $role->givePermissionTo(['view posts', 'create posts', 'edit posts', 'delete posts', 'publish posts', 'unpublish posts']);

        $role = Role::create(['name' => 'admin']);
        $role->givePermissionTo(Permission::all());
    }
}

Update your DatabaseSeeder.php to include this new seeder:

public function run()
{
    $this->call([
        RolesAndPermissionsSeeder::class,
    ]);
}

Run the seeder:

php artisan db:seed

This will create roles for writer, editor, and admin, along with permissions for viewing, creating, editing, deleting, publishing, and unpublishing posts.

Updating the User model

To use the package, your User model should use the HasRoles trait. Update your app/Models/User.php:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasFactory, Notifiable, HasRoles;

    // ...
}

This trait provides methods for assigning and checking roles and permissions for users in your application.

Implementing RBAC in controllers

Now, let's update our PostController to use the new permissions:

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function __construct()
    {
        $this->middleware('permission:view posts')->only('index', 'show');
        $this->middleware('permission:create posts')->only('create', 'store');
        $this->middleware('permission:edit posts')->only('edit', 'update');
        $this->middleware('permission:delete posts')->only('destroy');
        $this->middleware('permission:publish posts')->only('publish');
    }

    // ... other methods remain the same

    public function publish(Post $post)
    {
        $post->update(['is_published' => true]);
        return redirect()->route('posts.show', $post);
    }
}

The __construct method now uses middleware to check permissions for each controller action. This ensures that only users with the appropriate permissions can access the corresponding methods.

Using RBAC in Blade templates

You can use the package's directives in your Blade templates to show or hide elements based on the user's roles and permissions:

@can('edit posts')
<a href="{{ route('posts.edit', $post) }}">Edit Post</a>
@endcan @role('admin')
<a href="{{ route('admin.dashboard') }}">Admin Dashboard</a>
@endrole @hasanyrole('writer|editor')
<a href="{{ route('posts.create') }}">Create New Post</a>
@endhasanyrole

You can also use the @canany directive to check if the user has any of the specified permissions:

@canany(['edit posts', 'delete posts'])
<form action="{{ route('posts.destroy', $post) }}" method="POST">
  @csrf @method('DELETE')
  <button type="submit">Delete Post</button>
</form>
@endcanany

Dynamic role and permission assignment

Besides seeding roles and permissions, you can also assign roles and permissions dynamically based on user actions. For example, you might assign the writer role to users who have published a certain number of posts.

Here's an example of how you can assign roles and permissions dynamically in your controllers:

public function assignRole(User $user, Request $request)
{
    $validatedData = $request->validate([
        'role' => 'required|exists:roles,name',
    ]);

    $user->assignRole($validatedData['role']);

    return back()->with('success', 'Role assigned successfully');
}

public function revokeRole(User $user, Request $request)
{
    $validatedData = $request->validate([
        'role' => 'required|exists:roles,name',
    ]);

    $user->removeRole($validatedData['role']);

    return back()->with('success', 'Role revoked successfully');
}

Besides the removeRole and assignRole methods, the package provides other methods for managing roles and permissions, such as syncRoles, givePermissionTo, and revokePermissionTo for more advanced use cases.

Optimizing RBAC performance

When working with RBAC, especially in larger applications, you might encounter performance issues due to the increased number of database queries.

Here are some tips to optimize performance when using Spatie Laravel Permission with Postgres on Neon:

  1. Caching: Enable caching in the package's configuration to reduce database queries:

    // In config/permission.php
'cache' => [
    'expiration_time' => \DateInterval::createFromDateString('24 hours'),
    'key' => 'spatie.permission.cache',
    'model_key' => 'name',
    'store' => 'default',
],

  2. Eager loading: When fetching users with their roles and permissions, use eager loading:

    $users = User::with('roles', 'permissions')->get();

  3. Indexing: Ensure that the model_id and model_type columns in the model_has_roles and model_has_permissions tables are properly indexed. For more information on indexing, refer to the Postgres index types documentation.

  4. Minimize permission checks: Instead of checking individual permissions, consider using roles or permission groups to reduce the number of checks you do on each request.

  5. Use database-level permissions: For very large-scale applications, consider implementing some permissions at the database level using Postgres's role-based access control features.

Conclusion

You built authorization for a Laravel blog on Lakebase Postgres with Policies and Gates, then added roles and permissions with Spatie's Laravel Permission package.

As a next step, write feature tests for each policy method and role so changes to your authorization rules don't break access.

Additional resources