Overview

Authentication/Authorization
For any security system you need to know who is authenticated (authentication) and what (authorization) this user is allowed to do. cbsecurity is no different, so it provides an:
Authentication system which performs the following functions:
Validates user credentials
Logs them in and out
Tracks their security in sessions or any custom storage
Authorization system which:
validates permissions or roles or both
ColdBox Security Firewall
With the ColdBox security module you will be able to secure all your incoming ColdBox events from execution either through security rules or discrete annotations within your code. You will also be able to leverage our CBSecurity service model to secure any code context anywhere.
ColdBox Security Firewall
The module wraps itself around the preProcess interception point (The first execution of a ColdBox request) and will try to validate if the request has been authenticated and authorized to execute.  This is done via security rules and/or annotations on the requested handler actions through a CBSecurity Validator .  The job of the validator is to make sure user requests have been authenticated and authorized:
CBAuth Validator: this is the default (and recommended) validator, which makes use of the cbauth module. It provides authentication and permission based security.
CFML Security Validator: Coldbox security has had this validator since version 1,  and it will talk to the ColdFusion engine's security methods (cflogin,cflogout). It provides authentication and roles based security.
JWT Validator: If you want to use Json Web Tokens the JWT Validator provides authorization and authentication by validating incoming access/refresh tokens for RESTFul APIs.
Custom Validator: You can define your own authentication and authorization engines and plug them in to the cbsecurity framework.
How Does Validation Happen?
How does the interceptor know a user doesn't or does have access? Well, here is where you register a Validator CFC (validator setting) with the interceptor that implements two validation functions: ruleValidator() and annotationValidator() that will allow the module to know if the user is logged in and has the right authorizations to continue with the execution.
You can find an interface for these methods in cbsecurity.interfaces.ISecurityValidator
The validator has two options to determine if the user will be allowed access:
The ruleValidator() function will evaluate configured security rules​
The  annotationValidator() function will look at security annotations in your handler and handler actions.
You can use rules, annotations or even both. Rules are much more flexible, but more complex. Rules will be evaluated before annotations.
The validators' job is to tell back to the firewall if they are allowed access and if they don't, what type of validation they broke: authentication or authorization.
Authentication is when a user is NOT logged in
Authorization is when a user does not have the right permissions to access an event/handler or action.
Validation Process
Once the firewall has the results and the user is NOT allowed access, the following will occur:
The request that was blocked will be logged via LogBox with the offending IP and extra metadata
The current requested URL will be flashed as _securedURL so it can be used in relocations
If using a rule, the rule will be stored in prc as cbsecurity_matchedRule
The validator results will be stored in prc as cbsecurity_validatorResults
If the type of invalidation is authentication the cbSecurity_onInvalidAuthentication interception will be announced
If the type of invalidation is authorization the cbSecurity_onInvalidAuthorization interception will be announced
If the type is authentication the default action (defaultAuthenticationAction) for that type will be executed (An override or a relocation) will occur against the setting invalidAuthenticationEvent which can be an event or a destination URL.
If the type is authorization the default action (defaultAuthorizationAction) for that type will be executed (An override or a relocation) invalidAuthorizationEvent which can be an event or a destination URL.
Security Rules vs Annotation Security
Security Rules
1
{
2
    "whitelist"     : "", 
3
    "securelist"    : "", 
4
    "match"            : "event",  // or url
5
    "roles"            : "", 
6
    "permissions"    : "", 
7
    "redirect"         : "", 
8
    "overrideEvent"    : "", 
9
    "useSSL"        : false, 
10
    "action"        : "redirect", // or override 
11
    "module"        : ""
12
};
Copied!
Annotations
1
// Secure the entire handler
2
component secured{
3
​
4
	function index(event,rc,prc){}
5
	function list(event,rc,prc){}
6
​
7
}
8
// Same as this
9
component secured=true{
10
}
11
​
12
// Do NOT secure the handler
13
component secured=false{
14
}
15
// Same as this, no annotation!
16
component{
17
​
18
	function index(event,rc,prc) secured{
19
	}
20
​
21
	function list(event,rc,prc) secured="list"{
22
​
23
	}
24
	 
Copied!
Your application can be secured with security rules or handler and method annotations. Before making your choice, you should take the following arguments into consideration:
annotations are directly visible in your code, but very static. 
annotations can protect events. Rules can protect events and incoming Url's.
rules allow you to change your action (override or redirect) and target on each rule. With annotations you can only use your configured default action and target.
when stored in a file or database, rules can be edited by admins at runtime.
Security Rules
Global Rules can be declared in your config/ColdBox.cfc in plain CFML or in any module's ModuleConfig.cfc or they can come from the following global sources:
A json file
An xml file
The database by adding the configuration settings for it
A model by executing a getSecurityRules() method from it
Rule Anatomy
A rule is a struct that can be composed of the following elements. All of them are optional except the secureList.
1
rules = [
2
    {
3
        "whitelist"     : "", // A list of white list events or Uri's
4
        "securelist"    : "", // A list of secured list events or Uri's
5
        "match"            : "event", // Match the event or a url
6
        "roles"            : "", // Attach a list of roles to the rule
7
        "permissions"    : "", // Attach a list of permissions to the rule
8
        "redirect"         : "", // If rule breaks, and you have a redirect it will redirect here
9
        "overrideEvent"    : "", // If rule breaks, and you have an event, it will override it
10
        "useSSL"        : false, // Force SSL,
11
        "action"        : "", // The action to use (redirect|override) when no redirect or overrideEvent is defined in the rule.
12
        "module"        : "" // metadata we can add so mark rules that come from modules
13
    };
14
]
Copied!
Global Rules
Rules can be declared globally in your config/ColdBox.cfc or they can also be place in any custom module in your application:
config/Coldbox.cfc
1
// CB Security
2
cbSecurity : {
3
    // Global Relocation when an invalid access is detected, instead of each rule declaring one.
4
    "invalidAuthenticationEvent"     : "main.index",
5
    // Global override event when an invalid access is detected, instead of each rule declaring one.
6
    "invalidAuthorizationEvent"        : "main.index",
7
    // Default invalid action: override or redirect when an invalid access is detected, default is to redirect
8
    "defaultAuthorizationAction"    : "redirect",
9
    // The global security rules
10
    "rules"                         : [
11
        // should use direct action and do a global redirect
12
        {
13
            "whitelist": "",
14
            "securelist": "admin",
15
            "match": "event",
16
            "roles": "admin",
17
            "permissions": "",
18
            "action" : "redirect"
19
        },
20
        // no action, use global default action
21
        {
22
            "whitelist": "",
23
            "securelist": "noAction",
24
            "match": "url",
25
            "roles": "admin",
26
            "permissions": ""
27
        },
28
        // Using overrideEvent only, so use an explicit override
29
        {
30
            "securelist": "ruleActionOverride",
31
            "match": "url",
32
            "overrideEvent": "main.login"
33
        },
34
        // direct action, use global override
35
        {
36
            "whitelist": "",
37
            "securelist": "override",
38
            "match": "url",
39
            "roles": "",
40
            "permissions": "",
41
            "action" : "override"
42
        },
43
        // Using redirect only, so use an explicit redirect
44
        {
45
            "securelist": "ruleActionRedirect",
46
            "match": "url",
47
            "redirect": "main.login"
48
        }
49
    ]
50
    }
51
};
Copied!
Annotation Security
The firewall will inspect handlers for the secured annotation. This annotation can be added to the entire handler or to an action or both. The default value of the secured annotation is a Boolean true. Which means, we need a user to be authenticated in order to access it.
handlers
1
// Secure this handler
2
component secured{
3
​
4
    function index(event,rc,prc){}
5
    function list(event,rc,prc){}
6
​
7
}
8
​
9
// Same as this
10
component secured=true{
11
}
12
​
13
// Not the same as this
14
component secured=false{
15
}
16
// Or this
17
component{
18
​
19
    function index(event,rc,prc) secured{
20
​
21
    }
22
​
23
    function list(event,rc,prc) secured="list"{
24
​
25
    }
26
​
27
}
Copied!
Authorization Context
You can also give the annotation some value, which can be anything you like: A list of roles, a role, a list of permissions, metadata, etc. Whatever it is, this is the authorization context and the user validator must be able to not only authenticate but authorize the context or an invalid authorization will occur.
handler/users.cfc
1
// Secure this handler
2
component secured="admin,users"{
3
​
4
    function index(event,rc,prc) secured="list"{
5
​
6
    }
7
​
8
    function save(event,rc,prc) secured="write"{
9
​
10
    }
11
​
12
}
Copied!
Cascading Security
By having the ability to annotate the handler and also the action you create a cascading security model where they need to be able to access the handler first and only then will the action be evaluated for access as well.
Security Validator
As we mentioned at the beginning of this overview, the security module will use a Validator object in order to determine if the user has authentication/authorization or not. This setting is the validator setting and will point to the WireBox ID that implements the following methods: ruleValidator() and annotationValidator().
models/MyValidator.cfc
1
/**
2
 * This function is called once an incoming event matches a security rule.
3
 * You will receive the security rule that matched and an instance of the ColdBox controller.
4
 *
5
 * You must return a struct with two keys:
6
 * - allow:boolean True, user can continue access, false, invalid access actions will ensue
7
 * - type:string(authentication|authorization) The type of block that ocurred.  Either an authentication or an authorization issue.
8
 *
9
 * @return { allow:boolean, type:string(authentication|authorization) }
10
 */
11
struct function ruleValidator( required rule, required controller );
12
​
13
/**
14
 * This function is called once access to a handler/action is detected.
15
 * You will receive the secured annotation value and an instance of the ColdBox Controller
16
 *
17
 * You must return a struct with two keys:
18
 * - allow:boolean True, user can continue access, false, invalid access actions will ensue
19
 * - type:string(authentication|authorization) The type of block that ocurred.  Either an authentication or an authorization issue.
20
 *
21
 * @return { allow:boolean, type:string(authentication|authorization) }
22
 */
23
struct function annotationValidator( required securedValue, required controller );
Copied!
Each validator must return a struct with the following keys:
allow:boolean A Boolean indicator if authentication or authorization was violated
type:stringOf(authentication|authorization) A string that indicates the type of violation: authentication or authorization.
messages:string Info or debugging messages
CBAuthValidator
ColdBox security ships with the [email protected] which is the default validator in the configuration setting validator setting.
1
cbsecurity = {
2
    validator = "[email protected]"
3
}
Copied!
When using the default [email protected] you also have to configure the cbauth module.
1
  cbAuth: {
2
    userServiceClass: "UserService"
3
  }
Copied!
CFValidator
ColdBox security ships also with a CFML authentication and authorization validator called CFSecurity which has the following WireBox ID: [email protected] and can be found at cbsecurity.models.CFSecurity
You basically use cfloginuser to log in a user and set their appropriate roles in the system. The module can then match to these roles via the security rules you have created.
cfloginuser Code Examples and CFML Documentation
cflogin Code Examples and CFML Documentation
cbsecurity/models/CFValidator.cfc
1
struct function ruleValidator( required rule, required controller ){
2
    return validateSecurity( arguments.rule.roles );
3
}
4
​
5
struct function annotationValidator( required securedValue, required controller ){
6
    return validateSecurity( arguments.securedValue );
7
}
8
​
9
private function validateSecurity( required roles ){
10
    var results = { "allow" : false, "type" : "authentication" };
11
​
12
    // Are we logged in?
13
    if( isUserLoggedIn() ){
14
​
15
        // Do we have any roles?
16
        if( listLen( arguments.roles ) ){
17
            results.allow     = isUserInAnyRole( arguments.roles );
18
            results.type     = "authorization";
19
        } else {
20
            // We are satisfied!
21
            results.allow.true;
22
        }
23
    }
24
​
25
    return results;
26
}
Copied!
Custom Validators
The second method of authentication is based on your custom security logic. You will be able to register a validation object with the module. Once a rule is matched, the module will call your validation object, send in the rule/annotation value and ask if the user can access it or not. It will be up to your logic to determine if the rule is satisfied or not. Below is a sample permission based security validator:
models/MySecurity.cfc
1
component singleton{
2
​
3
    struct function ruleValidator( required rule, required controller ){
4
        return permissionValidator( rule.permissions, controller, rule );
5
    }
6
​
7
    struct function annotationValidator( required securedValue, required controller ){
8
        return permissionValidator( securedValue, controller );
9
    }
10
​
11
    private function permissionValidator( permissions, controller, rule ){
12
        var results = { "allow" : false, "type" : "authentication" };
13
        var user     = getCurrentUser();
14
​
15
        // First check if user has been authenticated.
16
        if( user.isLoaded() AND user.isLoggedIn() ){
17
            // Do we have the right permissions
18
            if( len( arguments.permissions ) ){
19
                results.allow     = user.checkPermission( arguments.permission );
20
                results.type     = "authorization";
21
            } else {
22
                results.allow = true;
23
            }
24
        }
25
​
26
        return results;
27
    }
28
}
Copied!
Authentication vs Authorization
The security module can distinguish between authentication issues and authorization issues. Once these actions are identified, the security module can act upon the result of these actions. These actions are based on the following 4 settings, but they all come down to two outcomes:
a relocation to another event or URL
an event override
Setting
Default
Description
invalidAuthenticationEvent
---
The global invalid authentication event or URI or URL to go if an invalid authentication occurs
defaultAuthenticationAction
redirect
Default Authentication Action: override or redirect when a user has not logged in
invalidAuthorizationEvent
---
The global invalid authorization event or URI or URL to go if an invalid authorization occurs
defaultAuthorizationAction
redirect
Default Authorization Action: override or redirect when a user does not have enough permissions to access something
Interceptions
When invalid authentication or authorizations occur the interceptor will announce the following events:
cbSecurity_onInvalidAuthentication
cbSecurity_onInvalidAuthorization
You will receive the following data in the interceptData struct:
ip : The offending IP address
rule : The security rule intercepted or empty if annotations
settings : The firewall settings
validatorResults : The validator results
annotationType : The annotation type intercepted, handler or action or empty if rule driven
processActions : A Boolean indicator that defaults to true. If you change this to false, then the interceptor won't fire the invalid actions. Usually this means, you manually will do them.
You can use these security listeners to do auditing, logging, or even override the result of the operation.
There are many more interception points available to you, check them out in our Interceptions page.
CBSecurity Model
The CBSecurity model was introduced in version 2.3.0 and it provides you with a way to provide authorization checks and contexts anywhere you like: handlers, layouts, views, interceptors and even models.
Getting access to the model is easy via our cbSecure() mixin (handlers/layouts/views/interceptors) or injecting it via WireBox:
1
// Mixin approach
2
cbSecure()
3
​
4
// Injection
5
property name="cbSecurity" inject="@CBSecurity";
Copied!
Once injected you can leverage it using our awesome methods listed below:
Blocking Methods
When certain permission context is met, if not throws NotAuthorized
secure( permissions, [message] )
secureAll( permissions, [message] )
secureNone( permissions, [message] )
secureWhen( context, [message] )
1
// Only allow access to user_admin
2
cbSecure().secure( "USER_ADMIN" );
3
​
4
// Only allow access if you have all of these permissions
5
cbSecure().secureAll( "EDITOR, POST_PUBLISH" )
6
​
7
// YOu must not have this permission, if you do, kick you out
8
cbSecure().secureNone( "FORGEBOX_USER" )
9
​
10
// Secure using security evaluations
11
// Kick out if you do not have the AUTHOR_ADMIN or you are not the same incoming author
12
cbSecurity.secureWhen( 
13
    cbSecurity.none( "AUTHOR_ADMIN" ) && 
14
    !cbSecurity.sameUser( oAuthor )  
15
)
16
​
17
// Secure using a closure 
18
cbSecurity.secureWhen( ( user ) => !user.isConfirmed() );
Copied!
Action Context Methods
When certain permission context is met, execute the success function/closure, else if a fail closure is defined, execute that instead.
when( permissions, success, fail )
whenAll( permissions, success, fail )
whenNone( permissions, success, fail )
1
var oAuthor = authorService.getOrFail( rc.authorId );
2
prc.data = userService.getData();
3
​
4
// Run Security Contexts
5
cbSecure()
6
    // Only user admin can change to the incoming role
7
    .when( "USER_ADMIN", ( user ) => oAuthor.setRole( roleService.get( rc.roleID ) ) )
8
    // The system admin can set a super admin
9
    .when( "SYSTEM_ADMIN", ( user ) => oAuthor.setRole( roleService.getSystemAdmin() ) )
10
    // Filter the data to be shown to the user
11
    .when( "USER_READ_ONLY", ( user ) => prc.data.filter( ( i ) => !i.isClassified ) )
12
​
13
// Calling with a fail closure
14
cbSecurity.when(
15
    "USER_ADMIN",
16
    ( user ) => user.setRole( "admin" ), //success
17
    ( user ) => relocate( "Invaliduser" ) //fail
18
);
Copied!
Verification Methods
Verify permissions or user equality
has( permissions ):boolean
all( permissions ):boolean
none( permissions ):boolean
sameUser( user ):boolean
1
function edit( event, rc, prc ){
2
    var oUser = userService.getOrFail( rc.id ?: "" );
3
    if( !sameUser( oUser ) ){
4
        relocate( "/users" );
5
    }
6
}
7
​
8
<cfif cbsecure().all( "USER_ADMIN,USER_EDITOR" )>
9
    This is only visible to user admins!
10
</cfif>
11
​
12
<cfif cbsecure().has( "SYSTEM_ADMIN" )>
13
    <a href="/user/impersonate/#prc.user.getId()#">Impersonate User</a>
14
</cfif>
15
​
16
<cfif cbsecure().sameUser( prc.user )>
17
    <i class="fa fa-star">This is You!</i>
18
</cfif>
Copied!
Request Context Methods
secureView( permissions, successView, failView )
handlers/users.cfc
1
component{
2
​
3
    function index( event, rc, prc ){
4
     event.secureView( "USER_ADMIN", "users/admin/index", "users/index" ); 
5
    }
6
​
7
}
Copied!
Security Visualizer
This module also ships with a security visualizer that will document all your security rules and your settings in a nice panel. In order to activate it you must add the enableSecurityVisualizer setting to your config and mark it as true. Once enabled you can navigate to: /cbsecurity and you will be presented with the visualizer.
Important The visualizer is disabled by default and if it detects an environment of production, it will disable itself.
JSON Web Tokens (JWT) REST Security
ColdBox Security offers a comprehensive feature set for RESTFul applications that require JSON web tokens.  We offer both access and refresh token capabilities.  Check out our JWT Section for an in-depth overview.
Getting Started - Previous
Installation
Next - Getting Started
Configuration
Last modified 3mo ago