Forem: Samuel Olaegbe

How to authenticate your frontend apps with Laravel Sanctum

Samuel Olaegbe — Mon, 14 Dec 2020 10:54:12 +0000

Passport or Sanctum?

One popular question I have seen everywhere is people asking: "Should I use Passport or Sanctum to authenticate my API"? I have seen people answer this in various ways, but my answer is: Use Sanctum when you need to create a frontend application to interact with your API.

Sanctum provides authentication for your frontend application without the need for tokens unlike Passport, and that isn't to say Sanctum isn't capable of issuing tokens, you can also issue tokens with abilities (read: scope as used in Oauth) to users to authenticate all requests made to your API.

The two core functionalities Sanctum provides are:

Stateful authentication
API Tokens

I love to use Sanctum when building an API backend with Laravel that will interact with a frontend application as it's simple and straight-forward to use for that purpose.

Passport

Passport is a much more compact tool than Sanctum, with a lot of options for authenticating your users. This is more appropriate when building an application that offers Oauth2 capabilities, to enable your users to connect an external service with your application and also gives you the capability to grant each application scopes and abilities.

If you want to build an application that needs to issue Oauth2 tokens to external applications that may connect with a tool like Socialite, then Passport is definitely the right choice.

Installing sanctum in your Laravel application

The Laravel docs provide the information needed to set up Sanctum for your application, but I still got confused about setting it up and deciding what was right for my use case between the API tokens option and SPA Authentication option. So I have written this guide hoping it will help anyone else setting Sanctum for the first time.

Setting up:

Follow the installation guide
Leave the default options for model name and migrations

API Tokens or SPA Authentication

Sanctum provides these two authentication methods to you by default and you do not have to use the two at once. I have put together this shortlist to determine which one is best to use:

SPA Authentication:

Stateful authentication without tokens.
CSRF protection

API Tokens:

Issue tokens to users
Authenticate users with Bearer Authorization
Attach abilities to tokens for access control

To use the SPA Authentication, your SPA has to be on the same domain as your Laravel API.

The stateful authentication method uses Laravel sessions to authenticate the user and thus eliminating the need for tokens, and I think that is super smart!

To authenticate with this method, note that you need to use the web middleware as the Laravel session is only available through this middleware.

You could write your own custom authentication or use any of Laravel starter kits to authenticate, I love to use Breeze and take out the views as this is an API only application.

Configuring your 3rd party domains

In order for Sanctum to maintain stateful authentication, you need to configure your application's domain names from config/sanctum.php:

/*
|--------------------------------------------------------------------------
| Stateful Domains
|--------------------------------------------------------------------------
|
| Requests from the following domains / hosts will receive stateful API
| authentication cookies. Typically, these should include your local
| and production domains which access your API via a frontend SPA.
|
*/

'stateful' => explode(',', env(
  'SANCTUM_STATEFUL_DOMAINS',
  'localhost,localhost:8000,localhost:8080,::1'
)),

This setting notifies Sanctum on which domains it should keep your users logged in using cookie based session authentication. We want our users to remain logged-in on our SPA and also our API.

While in development, you want to make sure you add the different port names for your Laravel application and your SPA.

Above we have added localhost:8000 which is same as 127.0.0.1:8000 for our Laravel application and we have also added localhost:8080 which the URL of our SPA which is also running locally. Of course, you can change this to whatever the URL of your SPA is. I am using a Vue CLI app and the default URL is localhost:8080

Note that you have to update these settings in our environment variables once our app is deployed.

You should clear your application cache with php artisan config:cache after changing your config files to make sure the new changes are working.

Add the Sanctum middleware

Follow the docs to add the Sanctum middleware.

CORS

If your SPA is on a different URL like we have in this tutorial, you will come across cross-site resource sharing errors (cors), but do not fret, I will show you how to overcome those. First you should make sure the API paths you will be accessing via the SPA are listed in the paths key of the config/cors.php file:

/*
|--------------------------------------------------------------------------
| 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' => [
    'api/*', 
    'sanctum/csrf-cookie'
        //define other custom paths
],

Above, we have defined the paths we will be accessing on the API. The first is the /api/* path which will be handling all requests to our API routes in the routes/api.php file. We have also defined the sanctum/csrf-cookie path which will set the headers for our application to use in subsequent requests to the backend. More details on this can be found in the Authentication section.

TIP: You may configure the prefix for the routes defined in routes/api.php from App\Providers\RouteServiceProvider.php, or even set a new prefix for a new file path in the routes folder.

While testing, you should set your domains key in config/sessions.php to [localhost](http://localhost):

'domain' => 'localhost',

On the frontend, you should use a library like Axios with Vue or React which already helps you set your headers based on the response from the server during the initial authentication request as we will see below.

Further, you should set the withCredentials option of axios to true:

axios.defaults.withCredentials = true;

To enable Laravel transform XHTTP (or Ajax) responses to JSON instead of the regular redirect or view responses, you should set the Accept header to application/json when making requests.

In a Vue CLI app, this can be done from the main.js file:

import Vue from 'vue'
import App from './App.vue'
import axios from 'axios';

Vue.config.productionTip = false;
axios.defaults.headers.common['Accept'] = 'application/json';
axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
axios.defaults.withCredentials = true;

Authentication

The method of authentication Sanctum uses is similar to the regular authentication method in Laravel. The only difference is that you have to first make a post request to sanctum/csrf-token from your frontend application:

methods:{
    login(){
            //initial request to set Laravel authentication cookies
      axios.get('http://localhost:8000/sanctum/csrf-cookie').then(() => {
                //make a request to /login
        axios.post('http://localhost:8000/login', {
          email: "olaegbesamuel@gmail.com",
          password: "strong-password"
        }).then(res => {
                    //do anything with returned response
        })
      });
    },
}

Get authenticated user from a protected route

To protect a route with Sanctum, you need to apply the auth:sanctum middleware to the route definition:

//api.php
Route::middleware('auth:sanctum')->post('/me', function (Request $request) {
    return auth()->user();
});

If Sanctum was set up correctly you should get the authenticated user back:

{
"id":1,
"name":"Samuel Olaegbe",
"email":"olaegbesamuel@gmail.com",
"email_verified_at":null,
"created_at":"2020-12-12T23:19:04.000000Z",
"updated_at":"2020-12-12T23:19:04.000000Z"
}

Conclusion

While building a Laravel powered API, this is one of the problems we are faced with and I had to do a lot of research to get this working solution that has worked for me and thought to share it here. This post should be a guide on best practices on how to authenticate your first-party SPA with Sanctum and would be updated regularly.

Taylor promised some additional documentation on how to do this well:

// Detect dark theme var iframe = document.getElementById('tweet-1334587723269763074-100'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1334587723269763074&theme=dark" }

Let me know if you have any questions or additions and I will be happy to discuss them!

PS: Subscribe to my blog so you could receive an email each time I publish content.

How to speed up database performance with indexes

Samuel Olaegbe — Mon, 12 Oct 2020 08:15:52 +0000

Background

In this article we will take a look at how to optimize database queries in a Laravel or PHP application with a MySQL database. At ExpenseNG, our database keeps growing quickly as we record more government expenses from the Nigerian Open Treasury website. For an app that started at a bootcamp, we weren't prepared for the impact a growing database would have on the website.

With these amount of records we had the responsibility of visualizing these data on our website in the way that has most meaningful impact and passed across the right information, which is Where is the government spending most money?

If you visit the contractors page on ExpenseNG, you will see the list of everyone that has received money from the government sorted by the contractor who got the most money in the last completed month and you can also see the total amount they got for that month. The data looks like this:

Contractor name: "",
Total Amount Received: "",
Month Ended: ""

The Challenge

Now that we know what the data we need looks like, let's take a look at what it takes to retrieve this data from the database.

Two tables are involved in this operation and they are the contractors and payments table. The contractors table holds the records of all everyone that has received money from the government and the payments table holds the records of every payment ever made and a reference to their recipients.

The tables schema looks like this:

payments:
    - amount (double)
    - date (DATE)
    - recipient (string)

contractors:
    - name (string)
    ...

To sort the results from getting all the records from the contractors table by the total amount received by a contractor from the past month, that already sounds like a query involving two tables and we can achieve that with something like this:

SELECT contractors.*, (SELECT SUM(amount) from payments WHERE 
recipient = contractors.name) as total from contractors 
order by total desc

From the query above, we have a sub-select statement which helps us to calculate the total money received by all recipients and we can use the result from that sub-query to create a new column in our query which we can now use to sort our final result. The new column created by this sub-query is given an alias of total.

The query above doesn't include the logic for fetching only results from the month ended, so we will modify the query further below:

SELECT contractors.*, (SELECT SUM(amount) from payments 
WHERE recipient = contractors.name 
AND date BETWEEN(2020-09-01, 2020-09-31) ) as total 
from contractors 
order by total desc

In the above query, we have added a new constraint to the sub-query which is BETWEEN. As you know this allows us to select only results that start from the first value and end on the second value.

New problem

The query above works fine when you have a few records in your database, but when working with a database with thousands of records this can easily result in the query taking several minutes to execute or even resulting in a request timeout error on the server as the server doesn't receive a response for too long.

We can easily solve this problem by adding an index to the columns that are pivotal to our query, from the above query the columns we should add an index to are:

contractors.name
payments.recipient
payments.date
payments.amout

The query to add an index to our columns will look like this:

ALTER TABLE contractors ADD INDEX name_index (name)

Or if you are using Laravel migrations:

//database/migrations/2020_09_20_102101_add_index_to_payments_table.php
Schema::table('payments', function (Blueprint $table) {
    $table->index('recipient');
    $table->index('amount');
    $table->index('date');
});

Now we can reduce our query execution time greatly by adding indexes. On ExpenseNG, our queries went from timing out after several minutes to a about 0.02 seconds with a pagination of 20 results per page.

We can further improve our query execution time by only selecting the columns that we need, we will change this line to look like this:

SELECT contractors.name, contractors.date, (SELECT SUM(amount) from payments 
....

Using Laravel's Eloquent

We can achieve the same queries as we did above in Eloquent by using the addSelect method to create a sub-query to our original query:

Contractor::select(['name', 'shortname', 'id'])
        ->addSelect(['total' => Payment::selectRaw('SUM(amount)')
            ->whereColumn('recipient', 'contractors.name')
            ->whereBetween('date', [$monthStart, $monthEnd])
    ])->orderBy('total', 'desc')->paginate(20);

Here we are using Eloquent's advanced sub-queries which gives us a nice and comprehensive API to retrieve results from our model. If we wanted, we could lazy load our Contractor model relationships by chaining the the select method with with('payments')->paginate(20).

And that is how you optimize database queries on a large MySQL database.

Adding an index to a table makes UPDATE queries run for a longer time, so you should not use them on tables that will get update frequently.

Resources

Static analysis with Phpstan

Samuel Olaegbe — Mon, 05 Oct 2020 11:23:05 +0000

Testing your code is one way to ensure that you have a high quality codebase, which is one way to ensure the maintainability of your projects and also a way to ensure you don't ship broken features in your product. CI tools like Travis CI help you to test your code each time you push to source control.

Static analysis is the method of testing your code for basic logical, runtime or typographical exceptions without actually executing the code.

As you must have guessed, static analysis of your codebase happens fast since the code doesn't actually get executed but scanned for common errors like having a method that doesn't return the expected date type.

How static analysis works

Static analysis as the name implies, actually doesn't need to execute your code before catching bugs in them. Statically typed languages like Dart or Java already have this functionality built into their compilers. Since they always define the types of their constructs the compiler won't run when there is a typo or an incorrect type for a method or variable. Before the advent of static analysis and tools like PHPStan, developers spend a lot of time debugging their PHP code looking for errors because PHP's execution is line by line and so it only throws an error when it gets to the line containing the error. And may sometimes continue execution after encountering the error, depending on the type of error encountered.

PHPStan checks for a couple of language constructs such as use of instanceof, try-catch blocks, typehints, number of arguments passed to a function, accessibility of called methods and variables, and many more.

PHPStan: Static analysis in your favourite language

Recently, PHPStan Pro was announced by the creators of PHPStan and that is already looking very promising with continuous watch mode (hot-reloading in PHP?), a Web UI and an interactive fixer! The good news is you get to save a ton of time and keystrokes by finding errors sooner and PHPStan can suggest a fix for you and everyone is happier.

Using PHPStan in your projects

Below we will go over steps to use PHPStan in our projects.

Setting up your environment

You can use PHPStan in any PHP project of your choice, for the purpose of this tutorial I have created a skeleton PHP library that I will be using. My composer.json file looks like this before installing phpstan

A screenshot of my composer.json setup

Installing PHPStan as a dev dependency

composer require --dev phpstan/phpstan

We are installing phpstan as a dev dependency with composer.

Now you are ready to run your first analysis, copy and paste the code below in your terminal:

phpstan analyse src

Depending on the content of your src directory you may get some errors after running this command and that is totally fine as we will look at how to configure PHPStan to our taste soon.

phpstan Command

The analyse keyword is what tells phpstan to analyse your codebase, and the 3rd argument in the command is the path to the code you want to analyse. Here I have used src as that is where the code I have written lives, I do not need to analyse my vendor folder or other temporary folders. However if you are writing tests then it's a good idea to analyse your tests directory as well. PHPStan has some extensions for popular testing libraries like PHPUnit, Behat and mock frameworks like Mockery.

Configuration

PHPStan makes use of the neon file format for its configuration, ideally you will have a phpstan.neon at the root of your project folder. Whenever you run the phpstan analyse command, it will look for phpstan.neon at the root and use it as configuration to analyse your code. If it doesn't find the configuration file at the root of your project, PHPStan will also check for phpstan.neon.dist and if that doesn't exist as well, it will run with the default configs. Below is a basic configuration options to get you started. Read more here.

parameters:
    level: max
    paths:
        - src
            - test

Using the configuration setting above, we can now omit the 3rd argument when running the phpstan command which is the path to our source code. This is now a valid command once you have phpstan.neon on your root directory:

phpstan analyse

With the level set to max, we have more stricter analysis and things like incorrect typehints, incorrect return types, will now throw an error:

$ phpstan analyse
Note: Using configuration file Code\demo\photo-library\phpstan.neon.
 1/1 [============================] 100%

 ------ ----------------------------------------------------------------------------------------
  Line   Photo.php
 ------ ----------------------------------------------------------------------------------------
  7      Property Photo::$http has no typehint specified.
  9      Method Photo::__construct() has parameter $token with no typehint specified.
  25     Method Photo::photos() return type has no value type specified in iterable type array.
         💡 Consider adding something like array<Foo> to the PHPDoc.
         You can turn off this check by setting checkMissingIterableValueType: false in your
         Code\demo\photo-library\phpstan.neon.
  27     Method Photo::photos() should return array but returns string.
 ------ ----------------------------------------------------------------------------------------

Take note of this line which now tells us that our configuration file is being used to analyse our code:

Note: Using configuration file Code\demo\photo-library\phpstan.neon.

The code which produced the errors above looks like this:

<?php

declare(strict_types=1);

use GuzzleHttp\Client;

class Photo{

    private $http;

    public function __construct(string $token)
    {
        $this->http = new GuzzleHttp\Client([
            'base_uri' => 'https://photo.google.com',
            'headers' => [
                'Authorization' => 'Bearer ' . $token
            ]
        ]);
    }

    /**
     * Returns an array of photos in the 
     * library
     * 
     * @return array
     */
    public function photos(): array
    {
        return 'Photos in the library';
    }
}

Since my codebase above is relatively new and I am using PHP 7.4 with strict types enabled, I may have better luck resolving these errors in a few minutes. That may not be the case when you have a large codebase, and you don't have to feel bad for having these errors since you wrote the code without static analysis in mind.

Editing our phpstan.neon file and setting the level to anywhere between 0 and 8 will allow us to make a loose or strict analysis based on the level we settle for. The max level will use the strictest value available depending on the version of PHPStan you have. Learn more about the levels here

Nip it in the bug :)

Catch your bugs before they get bigger and cause problems. One way I love to do this is by adding phpstan to the scripts section of my composer.json and running a command to analyse my codebase before pushing to source control. You can also add phpstan to your travis ci builds and we will see how to do that in a bit.

Add the following to the scripts section of your composer.json:

"scripts": {
        "analyse": [
            "phpstan analyse src -c phpstan.neon --level max --no-progress",
            "phpstan analyse tests -c phpstan.neon --level 4 --no-progress"
        ],
}

This adds a script called analyse to composer which you can run by executing composer run analyse. That will execute the 2 commands we have specified here:

"phpstan analyse src -c phpstan.neon --level 5 --no-progress"
"phpstan analyse tests -c phpstan.neon --level 5 --no-progress"

The first command analyses our src directory and the second analyses the tests directory. We are passing a couple of arguments which you can almost already tell what they do:

-c phpstan.neon: Tells phpstan to run with the configurations defined in phpstan.neon
—level: Tells phpstan what level to run the analysis at (5 in this case)
—no-progress is a special flag to tell phpstan not to report analysis progress as it traverses our codebase.

Adding phpstan to your Travis builds

This can be achieved by adding the composer script to analyse our codebase in the script section of .travis.yml:

script:
  - composer run analyse

This is only for demonstration purpose, ideally you will want to run other checks which you can group into a composer script in your composer.json file and run that script in your travis build but this is meant to give you an overview of how that is done.

You can find a sample .travis.yaml which I use here for my builds here and a sample composer.json file here

Final notes

Static analysis is something I learned recently and I must say that it gives a unique developer experience. As I am able to write efficient and clean code and catch my errors before they make it to source control. I hope that this article has given you an insight on how static analysis can help you write better code and improve your development process. Please leave your thoughts and comments on Twitter.