Basic Auth Middleware for Slim

This middleware implements HTTP Basic Authentication for Slim Framework.

Install

You can install latest version using composer.

$ composer require tuupola/slim-basic-auth

Usage

Configuration options are passed as an array. Only mandatory parameter is users. This is an array where you pass one or more "username" => "password" combinations. Username is the key and password is the value.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ]
]));

With optional path parameter can authenticate only given part of your website. It can be either a string or an array of strings. You can also change the displayed realm using the parameter with same name. Optional callback which is called if authentication succeeds can be added. Callback receives an array containing user and password as argument. Callback is called only if authentication succeeds. If callback returns boolean false authentication is forced to be failed.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin", /* or ["/admin", "/api"] */
    "realm" => "Protected",
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ],
    "callback" => function ($arguments) use ($app) {
        print_r($arguments);
    }
]));

Security

Browsers send passwords over the wire basically as cleartext. You should always use HTTPS. If the middleware detects insecure usage over HTTP it will throw RuntimeException. This rule is relaxed for localhost. To allow insecure usage you must enable it manually by setting secure to false.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "secure" => false,
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ]
]));

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

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "secure" => true,
    "relaxed" => ["localhost", "dev.example.com"],
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ]
]));

Custom authentication methods

Sometimes passing users in an array is not enough. To authenticate against custom datasource you can pass a callable as authenticator parameter. This can be either a class which implements AuthenticatorInterface or anonymous function. Callable receives an array containing user and password as argument. In both cases authenticator must return either true or false.

If you are creating an Enterprise™ software which randomly lets people log in you could use the following.

use \Slim\Middleware\HttpBasicAuthentication\AuthenticatorInterface;

class RandomAuthenticator implements AuthenticatorInterface {
    public function __invoke($arguments) {
        return (bool)rand(0,1);
    }
}

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "realm" => "Protected",
    "authenticator" => new RandomAuthenticator()
]));

Same thing can also be accomplished with anonymous function.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "realm" => "Protected",
    "authenticator" => function ($arguments) use ($app) {
        return (bool)rand(0,1);
    }
]));

Setting response body when authentication fails

By default plugin returns an empty response body with 401 response. You can return custom body using by providing an error handler. This is useful for example when you need additional information why authentication failed.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/api",
    "realm" => "Protected",
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ],
    "error" => function ($arguments) use ($app) {
        $response["status"] = "error";
        $response["message"] = $arguments["message"];
        $app->response->write(json_encode($response, JSON_UNESCAPED_SLASHES));
    }
]));

Usage with PDO

For those in hurry there is a ready made PDO authenticator. It covers most of the use cases. You probably end up implementing your own though.

use \Slim\Middleware\HttpBasicAuthentication\PdoAuthenticator;

$pdo = new \PDO("sqlite:/tmp/users.sqlite");
$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "realm" => "Protected",
    "authenticator" => new PdoAuthenticator([
        "pdo" => $pdo
    ])
]));

For better explanation see Basic Authentication from Database blog post.

Usage with FastCGI

By default Apache does not pass credentials to FastCGI process. If you are using mod_fcgi you can configure authorization headers with:

FastCgiExternalServer /usr/lib/cgi-bin/php5-fcgi -host 127.0.0.1:9000 -pass-header Authorization

If this is not possible workaround is to pass credentials in an environment variable using mod_rewrite.

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

The above rewrite rule should work out of the box. In some cases server adds REDIRECT_ prefix to environment name. In this case or if you want to use nonstandard environment use the parameter called environment.

$app = new \Slim\Slim();

$app->add(new \Slim\Middleware\HttpBasicAuthentication([
    "path" => "/admin",
    "realm" => "Protected",
    "users" => [
        "root" => "t00r",
        "user" => "passw0rd"
    ],
    "environment" => "REDIRECT_HTTP_AUTHORIZATION"
]));

Testing

You can run tests either manually...

$ vendor/bin/phpunit
$ vendor/bin/phpcs --standard=PSR2 src/ -p

... or automatically on every code change.

$ npm install
$ grunt 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.