bendbennett/JWT

JWT

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).

Prerequisites

PHP 5.6+

Install

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

Configuration for usage with Laravel 5

Edit config/app.php

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,

Edit app/Http/Kernel.php

Include the VerifyClaim class in the routeMiddleware array

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

Publish the config file

$ php artisan vendor:publish

Edit the config/jwtbdb file

algorithm

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

ttl

ttl (time to live) - this is in minutes

requiredClaims

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.

secret

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

privateKey and publicKey

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

Creation of public and private keys for use with asymmetric algorithms

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

ES256

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

ES384

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

ES512

$ 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

Usage

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.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

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

Credits

• Benjamin Bennett
• All Contributors

Inspiration

This package was inspired by Sean Tymon and Namshi.

License

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