README

Installation

composer require jekk0/jwt-auth

Optionally, install the paragonie/sodium_compat package from composer if your php env does not have libsodium installed:

composer require paragonie/sodium_compat

Package configuration

Publish package resources

php artisan vendor:publish --provider=Jekk0\JwtAuth\JwtAuthServiceProvider

After running this command, resources from the package, such as the configuration file and migrations, will be added to your Laravel application.

Configure package (optional)

You should now have a ./config/jwtauth.php file that allows you to configure the package.

Create a new table for manage refresh tokens

Run the migrate command to create the table jwt_refresh_tokens needed to store JWT refresh token data

php artisan migrate

Generate certificates and add configuration to your .env file

$ php artisan jwtauth:generate-certificates

Copy and paste the content below into your .env file:

JWT_AUTH_PUBLIC_KEY=zvZFv5w3DuY3rZK901cnMM8UmV...
JWT_AUTH_PRIVATE_KEY=GaD9g0Xk5QHpzIJOIuEbUEOyJXQSpN...

Laravel application configuration

Configure auth guard

Make the following changes to the file:

// file /config/auth.php

    'guards' => [
-        'web' => [
-            'driver' => 'session',
-            'provider' => 'users',
-        ],
+        'jwt-user' => [
+            'driver' => 'jwt',
+            'provider' => 'users',
+        ],
    ]

A JWT user can be any model that implements the native laravel interface \Illuminate\Contracts\Auth\Authenticatable

Create the user auth controller

php artisan make:controller UserAuthController

// app/Http/Controllers/UserAuthController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class UserAuthController
{
    public function login(Request $request): JsonResponse
    {
        $credentials = $request->only('email', 'password');

//        $tokens = auth('jwt-user')->attempt($credentials);
//        if (is_null($tokens)) {
//            throw new AuthenticationException();
//        }

        $tokens = auth('jwt-user')->attemptOrFail($credentials);

        return new JsonResponse($tokens->toArray());
    }

    public function refresh(Request $request): JsonResponse
    {
        $tokens = auth('jwt-user')->refreshTokens((string)$request->get('token'));

        return new JsonResponse($tokens->toArray());
    }

    public function logout(): JsonResponse
    {
        auth('jwt-user')->logout();

        return new JsonResponse();
    }

    public function logoutFromAllDevices(): JsonResponse
    {
        auth('jwt-user')->logoutFromAllDevices();

        return new JsonResponse();
    }

    public function profile(Request $request): JsonResponse
    {
        return new JsonResponse(['name' => $request->user()->name, 'email' => $request->user()->email]);
    }
}

Add auth routes

// routes/api.php

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\UserAuthController;

Route::group(['prefix' => '/auth/user'], function () {
    Route::post('/login', [UserAuthController::class, 'login']);
    Route::post('/refresh', [UserAuthController::class, 'refresh']);
    Route::post('/logout', [UserAuthController::class, 'logout'])->middleware('auth:jwt-user');
    Route::post('/logout/all', [UserAuthController::class, 'logoutFromAllDevices'])->middleware('auth:jwt-user');
    Route::get('/profile', [UserAuthController::class, 'profile'])->middleware('auth:jwt-user');
});

Pruning expired JWT refresh tokens

// routes/console.php

use Illuminate\Support\Facades\Schedule;
use Jekk0\JwtAuth\Model\JwtRefreshToken;

Schedule::command('model:prune', ['--model' => [JwtRefreshToken::class]])->daily();

Refresh Token Flow

The Refresh Token Flow is a mechanism that allows users to obtain a new access token without re-authenticating. It is used to maintain sessions securely while keeping access tokens short-lived.

User Authentication

The user logs in with their credentials (e.g., email/password) The server verifies the credentials and issues:

A short-lived access token (e.g., valid for 15 minutes).
A long-lived refresh token (e.g., valid for several days or weeks).

Authentication request:

curl --location 'localhost:8000/api/auth/user/login' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "user@example.com",
    "password": "user"
}'

Authentication response:

{
    "access": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9...",
        "expiredAt": 1741606251
    },
    "refresh": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9...",
        "expiredAt": 1744197351
    }
}

An access token is used to authenticate and authorize users, granting them access to protected resources without needing to repeatedly log in. It contains user identity and custom claims and is typically short-lived to enhance security.

A refresh token is used to obtain a new access token without requiring the user to log in again. It is long-lived and helps maintain user sessions securely while minimizing exposure of credentials.

Accessing Protected Resources

The client includes the access token in the Authorization header (Bearer <access_token>) to make authenticated API requests.
The server validates the token and grants access.

User profile request:

curl --location 'localhost:8000/api/auth/user/profile' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Token Expiration & Refresh Request

When the access token expires, the client sends a request to the token refresh endpoint.
The request includes the refresh token.
The server verifies the refresh token (e.g., checks its validity and ensures it is not revoked).
If valid, the server issues a new access token and refresh token.
The client replaces the expired access token and refresh token with new ones.

Refresh request:

curl --location 'localhost:8000/api/auth/user/refresh' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "token": "YOUR_REFRESH_TOKEN"
}'

Refresh response:

{
    "access": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9...",
        "expiredAt": 1741606046
    },
    "refresh": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9...",
        "expiredAt": 1744197146
    }
}

Logout or Token Revocation

If the user logs out, the refresh token will be revoked (removed from a database).
If a refresh token is compromised, see Refresh token compromised

Logout request:

curl --location --request POST 'localhost:8000/api/auth/user/logout' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Logout from all devices request:

curl --location --request POST 'localhost:8000/api/auth/user/logout/all' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Security

Access token invalidation

Since the lifetime of an access token is relatively short (up to one hour, with a default of 15 minutes), the package does not invalidate the access token upon logout. Instead, invalidation is only performed for the refresh token to avoid additional database query overhead.

It is assumed that the frontend will simply remove the access token from storage upon logout, allowing it to expire naturally. However, if token invalidation needs to be enforced on every request, this can be implemented using an event-based mechanism.

Make event listener:

php artisan make:listener AccessTokenInvalidation

<?php

namespace App\Listeners;

use Illuminate\Auth\AuthenticationException;
use Jekk0\JwtAuth\Events\JwtAccessTokenDecoded;
use Jekk0\JwtAuth\Model\JwtRefreshToken;

class AccessTokenInvalidation
{

    public function handle(JwtAccessTokenDecoded $event): void
    {
        // Solution 1
        $accessTokenId = $event->accessToken->payload->getJwtId();
        $refreshToken = JwtRefreshToken::whereAccessTokenJti($accessTokenId)->first();

        if ($refreshToken === null) {
            throw new AuthenticationException();
        }
        
        // Solution 2
        // $refreshTokenId = $event->accessToken->payload->getReferenceTokenId();
        // $refreshToken = JwtRefreshToken::find($refreshTokenId);
        //
        // if ($refreshToken === null) {
        //     throw new AuthenticationException();
        // }

        // Solution 3
        // If you do not want to use a relational database, you can implement token invalidation using two events:
        // 1. On Logout (JwtLogout Event) – Store the access token in a blacklist for its remaining lifetime using a fast storage solution, such as Redis or MongoDB.
        // 2. On Token Decoding (JwtAccessTokenDecoded Event) – Check whether the token is in the blacklist before processing it.
    }
}

Refresh token compromised

If a refresh token is reused (i.e., an old token is attempted after a new one has been issued), it is a strong indication of a token theft or replay attack. Here’s what to do:

Immediately Revoke All Active Tokens
- Revoke both the newly issued and previously used refresh tokens.
- Invalidate any active access tokens associated with the compromised refresh token.
Notify the User
- If a stolen refresh token was used, inform the user about a possible security breach.
- Recommend changing their password if suspicious activity is detected.

Make event listener:

php artisan make:listener RefreshTokenCompromised

<?php

namespace App\Listeners;

use Illuminate\Support\Facades\Log;
use Jekk0\JwtAuth\Events\JwtRefreshTokenCompromised;
use Jekk0\JwtAuth\Model\JwtRefreshToken;

class RefreshTokenCompromised
{
    public function handle(JwtRefreshTokenCompromised $event): void
    {
        Log::info("Guard $event->guard: Refresh token compromised.");

        // Get all user refresh tokens
        $affectedRefreshTokens = JwtRefreshToken::where('subject', '=', (string)$event->user->id)->get();

        // If you use Access token invalidation then this step is not needed
        foreach ($affectedRefreshTokens as $refreshToken) {
            $accessTokenId = $refreshToken->access_token_jti;

            // Invalidate access tokens
            // ...
        }

        // Invalidate refresh tokens related to user
        JwtRefreshToken::whereIn('jti', $affectedRefreshTokens->pluck('jti'))->delete();

        // Send notification to user
        //...
    }
}

Customization

Customize JWT token payload

To add custom claims to a JWT token, you need to implement the interface Jekk0\JwtAuth\Contracts\JwtCustomClaims

// file app/Models/User.php 
<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Jekk0\JwtAuth\Contracts\CustomClaims;

class User extends Authenticatable implements CustomClaims
{
    // ...
    
    public function getJwtCustomClaims(): array
    {
        return [
            'role' => 'user',
            'name' => 'John'
        ];
    }
}

//...
// Get custom claims in controller 

$role = auth('jwt-user')->getAccessToken()->payload['role']
$name = auth('jwt-user')->getAccessToken()->payload['name']

Customize JWT extractor

By implementing a custom extractor (default Authorization: Bearer), you can retrieve the JWT token from alternative locations such as request headers, query parameters or even custom request attributes.

php artisan make:provider CustomJwtTokenExtractor

// file /app/Providers/CustomJwtTokenExtractor.php

<?php

namespace App\Providers;

use Illuminate\Http\Request;
use Illuminate\Support\ServiceProvider;
use Jekk0\JwtAuth\Contracts\TokenExtractor;

class CustomJwtTokenExtractor extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(TokenExtractor::class, function () {
            return new class implements TokenExtractor {
                public function __invoke(Request $request): ?string
                {
                    return $request->header('X-API-TOKEN');
                }
            };
        });
    }
    
    public function boot(): void
    {
        //
    }
}

Customize JWT token issuer

By default, the JWT token issuer is taken from the request URL. To change this behavior, override the binding for Jekk0\JwtAuth\Contracts\TokenExtractor as shown in the example below:

php artisan make:provider CustomJwtTokenIssuer

// file /app/Providers/CustomJwtTokenIssuer.php

<?php

namespace App\Providers;

use Illuminate\Http\Request;
use Illuminate\Support\ServiceProvider;
use Jekk0\JwtAuth\Contracts\TokenIssuer;

class CustomJwtTokenIssuer extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(TokenIssuer::class, function () {
            return new class implements TokenIssuer {
                public function __invoke(Request $request): string
                {
                    return 'CustomIssuer';
                }
            };
        });
    }
    
    public function boot(): void
    {
        //
    }
}

Available events:

Jekk0\JwtAuth\Events\JwtAccessTokenDecoded
Jekk0\JwtAuth\Events\JwtAttempting
Jekk0\JwtAuth\Events\JwtAuthenticated
Jekk0\JwtAuth\Events\JwtFailed
Jekk0\JwtAuth\Events\JwtLogin
Jekk0\JwtAuth\Events\JwtLogout
Jekk0\JwtAuth\Events\JwtLogoutFromAllDevices
Jekk0\JwtAuth\Events\JwtRefreshTokenCompromised
Jekk0\JwtAuth\Events\JwtRefreshTokenDecoded
Jekk0\JwtAuth\Events\JwtTokensRefreshed
Jekk0\JwtAuth\Events\JwtValidated

Functionally testing a JWT protected api

Login with Laravel's default actingAs method:

public function test_authenticate_in_tests(): void
{
    $user = UserFactory::new()->create();
    $response = $this->actingAs($user, 'YOUR-GUARD-NAME')->postJson('/api/profile');

    self::assertSame(200, $response->getStatusCode());
}

Login with JWT guard:

public function test_logout(): void
{
    $user = UserFactory::new()->create();
    auth('user')->login($user);
    
    $response = $this->postJson('/api/logout');
    self::assertSame(200, $response->getStatusCode());
}

public function test_logout(): void
{
    $user = UserFactory::new()->create();
    $tokenPair = auth($guard)->login($user);

    $response = $this->getJson('/api/profile', ['Authorization' => 'Bearer ' . $tokenPair->access->token]);    

    self::assertSame(200, $response->getStatusCode());
}

Manually generate a JWT token for end-to-end testing:

public function test_authenticate(): void
    {
        $user = UserFactory::new()->create();
        $accessToken = $this->app->get(TokenManager::class)->makeTokenPair($user)->access;
        
        $response = $this->postJson(
            '/api/profile',
            ['origin' => config('app.url')],
            ['Authorization' => 'Bearer ' . $accessToken->token]
        );

        self::assertSame(200, $response->getStatusCode());
    }

Examples

Laravel separated user auth example application
It demonstrates a role-based authentication system where different user types (User, Admin, Company) are stored separately in the database.

jekk0 / jwt-auth

Maintainers

Details