Common pitfalls to watch out for when integrating Laravel Sanctum with a Vue 3 Frontend

When implementing a cookie based authentication in your Vue 3 Single Page Application with Laravel Sanctum, it can sometimes be frustrating when you keep geting 401 unauthorized in your browser console even when you are fully convinced that you have followed all the instructions from the documentation.

In this article, I will be sharing with you some common pitfalls I have identified based on my experience while working with Laravel Sanctum and a separate Vue SPA.

Before we proceed, I must say the easiest way to integrate Laravel Sanctum into your Laravel application is by using the Laravel Breeze package.

Laravel has excellent documentation covering how to set up Sanctum in your Laravel application. Please go through the documentation as we won't be covering the exact steps in this post.

This tutorial is focusing on the common pitfalls you would likely face even after going through the documentation.

Be sure to define the following environment variables in your Laravel .env file:

Make sure you add the port numbers.

APP_URL=http://localhost:80
FRONTEND_URL=http://localhost:5173
SESSION_DOMAIN=localhost

• #1 Using local Custom domains

  Let's assume you're using custom domains locally. So your Frontend domain is demo.local and the Backend API is api.demo.local.
  The updated .env variables will now look like below. Notice the leading . in the SESSION_DOMAIN variable

  APP_URL=http://api.demo.local:80
  FRONTEND_URL=http://demo.local:5173
  SESSION_DOMAIN=.demo.local
  

• #2 Misconfigured CORS file

  If you're integrating Sanctum into an existing laravel application that has a cors file already, check to make sure the paths and allowed_origins values are set properly. Most importantly the paths value should allow requests from both the api and web routes.
  allowed_origins array should include your Frontend domain.
  Also make sure support_credentials is set to true.
  Below is a sample cors file

    return [
  
        /*
        |--------------------------------------------------------------------------
        | Cross-Origin Resource Sharing (CORS) Configuration
        |--------------------------------------------------------------------------
        |
        | Here you may configure your settings for cross-origin resource sharing
        | or "CORS". This determines what cross-origin operations may execute
        | in web browsers. You are free to adjust these settings as needed.
        |
        | To learn more: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS
        |
        */
  
        'paths' => ['*'],
  
        'allowed_methods' => ['*'],
  
        'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:5173')],
  
        'allowed_origins_patterns' => [],
  
        'allowed_headers' => ['*'],
  
        'exposed_headers' => [],
  
        'max_age' => 0,
  
        'supports_credentials' => true,
  
    ];
  

• #3 Sanctum Config file

  The generated sanctum file should be fine to work with, but you can review it to make sure your frontend application url is included or referenced in the stateful key.

• #4 Use web route for authentication

  Laravel will automatically place the authentication routes in the web.php file or include a reference of the auth.php if you use an authentication scafolding package like Laravel Breeze.
  In a case where you're defining the authentication routes and controllers manually, you should make sure the routes are placed in the web.php file.

Conclusion

In conclusion Laravel Sanctum makes authenticating your Vue Single Page Application with a Laravel backend using cookies and sessions.

Laravel goes one step forward by providing Laravel Breeze which makes it super easier to generate all your authentication boilerplate code. There are however some common mistakes developers make when working with Laravel Sanctum and a Single Page Application and this post highlighted some of these mistakes and the suggested solutions.