README

Authentication and authorisation middleware for Slim 4 framework.

Installation

composer require madesimple/slim-auth

Authentication

A middleware to determine whether the request contains a 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 the 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 the 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 extension of Authentication which implements validate but adds an abstract function decode. 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'],

];

FirebaseJwtAuthentication is an implementation of JwtAuthentication which uses firebase/php-jwt. If you specify more than one possible algorithm in your options, then your JWT will need to include the kid in the headers. For example:

$jwt1 = \Firebase\JWT\JWT::encode($payload, $secret1, 'HS256', 'kid1')
$jwt2 = \Firebase\JWT\JWT::encode($payload, $secret2, 'HS512', 'kid2')

// ...

$middleware = new \Slim\Middleware\Authentication\FirebaseJwtAuthentication($ci, [
    // ...
    'secret' => [
        'kid1' => $secret1,
        'kid2' => $secret2,
    ],
    'algorithm' => [
        'kid1' => 'HS256',
        'kid2' => 'HS512',
    ],
    // ...

]);

If you only use a single secret but allow multiple algorithms, then the configuration is simpler:

$middleware = new \Slim\Middleware\Authentication\FirebaseJwtAuthentication($ci, [
    // ...
    'secret' => $secret,
    'algorithm' => ['HS256', 'HS512'],
    // ...

]);

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

madesimple / slim-auth

Maintainers

Package info

Statistics

Security