There are also times where you need to validate custom conditions and block access to certain areas. This way, you can implement your own custom security logic and leverage cbSecurity for blockage. You will accomplish this via the secureWhen() method:

The context can be a closure/lambda/udf or a boolean evaluation:

The closure/udf will receive the currently authenticated user as the first argument.

The secure() Methods

Now that you have access to the model, you can use the following method to verify explicit permissions and authorize access. This method will throw an exception if the user does not validate the incoming permissions context (NotAuthorized).

• The permission can be an array, string or list of the permissions to validate. The user must have at least one of the permissions specified.

• The message is a custom error message to be used in the message string of the exception thrown.

You also have two more authorization methods that will verify certain permission conditions for you:

Conditional Authorizations Using when()

There are also cases where you want to execute a piece of code by determining if the user has access to do so. For example, only a USER_ADMIN can change people's roles or you want to filter some data for certain users. For this, we have created the when() method with the following signature:

• The permissions is a permission array or list that will be Or'ed

• The success is a closure/lambda or UDF that will execute if the permissions validate.

• The fail is a closure/lambda or UDF that will execute if the permissions DID not validate, much like an else statement

Both closures/functions takes in a user which is the currently authenticated user, the called in permissions and can return anything.

You can also chain the when() calls if needed, to create beautiful security contexts. So if we go back to our admin examples, we can do something like this:

We have also added the following whenX() methods to serve your needs when evaluating the permissions:

Explicit Authorizations

The cbSecurity model is a specialized service that will allow you to do explicit authorizations in any layer of your ColdBox application.

There will be times where you will need authorization checks outside of the incoming request rules or the handler annotations. This can be from within interceptors, models, layouts or even views. For this, we have provided the cbSecurity model so you can do explicit authorization checks anywhere you like.

cbSecurity Model

You can inject our model or you can use our handy cbsecure() mixin (handlers/layouts/views) and then call the appropriate security functions:

// Mixin: Handlers/Layouts/Views
cbsecure()

// Injection
property name="cbSecurity" inject="@cbSecurity"

You can now discover our sections for securing using cbSecurity

• Secure() blocking methods

• Verification Methods

• Authorization Contexts

• Securing Views

cbSecurity Method Summary

Blocking Methods

When certain permission context is met, if not throws NotAuthorized

• secure( permissions, [message] )

• secureAll( permissions, [message] )

• secureNone( permissions, [message] )

• secureWhen( context, [message] )

• guard() alias to secure()

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 )

Verification Methods

Verify permissions or user equality

• has( permissions ):boolean

• all( permissions ):boolean

• none( permissions ):boolean

• sameUser( user ):boolean

Request Context Methods

• secureView( permissions, successView, failView )

You can also use our handy event.secureView() method in the request context to pivot between views according to user permissions.

event.secureView( permissions, successView, failView )

This will allow you to set the successView if the user has the permissions or the failView if they don't.

If you just want to validate if a user has certain permissions or maybe no permissions at all or if a passed user is the same as the logged in user, then you can use the following boolean methods that only do verification.

// Checks the user has one or at least one permission if the 
// permission is a list or array
boolean cbSecurity.has( permission );
// The user must have ALL the permissions
boolean cbSecurity.all( permission );
// The user must NOT have any of the permissions
boolean cbSecurity.none( permission );
// Verify if the passed in user is the same as the logged in user
boolean cbSecurity.sameUser( user );

These are great to have a unified and abstracted way to verifying permissions or if the passed user is the same as the logged in user. Here are some examples:

View Layer

<cfif cbsecure().has( "USER_ADMIN" )>
    This is only visible to user admins!
</cfif>

<cfif cbsecure().has( "SYSTEM_ADMIN" )>
    <a href="/user/impersonate/#prc.user.getId()#">Impersonate User</a>
</cfif>

<cfif cbsecure().sameUser( prc.user )>
    <i class="fa fa-star">This is You!</i>
</cfif>

Other Layers:

if( cbSecurity.has( "PERM" ) ){
    auditUser();
}

if( cbSecurity.sameUser( prc.incomingUser ) ){
    // you can change your gravatar
}