Example Zend Framework Blog Application Tutorial - Part 7: Authorisation ...

You'd never think a guy could write so much about a blog application but to date after 6 parts we have covered a mass of detail from initial setup of our project's directory structure to Authentication of users. To date the feedback has been overwhelmingly positive to this series and I'm presently collecting comments regarding improvements for later inclusion.

Today's entry concerns authorisation. 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.

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:



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.



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.



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 .



Now edit ie.css.



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.