README

Implement an Auth guard for FusionAuth JWTs in Laravel.
It ships with also a middleware to check against the user role.

Installation

You can install the package via composer:

composer require danilopolani/laravel-fusionauth-jwt

Then publish its config file:

php artisan vendor:publish --tag=fusionauth-jwt-config

Configuration

There are a few notable configuration options for the package.

Key	Type	Description
`domain`	String	Your FusionAuth domain, e.g. `auth.myapp.com` or `sandbox.fusionauth.io`.
`client_id`	String	The Client ID of the current application.
`client_secret`	String	The Client Secret of the current application.
`issuers`	Array	A list of authorized issuers for the incoming JWT.
`audience`	String \| Null	The ID/Name of the authorized audience. If null, the Client ID will be used.
`supported_algs`	Array	The supported algorithms of the JWT. Supported: `RS256` and `HS256`.
`default_role`	String \| Null	The default role to be checked if you're using the `CheckRole` middleware.

Usage

To start protecting your APIs you need to add the Guard and the Auth Provider to your config/auth.php configuration file:

'guards' => [
    // ...
    'fusionauth' => [
        'driver' => 'fusionauth',
        'provider' => 'fusionauth',
    ],
],

'providers' => [
    // ...
    'fusionauth' => [
        'driver' => 'fusionauth',
    ],
],

Then you can use the auth:fusionauth guard to protect your endpoints; you can apply it to a group or a single route:

// app\Http\Kernel.php

protected $middlewareGroups = [
    'api' => [
        'auth:fusionauth',
        // ...
    ],
];

// or routes/api.php

Route::get('users', [UserController::class, 'index'])
    ->middleware('auth:fusionauth');

Now requests for those endpoints will check if the given JWT (given as Bearer token) is valid.

To retrieve the current logged in user - or to check if it's logged in - you can use the usual Auth facade methods, specifying the fusionauth guard:

Auth::guard('fusionauth')->check();

/** @var \DaniloPolani\FusionAuthJwt\FusionAuthJwtUser $user */
$user = Auth::guard('fusionauth')->user();

Role middleware

The package ships with a handy middleware to check for user role (stored in the roles key).

You can apply it on a middleware group inside the Kernel.php or to specific routes:

// app\Http\Kernel.php

protected $middlewareGroups = [
    'api' => [
        'auth:fusionauth',
        \DaniloPolani\FusionAuthJwt\Http\Middleware\CheckRole::class,
        // ...
    ],
];

// or routes/api.php

Route::get('users', [UserController::class, 'index'])
    ->middleware(['auth:fusionauth', 'fusionauth.role']);

By default the middleware will check that the current user has the default_role specified in the configuration file, but you can use as well a specific role, different from the default:

// routes/api.php

Route::get('users', [UserController::class, 'index'])
    ->middleware(['auth:fusionauth', 'fusionauth.role:admin']);

For more complex cases we suggest you to take a look on how the CheckRole middleware is written (using the RoleManager class) and write your own.

Usage in tests

When you need to test your endpoints in Laravel, you can take advantage of the actingAs method to set the current logged in user.

You can pass any property you want to the FusionAuthJwtUser class, like email, user etc. Take a look at this example where we specify the user roles:

use DaniloPolani\FusionAuthJwt\FusionAuthJwtUser;

$this
    ->actingAs(
        new FusionAuthJwtUser([
            'roles' => ['user', 'admin'],
        ]),
        'fusionauth',
    )
    ->get('/api/users')
    ->assertOk();

If you need to set the authenticated user outside HTTP testing (therefore you can't use actingAs()), you can use the setUser() method of the Auth facade:

use DaniloPolani\FusionAuthJwt\FusionAuthJwtUser;
use Illuminate\Support\Facades\Auth;

Auth::guard('fusionauth')->setUser(
    new FusionAuthJwtUser([
        'roles' => ['user', 'admin'],
    ])
);

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email danilo.polani@gmail.com instead of using the issue tracker.

danilopolani / laravel-fusionauth-jwt

Maintainers

Details