Lumen Passport

Making Laravel Passport work with Lumen

Introduction

It's a simple service provider that makes Laravel Passport work with Lumen.

Installation

First install Lumen Micro-Framework if you don't have it yet.

Then install Lumen Passport:

composer require dusterio/lumen-passport

Or if you prefer, edit composer.json manually and run then composer update:

{
    "require": {
        "dusterio/lumen-passport": "^0.3.5"
    }
}

Modify the bootstrap flow

We need to enable both Laravel Passport provider and Lumen Passport specific provider:

/** @file bootstrap/app.php */

// Enable Facades
$app->withFacades();

// Enable Eloquent
$app->withEloquent();

// Enable auth middleware (shipped with Lumen)
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);

// Register two service providers, Laravel Passport and Lumen adapter
$app->register(Laravel\Passport\PassportServiceProvider::class);
$app->register(Dusterio\LumenPassport\PassportServiceProvider::class);

Laravel Passport ^7.3.2 and newer

On 30 Jul 2019 Laravel Passport 7.3.2 had a breaking change - new method introduced on Application class that exists in Laravel but not in Lumen. You could either lock in to an older version or swap the Application class like follows:

/** @file bootstrap/app.php */

//$app = new Laravel\Lumen\Application(
//    dirname(__DIR__)
//);
$app = new \Dusterio\LumenPassport\Lumen7Application(
    dirname(__DIR__)
);

* Note: If you look inside this class - all it does is adding an extra method configurationIsCached() that always returns false.

Migrate and install Laravel Passport

# Create new tables for Passport
php artisan migrate

# Install encryption keys and other stuff for Passport
php artisan passport:install

It will output the Personal access client ID and secret, and the Password grand client ID and secret.

* Note: Save the secrets in a safe place, you'll need them later to request the access tokens.

Configuration

Configure Authentication

Edit config/auth.php to suit your needs. A simple example:

/** @file config/auth.php */

return [

    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            'model' => \App\Models\User::class
        ]
    ],

];

* Note: Lumen 7.x and older uses \App\User::class

Load the config since Lumen doesn't load config files automatically:

/** @file bootstrap/app.php */

$app->configure('auth');

Registering Routes

Next, you should call the LumenPassport::routes method within the boot method of your application (one of your service providers). This method will register the routes necessary to issue access tokens and revoke access tokens, clients, and personal access tokens:

/** @file app/Providers/AuthServiceProvider.php */

use Dusterio\LumenPassport\LumenPassport;

class AuthServiceProvider extends ServiceProvider
{
    public function boot()
    {
        LumenPassport::routes($this->app);

        /* rest of boot */
    }
}

User model

Make sure your user model uses Laravel Passport's HasApiTokens trait.

/** @file app/Models/User.php */

use Laravel\Passport\HasApiTokens;

class User extends Model implements AuthenticatableContract, AuthorizableContract
{
    use HasApiTokens, Authenticatable, Authorizable, HasFactory;

    /* rest of the model */
}

Usage

You'll find all the documentation in Laravel Passport Docs.

Curl example with username and password authentication

First you have to issue an access token and then you can use it to authenticate your requests.

# Request
curl --location --request POST '{{APP_URL}}/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type": "password",
    "client_id": "{{CLIENT_ID}}",
    "client_secret": "{{CLIENT_SECRET}}",
    "username": "{{USER_EMAIL}}",
    "password": "{{USER_PASSWORD}}",
    "scope": "*"
}'

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "******",
    "refresh_token": "******"
}

And with the access_token you can request access to the routes that uses the Auth:Api Middleware provided by the Lumen Passport.

/** @file routes/web.php */

$router->get('/ping', ['middleware' => 'auth', fn () => 'pong']);

# Request
curl --location --request GET '{{APP_URL}}/ping' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

pong

Installed routes

This package mounts the following routes after you call routes() method, all of them belongs to the namespace \Laravel\Passport\Http\Controllers:

Verb	Path	Controller	Action	Middleware
POST	/oauth/token	AccessTokenController	issueToken	-
GET	/oauth/tokens	AuthorizedAccessTokenController	forUser	auth
DELETE	/oauth/tokens/{token_id}	AuthorizedAccessTokenController	destroy	auth
POST	/oauth/token/refresh	TransientTokenController	refresh	auth
GET	/oauth/clients	ClientController	forUser	auth
POST	/oauth/clients	ClientController	store	auth
PUT	/oauth/clients/{client_id}	ClientController	update	auth
DELETE	/oauth/clients/{client_id}	ClientController	destroy	auth
GET	/oauth/scopes	ScopeController	all	auth
GET	/oauth/personal-access-tokens	PersonalAccessTokenController	forUser	auth
POST	/oauth/personal-access-tokens	PersonalAccessTokenController	store	auth
DELETE	/oauth/personal-access-tokens/{token_id}	PersonalAccessTokenController	destroy	auth

* Note: some of the Laravel Passport's routes had to 'go away' because they are web-related and rely on sessions (eg. authorise pages). Lumen is an API framework so only API-related routes are present.

Extra features

There are a couple of extra features that aren't present in Laravel Passport

Prefixing Routes

You can add that into an existing group, or add use this route registrar independently like so;

/** @file app/Providers/AuthServiceProvider.php */

use Dusterio\LumenPassport\LumenPassport;

class AuthServiceProvider</