Slim Auth

Slim Auth is an authorization and authentication library for the Slim Framework.
Authentication is provided by the Zend Framework Zend\Authentication
component, and authorization by the Zend Framework Zend\Permissions\Acl component.

Fair Warning: Documentation Mostly Complete

Slim Auth is fully functional and production ready (I’ve used it in production
in multiple projects), but this documentation is incomplete. (Current status of
the documentation is ~90% complete.)

If you’re familiar with Zend\Authentication and Zend\Permissions\Acl, you’ll be able to implement the library without any trouble. Otherwise, you might want to wait for the docs to be completed (no ETA) or open a GitHub issue with any questions or problems you encounter.

Caveat emptor and all that.

Slim SessionCookie No Longer Recomended

TL;DR: You will experience unexpected behavior if you use
Zend\Authentication\Storage\Session as your auth storage and
Slim\Middleware\SessionCookie to provide encrypted cookies when your Slim
version is >= 2.6.

Earlier versions of this documentation (and the sample implementation)
demonstrated the use of Slim’s SessionCookie Middleware as a way to handle session storage in concert with Zend Session. As of Slim 2.6.0,
Zend Session and Slim’s SessionCookie middleware no longer play well together,
and I’ve opted for a Zend Session only approach.

Requirements

Slim Auth works with all versions of Slim 2 >= 2.4.2. Slim Auth has not been
tested against the upcoming Slim 3 release.

Example Implementation

I’ve put together an example implementation to demonstrate the library in
action. The example implementation can be found here.

Installation

Installation is provided via Composer.

First, install Composer.

curl -s https://getcomposer.org/installer | php

Then install Slim Auth with the following Composer command.

composer require jeremykendall/slim-auth

Finally, add this line at the top of your application’s index.php file:

require 'vendor/autoload.php';

Preparing Your App For Slim Auth

Database

Your database should have a user table, and that table must have a role
column. The contents of the role column should be a string and correspond to
the roles in your ACL. The table name and all other column names are up to you.

Here’s an example schema for a user table. If you don’t already have a user
table, feel free to use this one:

CREATE TABLE IF NOT EXISTS [users] (
    [id] INTEGER NOT NULL PRIMARY KEY,
    [username] VARCHAR(50) NOT NULL,
    [role] VARCHAR(50) NOT NULL,
    [password] VARCHAR(255) NULL
);

ACL

An Access Control List, or ACL, defines the set of rules that determines which group
of users have access to which routes within your Slim application. Below is a very simple example ACL. Please pay special attention to the comments.

Please refer to the Zend\Permissions\Acl documentation for complete details on using the Zend Framework ACL component.

namespace Example;

use Zend\Permissions\Acl\Acl as ZendAcl;

class Acl extends ZendAcl
{
    public function __construct()
    {
        // APPLICATION ROLES
        $this->addRole('guest');
        // member role "extends" guest, meaning the member role will get all of 
        // the guest role permissions by default
        $this->addRole('member', 'guest');
        $this->addRole('admin');

        // APPLICATION RESOURCES
        // Application resources == Slim route patterns
        $this->addResource('/');
        $this->addResource('/login');
        $this->addResource('/logout');
        $this->addResource('/member');
        $this->addResource('/admin');

        // APPLICATION PERMISSIONS
        // Now we allow or deny a role's access to resources. The third argument
        // is 'privilege'. We're using HTTP method as 'privilege'.
        $this->allow('guest', '/', 'GET');
        $this->allow('guest', '/login', array('GET', 'POST'));
        $this->allow('guest', '/logout', 'GET');

        $this->allow('member', '/member', 'GET');

        // This allows admin access to everything
        $this->allow('admin');
    }
}

The Guest Role

Please note the guest role. You must use the name guest as the role
assigned to unauthenticated users. The other role names are yours to choose.

Acl “Privileges”

IMPORTANT: The third argument to Acl::allow(), ‘privileges’, is either a
string or an array, and should be an HTTP verb or HTTP verbs respectively. By
adding the third argument, you are restricting route access by HTTP method. If
you do not provide an HTTP verb or verbs, you are allowing access to the
specified route via all HTTP methods. Be extremely vigilant here. You
wouldn’t want to accidentally allow a ‘guest’ role access to an admin DELETE
route simply because you forgot to explicitly deny the DELETE route.

Configuring Slim Auth: Defaults

Now that you have a user database table with a role column and an ACL, you’re
ready to configure Slim Auth and add it to your application.

First, add use statements for the PasswordValidator (from the
Password Validator library), the PDO adapter, and the Slim Auth Bootstrap.

use JeremyKendall\Password\PasswordValidator;
use JeremyKendall\Slim\Auth\Adapter\Db\PdoAdapter;
use JeremyKendall\Slim\Auth\Bootstrap;

Next, create your Slim application.

$app = new \Slim\Slim();

Authentication Adapter

From the Zend Authentication documentation:

Zend\Authentication adapters are used to authenticate against a particular
type of authentication service, such as LDAP, RDBMS, or file-based storage.

Slim Auth provides an RDBMS authentication adapter for PDO. The constructor
accepts five required arguments:

• A \PDO instance
• The name of the user table
• The name of the identity, or username, column
• The name of the credential, or password, column
• An instance of JeremyKendall\Password\PasswordValidator

$db = new \PDO(<database connection info>);
$adapter = new PdoAdapter(
    $db, 
    <user table name>, 
    <identity column name>, 
    <credential column name>, 
    new PasswordValidator()
);

NOTE: Please refer to the Password Validator documentation for more
information on the proper use of the library. If you choose not to use the
Password Validator library, you will need to create your own authentication
adapter.

Putting it all Together

Now it’s time to instantiate your ACL and bootstrap Slim Auth.

$acl = new \Namespace\For\Your\Acl();
$authBootstrap = new Bootstrap($app, $adapter, $acl);
$authBootstrap->bootstrap();

Login Route

You’ll need a login route, of course, and it’s important that you name your
route login using Slim’s Route Names feature.

$app->map('/login', function() {})->via('GET', 'POST')->name('login');

This allows you to use whatever route pattern you like for your login route.
Slim Auth will redirect users to the correct route using Slim’s urlFor()
Route Helper.

Here’s a sample login route:

// Login route MUST be named 'login'
$app->map('/login', function () use ($app) {
    $username = null;

    if ($app->request()->isPost()) {
        $username = $app->request->post('username');
        $password = $app->request->post('password');

        $result = $app->authenticator->authenticate($username, $password);

        if ($result->isValid()) {
            $app->redirect('/');
        } else {
            $messages = $result->getMessages();
            $app->flashNow('error', $messages[0]);
        }
    }

    $app->render('login.twig', array('username' => $username));
})->via('GET', 'POST')->name('login');

Logout Route

As authentication stores the authenticated user’s identity, logging out
consists of nothing more than clearing that identity. Clearing the identity is
handled by Authenticator::logout.

$app->get('/logout', function () use ($app) {
    $app->authenticator->logout();
    $app->redirect('/');
});

And Done

That should get you most of the way. I’ll complete documentation as soon as I’m
able, but can’t currently commit to an ETA. Again, please feel free to open and
issue with any questions you might have regarding implementation.

Thanks for considering Slim Auth for your project.