Tutorials

Zend Framework Blog Application Tutorial – Part 7: Authorization with Zend_Acl and Revised Styling

Oct 16, 2008 insic 5 Comments

This entry concerns authorization. We previously covered how to authenticate an author to the blog, but we still have nothing ensuring only authenticated authors can access the new Administration Module. This is the domain of Zend_Acl, an implementation of an Access Control List system which limits access to resources by the roles assigned to a user.

In the final section of this entry, we take a small detour into the world of CSS (which rarely works out for me ;-)) where I’ll apply some small changes to our Layouts and add two new stylesheets. Once these are added, our infant blog application will look slightly more presentable than it’s current nakedness.

Step 1: Understanding Access Control Lists (ACL)

It can be a bit confusing to face off against ACL if you’re new to the subject. In essence all ACL does is keep track of resources and roles.

As to what a resource is, it is anything to which access can be allowed or denied. For our blog application, I could decide that the Administration Module is itself one resource. From there I can restrict all access to that entire Module, including all it’s Controller classes and Action methods (which are part of that single Resource). Or perhaps I could determine that only one Action method in the whole Module is a specific Resource, bearing in mind that Resources are nestable (i.e. a basket is a Resource, and each egg it holds are also discrete Resources). Since each Resource can be given differing access rules, you can globally prevent non-author users from accessing the Administration Module, but maybe allow some registered users access to specific Actions in that Module as an exception to the global rule.

Banner

A lot of the time managing global rules, and then applying exception rules, is how ACL works in practice.

Explaining a Role is even simpler. Any visitor to the application can be assigned a Role which ACL rules may use to define that user’s access to Resources. Typically the first Role everyone will receive is “guest”. From there you can escalate Roles to offer a visitors a greater degree of access to Resources. Any user can be given multiple Roles even. For example, if an author visits the blog they start with the role of “guest” but after authentication we might grant them the additional role of “author”. If Roles dictate specific but limited responsibilities (perhaps there’s an “author” and “editor” Roles) you might decide to start tracking roles more elaborately, in a database possibly.

Going a bit further, if our Administration Module is a Resource called “admin” then we can decide that the only Role with access to it will be the “author” Role. Since our user has been authenticated and granted the “author” Role (either post-authentication or permanently recorded on the database), they can access the Administration Module.

Finally is the concept of Privileges. Just because you can access a Resource, does not instantly mean you should have total uncontrolled access to it. You can limit control over a Resource using Privileges. Perhaps an Author can access the Admin Module (represented by an Admin Resource) but we want to deny Authors the privilege of deleting entries from the database.

Step 2: A Little Planning Goes A Long Way

Before we leap into the fray like a demented action hero, let’s set out exactly what we’re aiming for.

Since our blog is a relatively simple application, we really only need two Roles to start with. We’ll call these guest and author. This may change in the future, perhaps we could allow for multiple Authors but one Editor capable of editing all posts. In that case we’d need to pick apart how that’s implemented. But for now, two Roles is just fine.

As for Resources, the first is the public facing facade of our application where entries are displayed, logins performed, and comments made. The second is the Administration Module. Again, we could be more elaborate but let’s not overcomplicate the application until we’re forced to ;-). This suggests we only have two Resources: the Default Module and the Administration Module. Remember that the Default Module comprises everything not assigned to a specific Module (like our Admin Module with its own separate tree of Controllers and Views).

The rules falling out form this quick analysis are simple.

1. Guests can access the Default Module
2. Authors can access the Default Module
3. Guests cannot access the Administration Module
4. Authors can access the Administration Module

Step 3: Storing Rules in a Class

There is no specific backend storage for Zend_Acl which since it is a serialisable class can be simply serialised and stored in anything from a database to a file for later consumption. To keep things simple I’ll just implement a class defining the relationship between Roles and Resources as described above. You’ll note we are not using Privileges, since access to a Resource assumes the accessing Role has all possible Privileges by default.

Start by creating a new file at /library/ZFBlog/Acl.php:

<?php

class ZFBlog_Acl extends Zend_Acl
{

    public function __construct(Zend_Auth $auth)
    {
        // Add Resources

        // Resource #1: Default Module
        $this->add(new Zend_Acl_Resource(‘default’));
        // Resource #2: Admin Module
        $this->add(new Zend_Acl_Resource(‘admin’));

        // Add Roles

        // Role #1: Guest
        $this->addRole(new Zend_Acl_Role(‘guest’));
        // Role #2: Author (inherits from Guest)
        $this->addRole(new Zend_Acl_Role(‘author’), ‘guest’);

        // Assign Access Rules

        // Rule #1 & #2: Guests can access Default Module (Author inherits this)
        $this->allow(‘guest’, ‘default’);
        // Rule #3 & #4: Authors can access Admin Module (Guests denied by default)
        $this->allow(‘author’, ‘admin’);
    }
}

One confusing point I’ve seen asked is whether Resources explicitly refer to Modules, Controllers or Actions. They don’t – the names used here are pure convention. A resource is a virtual item. Zend_Acl doesn’t know if a Resource is a Module, Controller or Action since that’s a decision we make when we check the ACL rules later. What we’ll do then is detect what Module a request for, and specifically carry out an ACL check for the Resource created here to refer to that Module, i.e. the connection between a real Module name and an ACL Virtual Resource is determined entirely by us at checking time.

Probably the biggest area of confusion is that its so common to consider Resources as Controllers, and Privileges as Actions, that people don’t realise this is pure convention. Someone seeing $this->allow('author', 'entry', array('create', 'edit', 'delete')) would interpret that Authors are allowed access to the Entry Controller with privileges sufficient to create, edit or delete entries. That is only the case if, and when, your ACL logic determines this is how the rule is interpreted.

To prove a point, where do Modules fit? They don’t. There is no Module parameter for Zend_Acl::allow(). You could append ACL interpretive logic where a Resource called “admin|entry” refers to the Entry Controller of an Admin Module which once again emphasises that a Resource is completely virtual. It is only what you interpret it to be and has no preconceived relationship with MVC. For all you care a Resource could be absolutely anything that is accessible only by passing through the ACL checkpoint.

Step 4: Implementing ACL using a custom Front Controller Plugin

The problem with ACL is that it’s one of those always-on checks. Every single request needs to be checked to ensure that the requesting user has a Role which allows them to access the Resource (i.e. the Module, Controller or Action) being requested.

By stringing together the requirements (interacts with request data, operates on all requests, occurs prior to Controller execution) we realise that the best way of accomplishing this is to add a Front Controller plugin implementing the preDispatch() method.

Create a new file at /library/ZFBlog/Controller/Plugin/Acl.php.

Once again we’re using the PEAR Convention and we will continue to mirror the organisation of Zend Framework classes.

<?php

class ZFBlog_Controller_Plugin_Acl extends Zend_Controller_Plugin_Abstract
{

    protected $_auth = null;

    protected $_acl = null;

    public function __construct(Zend_Auth $auth, Zend_Acl $acl)
    {
        $this->_auth = $auth;
        $this->_acl = $acl;
    }

    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        // Before you lot start, this is the laziest possible
        // means of assigning roles. Hands up – I’m guilty!
        // Store to the Author table if you prefer.
        if ($this->_auth->hasIdentity()) {
            $role = ‘author’;
        } else {
            $role = ‘guest’;
        }
       
        // Mapping to determine which Resource the current
        // request refers to (really simple for this example!)
        $resource = $request->module;

        if (!$this->_acl->has($resource)) {
            $resource = null;
        }

        // ACL Access Check
        if (!$this->_acl->isAllowed($role, $resource)) {
            if ($this->_auth->hasIdentity()) {
                // authenticated, denied access, forward to index
                $request->setModuleName(‘default’);
                $request->setControllerName(‘index’);
                $request->setActionName(‘index’);
            } else {
                // not authenticated, forward to login form
                $request->setModuleName(‘default’);
                $request->setControllerName(‘author’);
                $request->setActionName(‘login’);
            }
        }
    }
}

Look Ma, it’s another plugin!

If you haven’t already guessed from reading this series so far, a lot of great things happen when you take the time to write plugins and helpers for the Zend Framework.

This Front Controller Plugin is really simple. It checks whether the current user is authenticated or not. If they are authenticated, it assumes they are an Author – not a Guest. Now assumptions are not very pretty, but it’s a blog with two roles. If you had a slightly more complex scenario (say we had Guest, Author and Editor roles) you could instead maintain Roles in the database for querying by this plugin. For example, add a new “role” field to our author table on the database – the data from it will get stored by Zend_Auth during authentication which, as you see, is accessible by this plugin :-).

After Roles are assumed, we grab the name of the current Module and since we have a convention that Resource names map one-for-one to Module names, it’s a simple check to see if the current user’s Role allows them access to that Resource. If it does, we simply do nothing and let control pass back to the Front Controller. If access is denied we have two branches – authenticated users are just kicked back to the index page (part of our default Module) while unauthenticated users are redirected to the login page for Authors.

Note: Setting the Module name on the request object for forwarding is required when using Modules. That includes setting references to non-moduled controllers/actions with the Module name of “default”.

Of course there are more complex scenarios again. What if the resource is not a Module, but a specific Action on a specific Controller within a Module? Obviously such a simple plugin as above would fall flat and need to be scraped off the floor. Again this is not dictated to you by the Zend Framework manual. It’s usually typical to make use of Privileges in Resources and interpret these as Actions. And as explained earlier you can use a “admin|entry” convention for the Module/Controller pairing.

Step 5: Initialising the Front Controller Plugin

Before our plugin is even used, we need to register it with the Front Controller. This is another change to our Bootstrap class! The new method setupAcl is at the bottom of the file.

<?php

require_once ‘Zend/Loader.php’;

class Bootstrap
{

    public static $frontController = null;

    public static $root = ;

    public static $registry = null;

    public static function run()
    {
        self::prepare();
        $response = self::$frontController->dispatch();
        self::sendResponse($response);
    }

    public static function setupEnvironment()
    {
        error_reporting(E_ALL|E_STRICT);
        ini_set(‘display_errors’, true);
        date_default_timezone_set(‘Europe/London’);
        self::$root = dirname(dirname(<u>_FILE_</u>));
    }

    public static function prepare()
    {
        self::setupEnvironment();
        Zend_Loader::registerAutoload();
        self::setupRegistry();
        self::setupConfiguration();
        self::setupFrontController();
        self::setupView();
        self::setupDatabase();
        self::setupAcl();
    }

    public static function setupFrontController()
    {
        self::$frontController = Zend_Controller_Front::getInstance();
        self::$frontController->throwExceptions(true);
        self::$frontController->returnResponse(true);
        self::$frontController->setControllerDirectory(
            array(
                ‘default’ => self::$root . ‘/application/controllers’,
                ‘admin’ => self::$root . ‘/application/admin/controllers’
            )
        );
        self::$frontController->setParam(‘registry’, self::$registry);
    }

    public static function setupView()
    {
        $view = new Zend_View;
        $view->setEncoding(‘UTF-8′);
        $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
        Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
        Zend_Layout::startMvc(
            array(
                ‘layoutPath’ => self::$root . ‘/application/views/layouts’,
                ‘layout’ => ‘common’,
                ‘pluginClass’ => ‘ZFBlog_Layout_Controller_Plugin_Layout’
            )
        );
    }

    public static function sendResponse(Zend_Controller_Response_Http $response)
    {
        $response->setHeader(‘Content-Type’, ‘text/html; charset=UTF-8′, true);
        $response->sendResponse();
    }

    public static function setupRegistry()
    {
        self::$registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS);
        Zend_Registry::setInstance(self::$registry);
    }

    public static function setupConfiguration()
    {
        $config = new Zend_Config_Ini(
            self::$root . ‘/config/config.ini’,
            ‘general’
        );
        self::$registry->configuration = $config;
    }

    public static function setupDatabase()
    {
        $config = self::$registry->configuration;
        $db = Zend_Db::factory($config->db->adapter, $config->db->toArray());
        $db->query(“SET NAMES ‘utf8′”);
        self::$registry->database = $db;
        Zend_Db_Table::setDefaultAdapter($db);
    }

    public static function setupAcl()
    {
        $auth = Zend_Auth::getInstance();
        $acl = new ZFBlog_Acl($auth);
        self::$frontController->setParam(‘auth’, $auth);
        self::$frontController->setParam(‘acl’, $acl);
        self::$frontController->registerPlugin(
            new ZFBlog_Controller_Plugin_Acl($auth, $acl)
        );
    }

}

In case they are needed for a more specific use case in a controller, I’ve added both the authentication and authorisation objects as Front Controller parameters.

Go boot up http://zfblog/admin for a test drive. If you have previously logged in, you can logout using http://zfblog/author/logout manually (it’s not part of our View yet).

Step 6: And Now For Something Completely Different…

With ACL implemented I find myself at a loose end. So I spent some time putting together two new stylesheets to add some colour and life to this application. You’ll need two new files:

/public/css/style.css
/public/css/ie.css

The first may already exist from an earlier Part of this series.

Edit style.css to contain the following CSS. I won’t explain it – this, thankfully, is not a CSS blog ;-).

body {
    margin: 0;
}
#content {
    min-height: 50em;
}
#header {
        background: #303030;
}
#header h1 {
        float: left;
        width: 235px;
        height: 80px;
        margin: 0;
}
#header a {
    color: #AAA;
    text-decoration: none;
}
#footer {
    clear: both;
    width: 100%;
    margin: 0;
    padding: 15px 0;
    border-top: 1px solid #000;
    background: #303030;
    text-align: center;
    color: #AAA;
}
fieldset {
    float: left;
    clear: both;
    width: 100%;
    margin: 0 0 1.5em 0;
    padding: 0;
    border: 1px solid #BFBAB0;
    background-color: #F2EFE9;
}
fieldset.submit {
    float: none;
    width: auto;
    border-style: none;
    padding-left: 13.5em;
    background-color: transparent;
}
legend {
    margin-left: 1em;
    padding: 0;
    color: #000;
    font-weight: bold;
}
fieldset ol {
    padding: 1em 1em 0 1em;
    list-style: none;
}
fieldset li {
    float: left;
    clear: left;
    width: 100%;
    padding-bottom: 1em;
}
label {
    float: left;
    width: 10em;
    margin-right: 1em;
    text-align: right;
}
label strong {
    display: block;
    color: #C00;
    font-size: 85%;
    font-weight: normal;
    text-transform: uppercase;
}
label em {
    display: block;
    color: #060;
    font-size: 85%;
    font-style: normal;
    text-transform: uppercase;
}

Now repeat after me: “Paddy is not a designer!”. I can’t say this is the most spectacular CSS ever written when it’s probably more in the opposite direction. But it works. I’m pretty sure it does anyway. Fingers crossed! There might be some IE7 issues because my conditional doesn’t specify a version so check back with subversion in a while if so.

We’re not done yet. We need to make two more edits to each of our previous Layout templates. Here’s the amended excerpt for each. It is identical for both /application/views/layouts/common.phtml and /application/admin/views/layouts/admin.phtml. Now since it’s identical we know we have some duplication in our layouts, which is undesirable, but we’ll fix that another day.

<head>
    <meta http-equiv=“Content-Type” content=“text/html; charset=utf-8″ />
    <meta name=“language” content=“en” />
    <title><?php echo $this->escape($this->title) ?></title>
    <link rel=“stylesheet” href=“/css/blueprint/screen.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/style.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/blueprint/print.css” type=“text/css” media=“print”>
    <!–[if IE]>
    <link rel=“stylesheet” href=“/css/blueprint/ie.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/ie.css” type=“text/css” media=“screen, projection”>
    <![endif]–>
</head>
<body>
   
    <div class=“container”>

        <div class=“block”>
            <div id=“header” class=“column span-24″>
                <h1><a href=“/”>Lorem Ipsum</a></h1>
            </div>
        </div>
       
// …………….

        <div class=“block”>
            <div id=“footer” class=“span-24″>
                <p>Copyright &copy; 2008 Padraic Brady</p>
            </div>
        </div>

    </div>

</body>
</html>

Just make matters worse, I added some small changes to our previous AuthorController and it’s related login template.

/application/controllers/AuthorController.php

<?php

class AuthorController extends Zend_Controller_Action
{

    public function loginAction()
    {
        $form = new ZFBlog_Form_AuthorLogin;

        if (!$this->getRequest()->isPost()) {
            $this->view->loginForm = $form;
            return;
        } elseif (!$form->isValid($_POST)) {
            $this->view->failedValidation = true;
            $this->view->loginForm = $form;
            return;
        }

        $values = $form->getValues();

        // Setup DbTable adapter
        $adapter = new Zend_Auth_Adapter_DbTable(
            Zend_Db_Table::getDefaultAdapter() // set earlier in Bootstrap
        );
        $adapter->setTableName(‘authors’);
        $adapter->setIdentityColumn(‘username’);
        $adapter->setCredentialColumn(‘password’);
        $adapter->setIdentity($values[‘name’]);
        $adapter->setCredential(
            hash(‘SHA256′, $values[‘password’])
        );

        // authentication attempt
        $auth = Zend_Auth::getInstance();
        $result = $auth->authenticate($adapter);

        // authentication succeeded
        if ($result->isValid()) {
            $auth->getStorage()
                ->write($adapter->getResultRowObject(null, ‘password’));
            $this->view->passedAuthentication = true;
            $this->_forward(‘index’, ‘index’, ‘admin’);
        } else { // or not! Back to the login page!
            $this->view->failedAuthentication = true;
            $this->view->loginForm = $form;
        }
    }

    public function logoutAction()
    {
        Zend_Auth::getInstance()->clearIdentity();
        $this->_helper->redirector(‘index’, ‘index’);
    }

}

The main change here was to add additional View variables to flag some conditions to the view template as used below. I tend to use flags a lot with Views since they are simple booleans and delegate the translation of these flags into some meaning to the View itself. It’s a really obvious gimmick I know but there are still lots of people who assign actual text without a second thought.

/application/views/scripts/author/login.phtml

<h2>Authentication</h2>
<p>Enter your author name and password below.</p>

<?php if($this->failedValidation): ?>
    <p class=“error”>Some problems were detected with the submitted form.</p>
<?php elseif($this->failedAuthentication): ?>
    <p class=“error”>The credentials supplied could not be authenticated. Please try again.</p>
<?php endif; ?>

<?php echo $this->loginForm->render() ?>

Lastly I made another tiny change to the template for our Administration Modules index page:

/application/admin/views/scripts/index/index.phtml

<h2>Administration</h2>

<?php if($this->passedAuthentication): ?>
    <p class=“success”>You have been successfully authenticated.</p>
<?php endif; ?>
<ul>
<li><a href=“/admin/entry/add”>New Entry</a></li>
</ul>

Upon authentication, as noted in our AuthorController:loginAction() method, users are forwarded to the Admin Module index page. This addition merely informs the user they were authenticated which explain why they’ve ended up there ;-).

Step 7: A Small Administration Template Update

Hindsight is great, but unfortunately you can’t make use of it on a live blog, so I’ll make a few quick changes now. What we’ll do is create a simple Administration Menu in the left column of our Administration Module’s templates.

Open up the file /application/admin/views/scripts/index/index.phtml and edit as follows:

<h2>Administration</h2>

<?php if($this->passedAuthentication): ?>
    <p class=“success”>You have been successfully authenticated.</p>
<?php endif; ?>
<p>Welcome, <?php echo Zend_Auth::getInstance()->getIdentity()->realname ?>.</p>

The change merely replaces the early menu block with a simple greeting using the Author’s real name as stored from previous authentication.

Open up the file /application/admin/views/layouts/admin.phtml and edit as follows:

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN”
  “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>
<html xmlns=“http://www.w3.org/1999/xhtml” xml:lang=“en” lang=“en”>
<head>
    <meta http-equiv=“Content-Type” content=“text/html; charset=utf-8″ />
    <meta name=“language” content=“en” />
    <title><?php echo $this->escape($this->title) ?></title>
    <link rel=“stylesheet” href=“/css/blueprint/screen.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/style.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/blueprint/print.css” type=“text/css” media=“print”>
    <!–[if IE]>
    <link rel=“stylesheet” href=“/css/blueprint/ie.css” type=“text/css” media=“screen, projection”>
    <link rel=“stylesheet” href=“/css/ie.css” type=“text/css” media=“screen, projection”>
    <![endif]–>
</head>
<body>
   
    <div class=“container”>

        <div class=“block”>
            <div id=“header” class=“column span-24″>
                <h1><a href=“/”>Lorem Ipsum</a></h1>
            </div>
        </div>

        <div class=“block”>
            <div id=“left” class=“column span-5″>
                <div class=“menu”>
                    <ul>
                        <li class=“menu-header”>Account</li>
                        <li><a href=“/author/logout”>Logout</a></li>
                        <li class=“menu-header”>Entries</li>
                        <li><a href=“/admin/entry/add”>New Entry</a></li>
                    </ul>
                </div>
            </div>
           
            <div id=“content” class=“column span-18″>
               
                <?php echo $this->layout()->content ?>

            </div>

        </div>

        <div class=“block”>
            <div id=“footer” class=“span-24″>
                <p>Copyright &copy; 2008 Padraic Brady</p>
            </div>
        </div>

    </div>

</body>
</html>

If editing the menu in looks odd, don’t worry yet. Those who really don’t like it can add it as a template partial or pass an array of menu data into a custom View Helper (I’ll be doing something similar in the near future to tidy up layouts). Finally, edit our stylesheet at /public/css/style.css to include the following styles for the now modified column.

div.menu {
    padding: 0 1em 0 1em;
    margin-top: 3em;
}
div.menu ul {
    list-style: none;
}
div.menu ul li.menu-header {
    padding-top: 1em;
    font-weight: bold;
    font-size: 110%;
}
div.menu ul > li:first-child.menu-header {
    padding-top: 0;
}
div.menu a {
    text-decoration: none;
    font-weight: bold;
}

Try out the application once more. It should now look a bit more presentable.

Conclusion

Implementing an ACL solution with Zend_Acl hasn’t proven difficult, in part due to the simplicity of our immediate needs. I would reiterate that remembering that Resources are not Controllers/Action, but merely virtual values which can be mapped or interpreted as such, is quite important. Using a 1:1 mapping is simply a common convention.

Since we’re on the cusp of entering the realm to create new blog entries, an update to styling is welcome. It’s not the final styling obviously, but looking at the minimalistic monotone output in my browser was becoming tiring ;-)

In the next edition of this series we’ll visit the task of creating, editing and displaying new blog entries.

All Contents Copyrighted to Pádraic Brady.

About the author: insic

Subscribe in my RSS Feed for more updates on Web Design and Development related articles. Follow me on twitter or drop a message to my inbox.

  • hoppster

    this is a great series you’re writing here. It should be getting more attention. keep up the good work!

  • http://gustav.ernberg.se Gustav

    Finally an understandable blog/tutorial about ZF, keep it up. I’m looking forward for the next part!

  • http://www.landofthewood.co.uk Jack

    It’s great to find this, I started off with google searching for stuff on Auth and Acl, as I wanted to see a proper example and so found lots of pages talking about this tutorial but none telling me where to find it.

    You are a total god-zend for resurrecting these tutorials (please excuse the very bad pun).

    Could you tell me if the tidying up of layouts was covered in the future parts of the tutorial series, it is mentioned in this one but of course I have no idea if it was written (and you have it) before the original was taken down.

    Thank you again for all your hard and dedicated work, you’re a star.

  • http://www.returnvoid.cl gonzalo

    great tutorial. is the first time that i read the acl resources does not have necesarily relationship with modules, controllers or action.

    thanks a lot

  • Biou

    Very useful, thank you !