<?xml version="1.0" encoding="ISO-8859-1"?>
<-- <
Declare as many rule elements as you want, order is important 
Remember that the securelist can contain a list of regular
expressions if you want

ex: All events in the user handler
 user\..*
ex: All events
 .*
ex: All events that start with admin
 ^admin

If you are not using regular expressions, just write the text
that can be found in an event.
-->
<rules>
    <rule>
        <match>event</match>
        <whitelist>user\.login,user\.logout,^main.*</whitelist>
        <securelist>^user\..*, ^admin</securelist>
        <roles>admin</roles>
        <permissions>read,write</permissions>
        <redirect>user.login</redirect>
    </rule>

    <rule>
           <match>event</match>
        <whitelist></whitelist>
        <securelist>^moderator</securelist>
        <roles>admin,moderator</roles>
        <permissions>read</permissions>
        <redirect>user.login</redirect>
    </rule>

    <rule>
           <match>url</match>
        <whitelist></whitelist>
        <securelist>/secured.*</securelist>
        <roles>admin,paid_subscriber</roles>
        <permissions></permissions>
        <redirect>user.pay</redirect>
    </rule>
</rules>

IMPORTANT Please remember to white list your main events (implicit), login and logout events if you will be securing the entire application.

First Rule Analysis

As you can see from the sample, the first rule has the following elements

<match>event</match>

So it will match the incoming event.

<whitelist>user\.login,user\.logout,^main.*</whitelist>

This means that the following events will not be verified for security: user.login, user.logout and any event that starts with main will be let through, if they match the secure list pattern.

<securelist>^user\..*, ^admin</securelist>

This means that any event that starts with the word user will be secured and anything that starts with the word admin will also be secured, unless the incoming event matches a pattern in the whitelist element.

<roles>admin</roles>

This means that only a user with admin role will be allowed to visit the securelist events.

<permissions>read,write</permissions>

This probably means that I am doing my own security validation and apart from having the user have a role of admin, he/she must also have the read and write permissions. My own validator will validate this logic.

<redirect>user.login</redirect>

Then if it does not validate it will use this redirect element to relocate via setNextEvent()

Second Rule Analysis

The second rule has the following elements:

<match>event</match>

So it will match the incoming event.

<whitelist></whitelist>

No white listed events are defined.

<securelist>^moderator</securelist>

This means that any event that starts with the word moderator will be secured and validated against the user's credentials.

<roles>admin,moderator</roles>

This means that users with roles of admin and moderator can execute events that are in the securelist.

<permissions>read</permissions>

This probably means that I am doing my own security validation and apart from having the user have a role of admin or moderator, he/she must also have the read permission. My own validator will validate this logic.

<redirect>user.login</redirect>

Then if it does not validate it will use this redirect element to relocate via setNextEvent()

Third Rule Analysis

The third rule has the following elements:

<match>URL</match>

So it will match the incoming URL pattern after the domain name and application location.

<whitelist></whitelist>

No white listed events are defined.

<securelist>/secured.*</securelist>

It will secure any incoming URI that starts with /secured

<roles>admin,paid_subscriber</roles>

This means that users with roles of admin and paid_subscriber can visit URLs with /secured in them

<permissions></permissions>

No permissions

<redirect>user.pay</redirect>

Then if it does not validate it will use this redirect element to relocate via setNextEvent()

Now that we have seen all the properties of this module, how to configure it and declare it, let's look at how the rules work. All the security rules follows the following format, however, you can append as many columns as you like for your own custom validations and the interceptor will register all the columns you pass to it:

You might be asking, why is the element permissions here, if the default ColdFusion security doesn't work with permissions but with roles. Well, in anticipation to customizations and permissions based systems, the permissions element exists. It's there already if you need to use it. However, the default interceptor security does not use it, just the roles element. A few guidelines:

• Test your regular expressions (http://gskinner.com/blog/archives/2008/03/regexr_free_onl.html)

• Determine if you want to secure the incoming URL or event

• Order of declaration of the rules is important as they are fired in order

• Test your whitelist events, if not you might be producing endless loops of security redirections

• Make sure implicit events are whitelisted if you are securing the entire application events

• As best practice, create your own validator object for more granular control

IMPORTANT The basic rules table is provided. However, it is very denormalized and for simple applications. If your applications will deal with many permissions and roles, I suggest you build your DB according to your business rules and then just create a method that can join the rules into the above format. You can easily do this in SQL or create a view for your security rules. If you are doing this, then your security implementations are advanced and you know what you are doing (Hopefully). So please note that the way you store the rules in the DB is your priority and consideration.