Quickstart

This page provides a quick introduction to JWT-Auth and introductory examples. If you have not already installed, JWT-Auth, head over to the Overview page.

This quickstart will use Slim framework as am example but this will work with any PSR-15 compliant framework.

Basic Useage

The below example is the most basic use of the middleware, acting as a global authentication middleware on all routes. by default it will expect a JWT in the Authentication header or cookie named token prefixed with Bearer followed by the token i.e. Bearer xx.yy.zz

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use JimTools\JwtAuth\Middleware\JwtAuthentication;
use JimTools\JwtAuth\Options;

require __DIR__ . '/../vendor/autoload.php';

$app = AppFactory::create();
$app->addRoutingMiddleware();
$errorMiddleware = $app->addErrorMiddleware(true, true, true);

// Register Authentication Middleware
$decoder = new FirebaseDecoder(new Secret($_ENV['JWT_SECRET'], 'HS256'));
$authentication = new JwtAuthentication(new Options(), $decoder);
$app->addMiddleware($authentication);

$app->get('/hello/{name}', function (Request $request, Response $response, $args) {
    $name = $args['name'];
    $response->getBody()->write("Hello, $name");
    return $response;
});

$app->run();

Custom Rules

You may not always want a global authentication on all routes this is where custom rules comes in, the third parameter of JwtAuthentication allow you to specify which routes to authentication. the third argumet should be an array of JimTools\JwtAuth\Rules\RuleInterface

use JimTools\JwtAuth\Rules\RequestMethodRule;
use JimTools\JwtAuth\Rules\RequestPathRule;

$rules = [
  new RequestMethodRule(ignore: ['OPTIONS']),
  new RequestPathRule(paths: ['/'], ignore: ['/auth/login'])
]

// Register Authentication Middleware
$decoder = new FirebaseDecoder(new Secret($_ENV['JWT_SECRET'], 'HS256'));
$authentication = new JwtAuthentication(new Options(), $decoder, $rules);
$app->addMiddleware($authentication);

Out of the box there are two rules provided RequestMethodRule and RequestPathRule, these should cover 90% of all use cases but if you need fine-grained control you can while your own custom rules which impliments the RuleInterface interface.

RequestMethodRule

This rule allows you bypass all request with a specific HTTP method, by default it will ignore OPTION, check out MDN Http Request Methods for more infomation on methods.

RequestPathRule

This rule determines which url paths the authentication will action on, it takes two parameter both expect an array of strings.

paths is a list or URI where the authentication will take act on, this can be a string literal or a regular expression for example.

new RequestPathRule(['/privte', '/users/\d+'])

ignore is a list or URI where authentication will be bypassed, this can by a string literal or a regular expression for example.

new RequestPathRule(['/'], ['/auth/login', '/products/[a-zA-Z0-9_-]]'])

Note

All regular expressions are not treated as case insensative.

Multiple Tokens

If you need to parse multiple token from different source it’s possible, all you need to do is pass multiple secrts to the to the decoder see the below example.

$decoder = new FirebaseDecoder(
  new Secret($_ENV['JWT_ALPHA_SECRET'], 'HS256', 'alpha'),
  new Secret($_ENV['JWT_BETA_SECRET'], 'HS256', 'beta'),
);
$authentication = new JwtAuthentication(new Options(), $decoder);

Warning

when multiple secrets are passsed the kid is required in the token header and in the Secret class. The kid is used by the decoder to determine which secret to use to decode the JWT.