1 of 7

Rule Sources

The security firewall can be configured with rules that can come from many different sources:

Declared inline in your config/Coldbox.cfc
A JSON file
An XML file
From a model object via a method call
From a database
Declared inline in ANY module's ModuleConfig.cfc

When defining your rules source, you ALWAYS have to define the rules property. You specify an array of rules for inline, or rules = "(db|json|xml|model)" if you define your rules externally. If you have external rules you probably have to specify additional properties as explained in the next pages.

Let's start exploring these sources.

DB Rules

If you have your security rules in a database, then cbsecurity can read the rules from the database for you. Just make the rules key equal to db and fill out the extra configuration keys shown below:

config/Coldbox.cfc

moduleSettings = {
	// CB Security
	cbSecurity : {
		rules        : "db", // Rules are in the database
		rulesDSN     : "myDatasource", // The datasource
		rulesTable   : "securityRules", // The table that has the rules
		rulesOrderBy : "order asc" // An optional ordering
	}
};

Inline Rules

Inline rules will be used by declaring them in your configuration for cbsecurity in the config/ColdBox.cfc. This is done by making the rules key an array of rule structures.

JSON Rules

If you have already a JSON file with your rules, then all you need to do is add the path (relative or absolute) to that file in the rules configuration key. However, the path MUST include the keyword json in it.

config/Coldbox.cfc

moduleSettings = {
	// CB Security
	cbSecurity : {
		"rules" : "config/security.json.cfm"
};

Then your file can be something like this:

config/security.json.cfm

[
    {
        "whitelist": "user\\.login,user\\.logout,^main.*",
        "securelist": "^user\\.*, ^admin",
        "match": "event",
        "roles": "admin",
        "permissions": "",
        "redirect": "user.login",
        "useSSL": false
    },
    {
        "whitelist": "",
        "securelist": "^shopping",
        "match": "url",
        "roles": "",
        "permissions": "shop,checkout",
        "redirect": "user.login",
        "useSSL": true
    }
]

Model Rules

If you prefer to store your rules your way, then that's perfectly fine. Just make your rules setting point to model and then provide us with the object to get the rules from.

config/Coldbox.cfc

moduleSettings = {
	// CB Security
	cbSecurity : {
		"rules" 		: "model",
		"rulesModel" 	: "SecurityService"
	}
};

Module Rules

Every module in ColdBox has the capability to contribute their own rules to cbsecurity by registering them in the ModuleConfig.cfc within the settings struct. Just create another struct called cbsecurity with the following allowed keys:

ModuleConfig.cfc

settings = {
    // CB Security Rules to prepend to global rules
    cbsecurity = {
        // Module Relocation when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthenticationEvent"     : "mod1:secure.index",
        // Default Authentication Action: override or redirect when a user has not logged in
        "defaultAuthenticationAction"    : "redirect",
        // Module override event when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthorizationEvent"    : "mod1:secure.auth",
        // Default Authorization Action: override or redirect when a user does not have enough permissions to access something
        "defaultAuthorizationAction"    : "redirect",
        // You can define your security rules here
        "rules"                            : [
            {
                "secureList"     : "mod1:home"
            },
            {
                "secureList"     : "mod1/modOverride",
                "match"            : "url",
                "action"        : "override"
            }
        ]
    }
};

As you can see each module can have it's own overrides for authentication and authorization events as well as their own rules.

Please note that these security rules will be PREPENDED to the global rules

Rule Sources

As with the global rules defined in config/Coldbox.cfc, the module cbsecurity.rules setting supports multiple rule sources:

For example, you can load security rules specific to a module from a JSON file stored in your module:

ModuleConfig.cfc

settings = {
    cbsecurity = {
        "rules" : "#modulePath#/config/firewallRules.json"
        // other config here... <---
    }
};

Loading/Unloading

Also note that if modules are loaded dynamically, it will still inspect them and register them if cbsecurity settings are found. The same goes for unloading, the entire security rules for that module will cease to exist.

XML Rules

If you have already an XML file with your rules, then all you need to do is add the path (relative or absolute) to that file in the rules configuration key. However, the path MUST include the keyword XML in it.

config/Coldbox.cfc

moduleSettings = {
	// CB Security
	cbSecurity : {
		"rules" : "config/security.xml.cfm"
};

Then your xml file can look like this:

config/security.xml.cfm

<?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>

Module Rules

ModuleConfig.cfc

settings = {
    // CB Security Rules to prepend to global rules
    cbsecurity = {
        // Module Relocation when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthenticationEvent"     : "mod1:secure.index",
        // Default Authentication Action: override or redirect when a user has not logged in
        "defaultAuthenticationAction"    : "redirect",
        // Module override event when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthorizationEvent"    : "mod1:secure.auth",
        // Default Authorization Action: override or redirect when a user does not have enough permissions to access something
        "defaultAuthorizationAction"    : "redirect",
        // You can define your security rules here
        "rules"                            : [
            {
                "secureList"     : "mod1:home"
            },
            {
                "secureList"     : "mod1/modOverride",
                "match"            : "url",
                "action"        : "override"
            }
        ]
    }
};

As you can see each module can have it's own overrides for authentication and authorization events as well as their own rules.

Please note that these security rules will be PREPENDED to the global rules

Rule Sources

As with the global rules defined in config/Coldbox.cfc, the module cbsecurity.rules setting supports multiple rule sources:

For example, you can load security rules specific to a module from a JSON file stored in your module:

ModuleConfig.cfc

settings = {
    cbsecurity = {
        "rules" : "#modulePath#/config/firewallRules.json"
        // other config here... <---
    }
};