Solomon Onuche

Posted on Mar 23, 2022 • Updated on Apr 3, 2022

How to Implement JWT Auth in Laravel 9

#php #laravel #jwt #opensource

Introduction

This is a friendly introduction to Laravel 9 API authentication using JWT. In this tutorial we will learn how to use JSON Web Token (JWT) to secure REST APIs in Laravel 9. We will be using a third-party library called “php-open-source-saver/jwt-auth” to achieve this. Creating authentication in Laravel is very easy as most of the common functionalities needed in a web application are already implemented out of the box.

Goal

The reader should be able to create secure REST APIs in Laravel using JWT after going through this tutorial

Requirement

Basic knowledge of the Laravel framework is required to take this tutorial as this is not an introduction to Laravel tutorial
XAMPP
composer
Postman

What is JSON Web Token

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
When should you use JSON Web Tokens
Here are some scenarios where JSON Web Tokens are useful:
• Authorization: This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single Sign-On is a feature that widely uses JWT nowadays, because of its small overhead and its ability to be easily used across different domains.
• Information Exchange: JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be signed—for example, using public/private key pairs—you can be sure the senders are who they say they are. Additionally, as the signature is calculated using the header and the payload, you can also verify that the content hasn't been tampered with.

What is the JSON Web Token structure?

In its compact form, JSON Web Tokens consist of three parts separated by dots (.), which are:
• Header
• Payload
• Signature
Therefore, a JWT typically looks like the following.
xxxxx.yyyyy.zzzzz

How Does It Work

The simple explanation as to how JWT authentication work is when a user attempt to log in with their correct credentials (i.e email and password), a token is generated and sent back to the client-side, the client-side then stores the token and use it to access protected routes.

Let's Get To It Shall We
Table of content

Fresh Laravel Install
Create Your Database
Connect To The Database
Run Migration To Create User Table
Install JWT Auth Package
Configure Auth Guard
Modify User Model
Create Controller
Add API Routes
Test Endpoints With Postman
Conclusion

Fresh Laravel Install

We will kick things off by installing a new Laravel 9 project
Run the below commands to install and navigate to your fresh Laravel project

composer create-project laravel/laravel laravel-jwt
cd laravel-jwt

Create Your Database
Create a MySQL database with the name laravel-jwt, I am using XAMMP but whatever you are using will work just fine.

Connect To The Database

For your Laravel application to be able to interact with the new database you just created you need to establish a connection, add your database credentials to the .env file to connect

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel-jwt
DB_USERNAME=root
DB_PASSWORD=

Run Migration To Create User Table
Laravel comes with the User table migration all we need to do is to run the migration to create the table in our database, we do not need to create any other table, the user table is sufficient for the scope of this tutorial. Run the command below to create the users table

    php artisan migrate

Install JWT Auth Package

Now that our database is all set up its time to install and configure the Laravel jwt auth package, will be using “php-open-source-saver/jwt-auth” a fork of “tymondesign/jwt-auth”, the reason for the choice is simple as “tymondesign/jwt-auth” seems to have been abandoned and is not compatible with Laravel 9
Run the below command to install the latest version of the package

composer require php-open-source-saver/jwt-auth

Next, we have to publish the package configurations run the below command to copy the jwt configuration file from vendor to confi/jwt.php

php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider"

a secret key needs to be generated to handle the token encryption run this command to achieve that

php artisan jwt:secret

This will update your .env file with something like

JWT_SECRET=foobar

It is the key that will be used to sign your tokens

Configure Auth Guard

Inside the config/auth.php file you will need to make a few changes to configure Laravel to use the jwt guard to power your application authentication.

Make the following changes to the file:

 'defaults' => [
        'guard' => 'api',
        'passwords' => 'users',
    ],


    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'api' => [
                'driver' => 'jwt',
                'provider' => 'users',
        ],

    ],

Here we are telling the api guard to use the jwt driver, and we are setting the api guard as the default.
We can now use Laravel's built-in Auth system, with jwt-auth doing the work behind the scenes!

Modify User Model

Firstly you need to implement the PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject contract on your User model, which requires that you implement the 2 methods getJWTIdentifier() and getJWTCustomClaims().
Replace the existing code in app/Models/User.php with the following code

<?php

namespace App\Models;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject;

class User extends Authenticatable implements JWTSubject
{
    use HasFactory, Notifiable;

    /**
     * The attributes that are mass assignable.
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array<int, string>
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * The attributes that should be cast.
     *
     * @var array<string, string>
     */
    protected $casts = [
        'email_verified_at' => 'datetime',
    ];

     /**
     * Get the identifier that will be stored in the subject claim of the JWT.
     *
     * @return mixed
     */
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    /**
     * Return a key value array, containing any custom claims to be added to the JWT.
     *
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [];
    }

}

That is it for our model setup

Create Controller

Next, we create a controller to handle the core logic of the authentication process
Run this command to generate the controller

php artisan make:controller AuthController

replace the content of the controller with the following code

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Hash;
use App\Models\User;

class AuthController extends Controller
{

    public function __construct()
    {
        $this->middleware('auth:api', ['except' => ['login','register']]);
    }

    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|string|email',
            'password' => 'required|string',
        ]);
        $credentials = $request->only('email', 'password');

        $token = Auth::attempt($credentials);
        if (!$token) {
            return response()->json([
                'status' => 'error',
                'message' => 'Unauthorized',
            ], 401);
        }

        $user = Auth::user();
        return response()->json([
                'status' => 'success',
                'user' => $user,
                'authorisation' => [
                    'token' => $token,
                    'type' => 'bearer',
                ]
            ]);

    }

    public function register(Request $request){
        $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:6',
        ]);

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => Hash::make($request->password),
        ]);

        $token = Auth::login($user);
        return response()->json([
            'status' => 'success',
            'message' => 'User created successfully',
            'user' => $user,
            'authorisation' => [
                'token' => $token,
                'type' => 'bearer',
            ]
        ]);
    }

    public function logout()
    {
        Auth::logout();
        return response()->json([
            'status' => 'success',
            'message' => 'Successfully logged out',
        ]);
    }

    public function me()
    {
        return response()->json([
            'status' => 'success',
            'user' => Auth::user(),
        ]);
    }

    public function refresh()
    {
        return response()->json([
            'status' => 'success',
            'user' => Auth::user(),
            'authorisation' => [
                'token' => Auth::refresh(),
                'type' => 'bearer',
            ]
        ]);
    }

}

A brief explanation of what is going on in the AuthController
Constructor: we defined a constructor method in our controller class so that we can use the auth:api middleware within it, the middleware prevent unauthenticated access to certain methods within the controller.
Login: the login method authenticate the user using their email and password, the Auth facades attempt() method returns the jwt token once the user is successfully authenticated, the generated token is retrieved and returned as JSON with the user object
Register: the register method creates the user record and logs the user in with token generations as well
Logout: the logout method invalidate the user auth token
Refresh: the refresh method invalidates the current logged in user and generate a new token
Me: the me method returns the user profile or in this case the user object

Add API Routes

To access our newly created methods we need to define our API routes, to do this navigate to routes/api.php and replace the content with the following

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\AuthController;

Route::controller(AuthController::class)->group(function () {
    Route::post('login', 'login');
    Route::post('register', 'register');
    Route::post('logout', 'logout');
    Route::post('refresh', 'refresh');
    Route::get('me', 'me');

});

Note we are using Laravel 9 syntax here, you will need to declare your route the normal way if you are using lower versions of Laravel

Test End Points With Postman

Before we move to Postman and start testing our API endpoints we need to start our Laravel application first
Run the below command to start your Laravel application

php artisan serve

now we are ready to begin testing;
start your postman app
here are the lists of endpoints we will be testing

Register: localhost:8000/api/register. Method: POST
Login: localhost:8000/api/login. Method: POST
Logout: localhost:8000/api/logout. Method: POST
Refresh: localhost:8000/api/refresh. Method:POST
Me: localhost:8000/api/me. Method: GET

Register API

Start your Postman application add the registration API in the address bar, select the POST HTTP request method, select form-data in the body tab and add the name, email and password input fields, click on the Send button to see the server response

Login API

Add the email and password to the input field click Send to see the response

Me, Refresh and Logout

The Me, Refresh and Logout endpoints are all protected by the auth:api middleware and hence requires that you send a valid token with the authorization header, so copy the token from your login response go to the authorization tab, select bearer token and paste it the input provided.

Me API

Refresh API

Logout

Conclusion!

Yes, you made it to the end, in this article we learned how to create REST API authentication with JWT, the full code for this project is available on GitHub