Laravel Passport Custom JWT Claims

Customize the JWT claims in Laravel/Passport access tokens

What are JWT claims?

All access tokens issued by Laravel/Passport are in fact JSON web tokens (JWT). Each token contains a set of claims consisting of JSON key value pairs. Because the token is cryptographically signed using a public/private RSA key pair we can trust that the claims contained in the token were issued by Laravel/Passport.

Here is an example token containing the default Laravel/Passport claims:

If we decode the token you get the following JWT payload object:

{
  "aud": "c8e104f0-0562-11e7-905b-3d77df97f2f8",
  "jti": "9e70128f990e1ef244af074b43306a4f45beab6553396168228bf876ce01005224fa17937d0f0157",
  "iat": 1489901755,
  "nbf": 1489901755,
  "exp": 1521437755,
  "sub": "c8df99a0-0562-11e7-9082-bfd7aa3311e8",
  "scopes": []
}

For reference, the claim aud is the Laravel/Passport client_id that issued the token and the key sub refers to the user id in your laravel users table. Note that my client_id and user_id columns are UUID data types.

Why would you need custom claims?

The OpenID Connect protocol requires JWT claims that are not included in Laravel/Passport access tokens. Adding custom claims allows us to use access tokens issued by Laravel/Passport to authenticate with other services using OpenID Connect. For example, with this package it is possible to use a Laravel/Passport access token to authenticate a laravel user on a Couchbase Sync Gateway server.

Installation

Install the package via composer:

composer require benbjurstrom/passport-custom-jwt-claims

Add the service provider to the config/app.php providers array.

// config/app.php
'providers' => [
    ...
    BenBjurstrom\JwtClaims\JwtClaimsServiceProvider::class
];

Do not include Laravel\Passport\PassportServiceProvider in your providers array as JwtClaimsServiceProvider extends from it.

Configuration

To set your custom claims you must publish the config file:

php artisan vendor:publish --provider="JwtClaimsServiceProvider"

This is the contents of the published file. Add additional claims as needed.

return [

    /*
    |--------------------------------------------------------------------------
    | User Claims
    |--------------------------------------------------------------------------
    |
    | User claims will be loaded from the properties of the auth providers model
    | specified in the auth config file.
    |
    */
    'user_claims' => [
        'name' => 'name',
        'email' => 'email',
    ],

    /*
    |--------------------------------------------------------------------------
    | App claims
    |--------------------------------------------------------------------------
    |
    | App claims are static and will be given the specified value across all
    | tokens issued by the app.
    |
    */
    'app_claims' => [
        'iss' => url('')
    ]

];