PSR-7 and PSR-15 JWT Authentication Middleware

Mika Tuupola

Last update: Dec 18, 2022

Related tags

Overview

PSR-7 and PSR-15 JWT Authentication Middleware

This middleware implements JSON Web Token Authentication. It was originally developed for Slim but can be used with any framework using PSR-7 and PSR-15 style middlewares. It has been tested with Slim Framework and Zend Expressive.

Heads up! You are reading documentation for 3.x branch which is PHP 7.1 and up only. If you are using older version of PHP see the 2.x branch. These two branches are not backwards compatible, see UPGRADING for instructions how to upgrade.

Middleware does not implement OAuth 2.0 authorization server nor does it provide ways to generate, issue or store authentication tokens. It only parses and authenticates a token when passed via header or cookie. This is useful for example when you want to use JSON Web Tokens as API keys.

For example implementation see Slim API Skeleton.

Install

Install latest version using composer.

$ composer require tuupola/slim-jwt-auth

If using Apache add the following to the .htaccess file. Otherwise PHP wont have access to Authorization: Bearer header.

RewriteRule .* - [env=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Usage

Configuration options are passed as an array. The only mandatory parameter is secret which is used for verifying then token signature. Note again that secret is not the token. It is the secret you use to sign the token.

For simplicity's sake examples show secret hardcoded in code. In real life you should store it somewhere else. Good option is environment variable. You can use dotenv or something similar for development. Examples assume you are using Slim Framework.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

An example where your secret is stored as an environment variable:

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => getenv("JWT_SECRET")
]));

When a request is made, the middleware tries to validate and decode the token. If a token is not found or there is an error when validating and decoding it, the server will respond with 401 Unauthorized.

Validation errors are triggered when the token has been tampered with or the token has expired. For all possible validation errors, see JWT library source.

Optional parameters

Path

The optional path parameter allows you to specify the protected part of your website. It can be either a string or an array. You do not need to specify each URL. Instead think of path setting as a folder. In the example below everything starting with /api will be authenticated. If you do not define path all routes will be protected.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "path" => "/api", /* or ["/api", "/admin"] */
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Ignore

With optional ignore parameter you can make exceptions to path parameter. In the example below everything starting with /api and /admin will be authenticated with the exception of /api/token and /admin/ping which will not be authenticated.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "path" => ["/api", "/admin"],
    "ignore" => ["/api/token", "/admin/ping"],
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Header

By default middleware tries to find the token from Authorization header. You can change header name using the header parameter.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "header" => "X-Token",
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Regexp

By default the middleware assumes the value of the header is in Bearer <token> format. You can change this behaviour with regexp parameter. For example if you have custom header such as X-Token: <token> you should pass both header and regexp parameters.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "header" => "X-Token",
    "regexp" => "/(.*)/",
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Cookie

If token is not found from neither environment or header, the middleware tries to find it from cookie named token. You can change cookie name using cookie parameter.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "cookie" => "nekot",
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Algorithm

You can set supported algorithms via algorithm parameter. This can be either string or array of strings. Default value is ["HS256", "HS512", "HS384"]. Supported algorithms are HS256, HS384, HS512 and RS256. Note that enabling both HS256 and RS256 is a security risk.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub",
    "algorithm" => ["HS256", "HS384"]
]));

Attribute

When the token is decoded successfully and authentication succeeds the contents of the decoded token is saved as token attribute to the $request object. You can change this with. attribute parameter. Set to null or false to disable this behavour

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "attribute" => "jwt",
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

/* ... */

$decoded = $request->getAttribute("jwt");

Logger

The optional logger parameter allows you to pass in a PSR-3 compatible logger to help with debugging or other application logging needs.

use Monolog\Logger;
use Monolog\Handler\RotatingFileHandler;

$app = new Slim\App;

$logger = new Logger("slim");
$rotating = new RotatingFileHandler(__DIR__ . "/logs/slim.log", 0, Logger::DEBUG);
$logger->pushHandler($rotating);

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "path" => "/api",
    "logger" => $logger,
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Before

Before function is called only when authentication succeeds but before the next incoming middleware is called. You can use this to alter the request before passing it to the next incoming middleware in the stack. If it returns anything else than Psr\Http\Message\ServerRequestInterface the return value will be ignored.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub",
    "before" => function ($request, $arguments) {
        return $request->withAttribute("test", "test");
    }
]));

After

After function is called only when authentication succeeds and after the incoming middleware stack has been called. You can use this to alter the response before passing it next outgoing middleware in the stack. If it returns anything else than Psr\Http\Message\ResponseInterface the return value will be ignored.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub",
    "after" => function ($response, $arguments) {
        return $response->withHeader("X-Brawndo", "plants crave");
    }
]));

Note that both the after and before callback functions receive the raw token string as well as the decoded claims through the $arguments argument.

Error

Error is called when authentication fails. It receives last error message in arguments. You can use this for example to return JSON formatted error responses.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub",
    "error" => function ($response, $arguments) {
        $data["status"] = "error";
        $data["message"] = $arguments["message"];
        return $response
            ->withHeader("Content-Type", "application/json")
            ->getBody()->write(json_encode($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT));
    }
]));

Rules

The optional rules parameter allows you to pass in rules which define whether the request should be authenticated or not. A rule is a callable which receives the request as parameter. If any of the rules returns boolean false the request will not be authenticated.

By default middleware configuration looks like this. All paths are authenticated with all request methods except OPTIONS.

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "rules" => [
        new Tuupola\Middleware\JwtAuthentication\RequestPathRule([
            "path" => "/",
            "ignore" => []
        ]),
        new Tuupola\Middleware\JwtAuthentication\RequestMethodRule([
            "ignore" => ["OPTIONS"]
        ])
    ]
]));

RequestPathRule contains both a path parameter and a ignore parameter. Latter contains paths which should not be authenticated. RequestMethodRule contains ignore parameter of request methods which also should not be authenticated. Think of ignore as a whitelist.

99% of the cases you do not need to use the rules parameter. It is only provided for special cases when defaults do not suffice.

Security

JSON Web Tokens are essentially passwords. You should treat them as such and you should always use HTTPS. If the middleware detects insecure usage over HTTP it will throw a RuntimeException. This rule is relaxed for requests on localhost. To allow insecure usage you must enable it manually by setting secure to false.

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secure" => false,
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Alternatively you can list your development host to have relaxed security.

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secure" => true,
    "relaxed" => ["localhost", "dev.example.com"],
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

Authorization

By default middleware only authenticates. This is not very interesting. Beauty of JWT is you can pass extra data in the token. This data can include for example scope which can be used for authorization.

It is up to you to implement how token data is stored or possible authorization implemented.

Let assume you have token which includes data for scope. By default middleware saves the contents of the token to token attribute of the request.

[
    "iat" => "1428819941",
    "exp" => "1744352741",
    "scope" => ["read", "write", "delete"]
]

$app = new Slim\App;

$app->add(new Tuupola\Middleware\JwtAuthentication([
    "secret" => "supersecretkeyyoushouldnotcommittogithub"
]));

$app->delete("/item/{id}", function ($request, $response, $arguments) {
    $token = $request->getAttribute("token");
    if (in_array("delete", $token["scope"])) {
        /* Code for deleting item */
    } else {
        /* No scope so respond with 401 Unauthorized */
        return $response->withStatus(401);
    }
});

Testing

You can run tests either manually or automatically on every code change. Automatic tests require entr to work.

$ make test

$ brew install entr
$ make watch

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

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

Comments

Slim 3 passthrough all routes when installed in subfolder

When no public routes set, middleware runs ok, but when add the following:

    "rules" => [
        new \Slim\Middleware\JwtAuthentication\RequestPathRule([
            "path" => "/",
            "passthrough" => ["/api/ping"]
        ]),
        new \Slim\Middleware\JwtAuthentication\RequestMethodRule([
            "passthrough" => ["OPTIONS"]
        ])
    ]

Middleware just don't check JWT and passthrough all routes. The same code works fine on Slim 2, but Slim 3 don't.

Ps: Works fine on php built-in server, (without any dot (.) char in uri params), Apache doesn't work, passthrough all routes. Current .htaccess:

<IfModule mod_rewrite.c>
    RewriteEngine On

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [QSA,L]
    RewriteRule .* - [env=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
</IfModule>

bug

opened by ronaldo-systemar 29

Token not found / apache / php

On my Slim setup (v3) with php 5.6.14, token can't be found, i need to get it via apache_request_headers() and set $_SERVER['HTTP_AUTHORIZATION'] in index.php. I've tried different .htaccess directives like the one provided here without success.

Would it be possible to check if token can be found in 'apache_request_headers' ?

/**
 * Fetch the access token
 *
 * @return string|null Base64 encoded JSON Web Token or null if not found.
 */
public function fetchToken(RequestInterface $request) 
{

   /* If using PHP in CGI mode and non standard environment */
    $server_params = $request->getServerParams();
    if (isset($server_params[ $this->options["environment"]])) 
    {
        $message = "Using token from environent";
        $header = $server_params[ $this->options["environment"]];
    }

    $header = $request->getHeader("Authorization");
    if (isset($header[0])) 
    {
        $message = "Using token from request header";
        $header = isset($header[0]) ? $header[0] : "";
    }

    /* FIX for apache */
    if (function_exists('apache_request_headers')) 
    {
        $headers = apache_request_headers();
        $header = isset($headers['Authorization']) ? $headers['Authorization'] : "";
    }

    if (preg_match("/Bearer\s+(.*)$/i", $header, $matches)) 
    {
        $this->log(LogLevel::DEBUG, $message);
        return $matches[1];
    }

    /* Bearer not found, try a cookie. */
    $cookie_params = $request->getCookieParams();

    if (isset($cookie_params[ $this->options["cookie"]])) 
    {
        $this->log(LogLevel::DEBUG, "Using token from cookie");
        $this->log(LogLevel::DEBUG, $cookie_params[ $this->options["cookie"]]);
        return $cookie_params[ $this->options["cookie"]];
    };

    /* If everything fails log and return false. */
    $this->message = "Token not found";
    $this->log(LogLevel::WARNING, $this->message);
    return false;
}

enhancement

opened by zeced 21

When I add jwt Middleware Its showing some error How to Solve this?
When I add jwt Middleware Its showing some error in every routes, but ignore routes are working fine @tuupola How to Solve this?

after update , my composer v2

`$app->add(new Tuupola\Middleware\JwtAuthentication([ "ignore"=>["/auth/login","/auth/register"], "secret"=> "Token", "error"=>function ($response,$arguments) { $data["success"]= false; $data["response"]=$arguments["message"]; $data["status_code"] = "401";

return $response->withHeader("Content-type","application/json") ->getBody()->write(json_encode($data,JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT)); } ]));

`
opened by tonmooy 15

$Fatal error: Class 'Slim\Middleware\JwtAuthentication' not found$

Fatal error: Class 'Slim\Middleware\JwtAuthentication' not found

Middleware.php


// Application middleware

// e.g: $app->add(new \Slim\Csrf\Guard);
use Tuupola\Middleware\HttpBasicAuthentication;

$container = $app->getContainer();
$container['logger'] = function($c) {
 $logger = new \Monolog\Logger('my_logger');
 $file_handler = new \Monolog\Handler\StreamHandler("../logs/app.log");
 $logger->pushHandler($file_handler);
 return $logger;
};

$container["jwt"] = function ($container) {
    return new StdClass;
   };

   $app->add(new \Slim\Middleware\JwtAuthentication([
    "path" => "/",
    "logger" => $container[‘logger’],
    "secret" => "123456789helo_secret",
    "rules" => [
    new \Slim\Middleware\JwtAuthentication\RequestPathRule([
    "path" => "/",
    "passthrough" => ["/token", "/not-secure", "/home"]
    ]),
    new \Slim\Middleware\JwtAuthentication\RequestMethodRule([
    "passthrough" => ["OPTIONS"]
    ]),
    ],
    "callback" => function ($request, $response, $arguments) use ($container) {
    $container["jwt"] = $arguments["decoded"];
    },
    "error" => function ($request, $response, $arguments) {
    $data["status"] = "error";
    $data["message"] = $arguments["message"];
    return $response
    ->withHeader("Content-Type", "application/json")
    ->write(json_encode($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT));
    }
   ]));

Where is the problem? I Slim 3 and composer

question

opened by fcolasante 13

Slim v4 support

Any plans to support the upcomming Slim v4?

I'm currently starting to build an app based on v3, but decided to switch to Slim v4 (http://slim-website.lgse.com/docs/v4/start/upgrade.html), so it might be a good opportunity to also help with the integration, I have not yet startet to investigate whether the changes in Slim v4 actually mean any changes to this middleware are needed.

opened by dakujem 12
Call Middleware after Verification

I would like to do the following

Verify Token --> Call Middleware no matter what the result is (as long it's not error)

How would I go about doing this?

I tried with the before parameter and didn't get anywhere.

Reason for this is that I'm using this on a website, so I don't want people getting plain 401 errors. I want them to be redirected to the login page or for the backend API to be actually given the 401 error, which I can do in the middleware by calling the route name.

Thank You
question

opened by citadelnetworks 12
Token does not expire

HI, my tokens are not expiring... although they have the default exp set at now+2hours, I'm using a token that had expired 36 hours ago... in the verify method it returns false, but the middleware does not returning any complain about the expiracy... How can I solve this?

opened by lfelisiak 12
404 error on request

Hi, i get a 404 error when i make a get request to the api when using with angular 2, at first i felt it was problem with angular 2 service. But when i tested with other api's it works, but gives 404 error with a response saying {message: "Not found"} Its an issue on the api side what am i doing wrong, is it the cors issue, Please help

opened by crimsonmoin 12
Passing rules in an array always returns 401
I would like to redirect the user to a page when the error callbeck gets called. Currently it's not possible because a 401 status gets attacked to the response (which is ok). So currently it's not possible, right?

Maybe a feature for the next version to set an option of the 401 status gets added automaticly or not.

Or is there a workaround for this?

"error" => function ($request, $response, $arguments) use ($container) { return $response->withRedirect( "my/target/path" ); },
bug
opened by X-Tender 11
Allow Multiple Secrets
I can't find this in the documentation, so I was wondering how one would go about accepting multiple JWT Secrets. For example, I would like to generate a new secret for every client who I give access.

Client1 => 'client1secret' Client2 => 'client2secret'

Is this possible?
question
opened by SmoshySmosh 11

$request->getAttribute("token"); - not works in my handler

Hello,

I configured the middleware, the authentication works perfectly but i cannot access the decoded data in the "token" attribute.

Can somebody please help me out?

index.php

$routes = simpleDispatcher(function (RouteCollector $r) {                                                                                                     
    $r->get('/', MainPage::class);                                                                                                                            
    $r->post('/token', Token::class);                                                                                                                         
    $r->get('/info', Info::class);                                                                                                                            
}); 
...
$middlewareQueue = [                                                                                                                             
    new FastRoute($routes),                                                                                                                      
    new JwtAuthentication($configJwt),                                                                                                           
    new RequestHandler($container),                                                                                                              
];                                                                                                                                               
                                                                                                                                                 
$requestHandler = new Relay($middlewareQueue);                                                                                                   
$response = $requestHandler->handle($request);

I am trying to read the decoded token data in Info.php

class Info                                                                                                                                                      
  {                                                                                                                                                               
      private RequestInterface $request;                                                                                                                          
      private ResponseInterface $response;                                                                                                                        
                                                                                                                                                                  
      public function __construct(RequestInterface $request, ResponseInterface $response)                                                                         
      {                                                                                                                                                           
          $this->request = $request;                                                                                                                              
          $this->response = $response;                                                                                                                            
      }                                                                                                                                                           
                                                                                                                                                                  
      public function __invoke(): ResponseInterface                                                                                                               
      {                                                                                                                                                           
          $response = $this->response->withHeader('Content-Type', 'application/json');                                                                            
                                                                                                                                                                  
          $ret = $this->request->getAttribute('token');                                                                                                           
          $response->getBody()->write(json_encode($ret));     
// ret = null                                                                                                    
                                                                                                                                                                  
          return $response;                                                                                                                                       
      }                                                                                                                                                           
  }     

 [attributes:Laminas\Diactoros\ServerRequest:private] => Array
 (
 )

what am i doing wrong here? thanks

opened by nrob81 10

Starting with `3.2.0` it is possible to pass in array of secret keys.

    > Starting with `3.2.0` it is possible to pass in array of secret keys. The middleware then chooses the correct key based on the `kid` claim in the token header. For example:

$middleware = new JwtAuthentication([
    "secret" => [
        "acme" =>"supersecretkeyyoushouldnotcommittogithub",
        "beta" =>"anothersecretkeyfornevertocommittogithub"
    ]
]);

Token with this header would use the supersecretkeyyoushouldnotcommittogithub as secret key.

{
  "typ": "JWT",
  "alg": "HS256",
  "kid": "acme"
}

Is it possible when no kid is given we can fall back on a default key?

Originally posted by @Dadinos in https://github.com/tuupola/slim-jwt-auth/issues/45#issuecomment-1273067475

opened by Dadinos 4

Authentication middleware should NOT interfere with Authorization
Hi,

Slim-jwt-auth is "Authentication middleware": This middleware implements JSON Web Token Authentication.

Authentication should:

parse and validate token if found

add identity of the user to Request (if the token is valid and found)

Authentication SHOULD NOT:

prevent any action

return 401

disallow going to any route

Because it's part of the process which should be handled by AUTHORIZATION middleware.

slim-jwt-auth is authentication middleware , there are several good reasons, why you should not interchange / mix these two terms.

Please do not provide any "authorization" / denial service inside Authentication middleware, it is wrong place to do that and you usually want to sort your middlewares in this way:

...

Authentication (parse and validate identity)

Routing

Authorization

Authentication / Authentication should be split to 2 middlewares and named correctly.

Preventing routes in "authentication" middleware is wrong.
opened by montella1507 2
How do you allow only some get routes to have auth
I'm making an API where some data is publicly available for my site and some need auth. I know I can add this,

$app->add(new Tuupola\Middleware\JwtAuthentication([ "rules" => [ new Tuupola\Middleware\JwtAuthentication\RequestPathRule([ "path" => "/", "ignore" => [] ]), new Tuupola\Middleware\JwtAuthentication\RequestMethodRule([ "ignore" => ["OPTIONS", "GET"] ]) ] ]));

This allows all GET methods to have no auth on them. so is there a way to specify /projectData as a GET route that has no auth but /projetData as a POST, PUT, PATCH, DELETE routes have auth on them
opened by rodude123 3
How to tackle with 2 authorization cookies

Is there any way to handle tokens from 2 different token values? Any one is present at a time. This is required for session cookies for different type of user.

For example, buyer login has a cookie with name buyer-token and seller login has a cookie with name seller-token.

If any one cookie is present than user should be authenticated.

Anyway to achieve this?

opened by gohelkiran30 2

Upgrading firebase/php-jwt to v6

Upgrading firebase/php-jwt to v6 this has a significant change in usage, the secret and algorithm need to be known a head of time to build the key.

changes now manipulate the algorithm option when only one secret is provided.

[
    'secret' => [
        'foo' => 'keepItSecret',
        'bar' => 'tooManySecrets',
    ],
    'algorithm' => [
        'HS256',
    ],
]

will become

[
    'secret' => [
        'foo' => 'keepItSecret',
        'bar' => 'tooManySecrets',
    ],
    'algorithm' => [
        'foo' => 'HS256',
        'bar' => 'HS256',
    ],
]

closes (#217)

opened by JimTools 0

Owner

Mika Tuupola

GitHub https://appelsiini.net/projects/slim-jwt-auth

Laravel JWT-Authentication API starter kit for rapid backend prototyping.

Laravel JWT API A Laravel JWT API starter kit. Features Laravel 8 Login, register, email verification and password reset Authentication with JWT Socia

3 Nov 6, 2022

Single file PHP that can serve as a JWT based authentication provider to the PHP-CRUD-API project

163 Dec 18, 2022

It's a Laravel 8 authentication markdown that will help you to understand and grasp all the underlying functionality for Session and API Authentication

About Auth Starter It's a Laravel 8 authentication markdown that will help you to understand and grasp all the underlying functionality for Session an

10 Aug 3, 2022

Rinvex Authy is a simple wrapper for @Authy TOTP API, the best rated Two-Factor Authentication service for consumers, simplest 2fa Rest API for developers and a strong authentication platform for the enterprise.

Rinvex Authy Rinvex Authy is a simple wrapper for Authy TOTP API, the best rated Two-Factor Authentication service for consumers, simplest 2fa Rest AP

34 Feb 14, 2022

JWT auth for Laravel and Lumen

JWT Artisan Token auth for Laravel and Lumen web artisans JWT is a great solution for authenticating API requests between various services. This packa