This package is primarily intended for use as middleware within Laravel 5 to provide restricted route access on the basis of scopes defined within the payload of a JSON Web Token (JWT).

PHP 5.6+

This package will not be present on packagist until the first major version (i.e., 1.0.0) is released.

Until that time, installation will first require that composer.json is updated to include this github repo

  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/bendbennett/JWT"
    }
  ],

Then composer can be used

$ composer require bendbennett/JWT

Include the JWTServiceProvider in the providers array

    Bendbennett\JWT\Providers\JWTServiceProvider::class,

Include the JWT facade in the aliases array

    'JWT'   => Bendbennett\JWT\Facades\JWT::class,

Include the VerifyClaim class in the routeMiddleware array

    'verifyClaim' => \Bendbennett\JWT\Middleware\VerifyClaim::class,

$ php artisan vendor:publish

Possible choices are ES256|ES384|ES512|RS256|RS384|RS512 for asymmetric algorithms or HS256|HS384|HS512 for symmetric algorithms.

ttl (time to live) - this is in minutes

Typically this would include:

• iss (issuer)
• iat (issued at - unix timestamp)
• exp (expires - unix timestamp, uses ttl defined in the config file),
• nbf (not before - unix timestamp)
• sub (subject - usually an ID associated with the current user)
• jti (JWT ID).

In this implementation iss, iat, exp, nbf and jti are autogenerated (see below) but can be overridden.

It is expected that sub will be supplied during the generation of the payload if this is defined as a requiredClaim.

This should be set to a random string if a symmetric algorithm is going to be used

These should either:

• provide a relative location of public and private keys within the laravel directory (e.g., certs/publicKey.pem, if the certs directory is at the same level as the app, config or public directories)
• provide an absolute location of public and private keys within the file system
• contain the actual text of the key

If ES256, ES384 or ES512 algorithms are to be used then the private and public keys can be generated as follows:

$ openssl ecparam -genkey -name secp256r1 -noout -out ec_privateKey_256.pem
$ openssl ec -in ec_privateKey_256.pem -pubout -out ec_publicKey_256.pem

$ openssl ecparam -genkey -name secp384r1 -noout -out ec_privateKey_384.pem
$ openssl ec -in ec_privateKey_384.pem -pubout -out ec_publicKey_384.pem

$ openssl ecparam -genkey -name secp521r1 -noout -out ec_privateKey_512.pem
$ openssl ec -in ec_privateKey_512.pem -pubout -out ec_publicKey_512.pem

If RS256, RS384 or RS512 are to be used then the private and public keys can be generated as follows:

$ openssl genrsa -out rsa_privateKey.pem 2048
$ openssl rsa -in rsa_privateKey.pem -outform PEM -pubout -out rsa_publicKey.pem

The following is a ridiculously contrived example, but let's say for sake of argument that you are using this package to generate a JWT as part of your authentication process and that the JWT is then to be used for all API calls within a microservices set-up.

The JWT can be generated including a "scopes" claim which reflects which the API(s), role(s) and action(s) that the user has access to. This is inspired by the post on auth0.com

    $payload = array(
        'sub' => 1234567890,
        'scopes' => array('hr' => array('user' => array('create')))
    );
    $jwt = JWT::create($payload);

    $response->header('Authorization', 'Bearer ' . $jwt);
    return $response;

The JWT can then be used for all subsequent API calls and the scopes within the JWT can be verified through the middleware by defining the required scope(s) for specific routes

    Route::get('/', 'SomeController@index')->middleware(['middleware' => 'verifyClaim:hr.user.create,hr.admin']);

In this case, if the JWT contains "scopes" within the payload which match either or both of the scopes defined on the route then the user will be able to access that route.

When using asymmetric algorithms the API that receives the JWT as part of the request only needs the public key to verify the signature.

$ composer test

Please see CONTRIBUTING and CONDUCT for details.

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

• Benjamin Bennett
• All Contributors

This package was inspired by Sean Tymon and Namshi.

The MIT License (MIT). Please see License File for more information.