README

👁 Build Status

An authentication and authorisation middleware for Slim 4 framework.

Installation

composer require madesimple/slim-auth

Authentication

A middleware to determine whether the request contains valid authentication token. The middleware has been designed so that it can easily be extended to:

• handle any type of token retrieval;
• handle any type of validation method; and,
• perform any set of actions if authentication was successful.

To use an Authentication middleware to your Slim application simply:

use Slim\Middleware\Authentication\SimpleTokenAuthentication;
/** @var \Slim\App $app The Slim application */
/** @var string $pattern Pattern for either the group or a route */
/** @var callable $callable A callable for a route */

// Add to all routes:
$app->add(new SimpleTokenAuthentication($app->getContainer(), $options));

// Add to a group of routes:
$app->group($pattern, function () {})
 ->add(new SimpleTokenAuthentication($app->getContainer(), $options));

// Add to a specific route:
$app->get($pattern, $callable)
 ->add(new SimpleTokenAuthentication($app->getContainer(), $options));

Side node: We recommend that if you are going to be adding same authentication to more than more groups/routes to put the middleware in dependencies.php.

Default options for authentication are:

[
 // boolean - whether to enforce an https connection
 'secure' => true,
 // array - list of hostnames/IP addresses to ignore the secure flag
 'relaxed' => ['localhost', '127.0.0.1'],
 // array - list of environment variables to check for the token (set to an empty array to skip)
 'environment' => ['HTTP_AUTHORIZATION', 'REDIRECT_HTTP_AUTHORIZATION'],
 // string - the header to check for the token (set to false, null, or '' to skip)
 'header' => 'X-Auth',
 // string - the regex to match the token ($match[$options['index']] is used as the token)
 'regex' => '/(.*)/',
 // integer - the regex index to use as the token
 'index' => 1,
 // string - the cookie to check for the token (set to false, null, or '' to skip)
 'cookie' => 'X-Auth',
 // string - the identifier for the token in the payload
 'payload' => null,
 // string - the name to store the token in the request attributes
 'attribute' => 'token',
 // object - an instance of a Psr\LoggerInterface
 'logger' => null,
];

When authentication fails the middleware throws an HttpUnauthorizedException is thrown.

SimpleTokenAuthentication

Simple token authentication is an implementation of Authentication which allows the user to provide a callable to validate a token. The callable is passed to Simple token authentication using the option:

[
 // callable - function to validate the token [required]
 'validate' => null,
];

The callable should have the following signature:

function ($token): bool {
 /** @var bool $isValid Populated by this function, true if the token is valid */
 return $isValid;
}

JwtAuthentication

JWT authentication is an implementation of Authentication which allows the user to use JWT as authentication tokens. JWT authentication overrides the default regex, and adds two extra options:

[
 // string - Overrides the default regex
 'regex' => '/Bearer\s+(.*)$/i',

 // string - JWT secret [required]
 'secret' => '',
 // array - list of JWT algorithms [optional]
 'algorithm' => ['HS256', 'HS512', 'HS384'],

];

Authorisation

A middleware to determine whether an authenticated request has authorisation to access the requested route.

When Authorisation fails the middleware throws an HttpForbiddenException exception.

Note: If you need to access the route from within your app middleware you will need to add the Middleware\RoutingMiddleware middleware to your application just before you call run().