In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 2.0

Version 2 is a major release of our security module. We completely refactored the engine to make it more modern and to adhere to our new coding standards. We then proceeded to enhance it to tap into our HMVC approach and allow rules to be contributed from modules themselves. We also added annotation driven security to complete the ability to secure not only incoming requests by rules but also by easy annotations.

We have made great strides in this release to make it a one-stop-shop for security concerns within ColdBox applications.

Version 1.0

Our first release as a module decoupled from the ColdBox 2 days!

Added

• More and more apps will need real ip's from request, so expose it via the CBSecurity model service as : getRealIp()

Fixed

• When using getHTTPREquestData() send false so we DON'T retrieve the http body when we just need the headers

• More updates to getRealIp() when dealing with lists

Added

• threadsafe annotation to all models to prevent invalid creations under load, since we don't use circular dependencies.

Added

• Adobe 2021 Support

• Migration to GitHub Actions from Travis CI

• Refresh tokens support

• Refresh token endpoint /cbsecurity/refreshToken for secure refresh token generation

• Manual refresh token method on the JwtService : refreshToken( token )

• Auto refresh token header interceptions for JWT validators

• Detect on authenticate() if the payload is empty and throw the appropriate exceptions

• Added ability for the authenticate( payload ) to receive a payload to authenticate

• Added ability to recreate the token storage using a force argument getTokenStorage( force = false )

• Ability for the parseToken() to choose to store and authenticate or just parse

Fixed

• Unique jti could have collisions if tokens created at the same time, add randomness to it

• TokenExpirationException not relayed from the base jwt library

• If variables.settings.jwt.tokenStorage.enabled is disabled all invalidations failed, make sure if the storage is disabled to not throw storage exceptions.

🚀 Added

• Pass custom claims from refreshToken() method when refreshing tokens

In the JWTService the refreshToken( struct customClaims = {} ) now has a customClaims argument which you can use to seed the refresh token with custom claims.

• Pass in the current JWT payload in to getJWTCustomClaims( payload ) method

This was done to help authors have the exact payload that was used for the execution call. This affects the IJwtSubject interface.

• The auto refresh token features now will auto refresh not only on expired tokens, but on invalid and missing tokens as well. Thanks to @elpete

🐛 Fixed

• Timeout in token storage is now the token timeout

The ColdBox cbsecurity module is a collection of modules to help secure your applications.

The major areas of concern are:

• A security authentication/authorization firewall ( cbsecurity ) which can secure your application based on:

  • Security rules and a rule engine for validation incoming events or URL's

  • Handler annotations

• A security service for explicit authorizations ( cbsecurity ) to provide you with functional approaches to security context authorization in any layer of your application.

• A JWT generator, decoder and authentication services ( jwtcfml )

• Cross Site Request Forgery (CSRF) Protection ( cbcsrf )

• An authentication manager ( cbauth )

Module composition

Features

• Ability to have global security rules

• Ability for modules to add their own security rules and action overrides

• Ability to distinguish between authentication and authorization issues

• Annotation driven cascading security for handlers and actions

• A functional security service that can be injected anywhere to provide you with authorizations

• Security rules can exist in:

  • XML File

  • JSON File

  • Database

  • Models

• The rules can be configured to use regular expressions or simple snippets

• Can use ColdFusion authentication security

• Can leverage any custom authentication provider

• Plug any Authentication service or can leverage cbauth by default

• Capability to distinguish between invalid authentication and invalid authorization and determine an outcome of the process.

• Ability to load/unload security rules from contributing modules.

• Ability for each module to define it's own validator

• JWT Access and Refresh Tokens Native support

Versioning

The ColdBox Security Module is maintained under the Semantic Versioning guidelines as much as possible. Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

Apache 2 License: http://www.apache.org/licenses/LICENSE-2.0​

Important Links

• Code: https://github.com/coldbox-modules/cbsecurity​

• Issues: https://github.com/coldbox-modules/cbsecurity/issues

Professional Open Source

The ColdBox Security Module is a professional open source software backed by Ortus Solutions, Corp offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Discussion & Help

The Box products and modules community for discussion and help can be found here:

https://community.ortussolutions.com/c/box-modules/cbsecurity/

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Added

• Add a secureSameUser method to throw when passed a different user #29 (https://github.com/coldbox-modules/cbsecurity/pull/29)

[2.11.1] => 2021-MAR-10

Fixed

• Fix getRealIP() to only return originating user's source IP, if the forwarded ip is a list

Added

• parseToken( token ) now accepts a token of your choice to work with in the request or it will continue to discover it if not passed.

• Added new JWT Service method: invalidateAll() which invalidates all tokens in the token storage

• Added the new event: cbSecurity_onJWTInvalidateAllTokens that fires once all tokens in the storage are cleared

• Added storage of the authenticated user into the prc scope when using attempt() to be consistent with API calls

Fixed

• Spelling corrections on the readme

• Added full var scoping for cbsecurity in JWTService calls

Added

• Moved the registration of the validator from the configure() to the afterAspectsLoad() interception point to allow for modules to declare the validator if needed.

• Moved handler bean to afterAspectsLoad() to allow for module based invalid events to work.

Added

• Contributed module rules are now pre-pended instead of appended. (@wpdebruin)

Fixed

• Not loading rules by source file detection due to invalid setting check

• Don't trigger ColdBox's invalid event looping protection. It also auto-senses between ColdBox 6 and 5 (@homestar9)

• Fixed token scopes according to JWT spec, it is called scope and it is a space separated list. This doesn't change the User interface for it. (@wpdebruin)

• Update token storages so no token rejection anymore when storage is not enabled. (@wpdebruin)

Fixed

• Fixes a typo in the cbSecurity_onInvalidAuthorization interception point declaration. Previously, the typo would prevent ColdBox from allowing the correctly-typed interception point from ever triggering an interception listener.

• The userValidator() method has been changed to roleValidator(), but the error message was forgotten! So the developer is told they need a userValidator() method... because the userValidator method is no longer supported. :/

Added

• The isLoggedIn() method now makes sure that a jwt is in place and valid, before determining if you are logged in or not.

• Migrated all automated tests to focal and mysql8 in preparation for latest updates

• Add support for JSON/XML/model rules source when loading rules from modules. Each module can now load rules not only inline but from the documented external sources.

• Ensure non-configured rules default to empty array

In this release we have updated our internal authentication library cbauth to version 5.x. Which brings the following changes to cbauth:

• Added preLogin, postLogin, preLogout, postLogout interception points

• authentication() now returns the user if valid

Just run update cbsecurity and you are done!

This release adds the inclusion of the Cross Site Request Forgery module into cbsecurity: cbcsrf. You can find all the details about this module here: https://github.com/coldbox-modules/cbcsrf. Below are the major features of this module:

Features

• Ability to generate security tokens based on your session

• Automatic token rotation when leveraging cbauth login and logout operations

• Ability to on-demand rotate all security tokens for specific users

• Leverages cbStorages to store your tokens in CacheBox, which can be easily distributed and clustered

• Ability to create multiple tokens via unique reference keys

• Auto-verification interceptor that will verify all non-GET operations to ensure a security token is passed via rc or headers

• Auto-sensing of integration testing so the verifier can allow testing calls

• Token automatic rotation on specific time periods for enhance security

• Helpers to automatically generate hidden fields for the token

• Automatic generation endpoint that can be used for Ajax applications to request tokens for users

Features

• Feature : Migrated from the jwt to the jwtcfml (https://forgebox.io/view/jwt-cfml) library to expand encoding/decoding capabilities to support RS and ES algorithms:

  • HS256

  • HS384

  • HS512

  • RS256

  • RS384

  • RS512

  • ES256

  • ES384

  • ES512

• Feature : Added a new convenience method on the JWT Service: isTokenInStorage( token ) to verify if a token still exists in the token storage

• Feature : If no jwt secret is given in the settings, we will dynamically generate one that will last for the duration of the application scope.

• Feature : New setting for jwt struct: issuer, you can now set the issuer of tokens string or if not set, then cbSecurity will use the home page URI as the issuer of authority string.

• Feature : All tokens will be validated that the same iss (Issuer) has granted the token

Improvements

• Improve : Ability to have defaults for all JWT settings instead of always typing them in the configs

• Improve : More formattting goodness!

Bugs

• Bug : Invalidation of tokens was not happening due to not using the actual key for the storage

This release focuses on bringing a strong focus on protecting every development layer of a ColdBox application. It introduces the cbSecurity model that can be used by any layer and provides you with a great functional API to secure your code.

Explicit Authorizations

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 (interceptors/handlers/layouts/views) and then call the appropriate security functions:

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

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

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).

// Verify the currently logged in user has those permission, 
// else throw a NotAuthorized exception
cbSecurity.secure( permissions, [message] );
cbsecure().secure( permissions, [message] );

• The permission can be an array, string or list of the permissions to validate.

• 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:

// Authorize that the user has ALL of the incoming permissions
cbSecurity.secureAll( permissions, [message] );
// Authorize that the user has NONE of the incoming permissions
cbSecurity.secureNone( permissions, [message] );

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:

when( permissions, success, fail )

• 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.

// Lambda approach
( user, permissions ) => { 
    // your code here
};
// UDF/Closure
function( user, permissions ){ 
    // your code here
}

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:

var oAuthor = authorService.getOrFail( rc.authorId );
prc.data = userService.getData();

// Run Security Contexts
cbSecure()
    // Only user admin can change to the incoming role
    .when( "USER_ADMIN", ( user ) => oAuthor.setRole( roleService.get( rc.roleID ) ) )
    // The system admin can set a super admin
    .when( "SYSTEM_ADMIN", ( user ) => oAuthor.setRole( roleService.getSystemAdmin() ) )
    // Filter the data to be shown to the user
    .when( "USER_READ_ONLY", ( user ) => prc.data.filter( ( i ) => !i.isClassified ) )

// Calling with a fail closure
cbSecurity.when(
    "USER_ADMIN",
    ( user ) => user.setRole( "admin" ), //success
    ( user ) => relocate( "Invaliduser" ) //fail
);

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

// When all permissions must exist in the user
whenAll( permissions, success, fail)
// When none of the permissions exist in the user
whenNone( permissions, success, fail )

Verification Methods

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
}

Authorization Contexts

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:

secureWhen( context, [errorMessage] )

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

// Using as a closure/lambda
cbSecurity.secureWhen( ( user ) => !user.isConfirmed() )
cbSecurity.secureWhen( ( user ) => !oEntry.canPublish( user ) )

// Using a boolean evaluation
cbSecurity.secureWhen( cbSecurity.none( "AUTHOR_ADMIN" ) && !cbSecurity.sameUser( oAuthor )  )
cbSecurity.whenNone( "AUTHOR_ADMIN", ( user ) => relocate() );

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

( user ) => {}
function( user );

Securing Views

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.

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 )

Added

• New build layout based on new module layout

• Auto github publishing release notes

• More formatting goodness and watcher

Fixed

• JWT Validator now passing permissions instead of roles

• Token Storage checking was being done even if disabled

New Features

• Adobe 2016,2018 Support

• Settings transferred to ColdBox 4/5 moduleSettings approach instead of root approach (See compat section)

• The rulesModelMethod now defaults to getSecurityRules()

• ColdFusion security validator has an identity now CFValidator@cbsecurity instead of always being inline.

• You can now add an overrideEvent element to a rule. If that is set, then we will override the incoming event via event.overrideEvent() instead of doing a relocation using the redirect rule element.

• You can now declare your rules inline in the configuration settings using the rules key. This will allow you to build the rules in your config instead of a rule source.

• We now can distinguish between invalid auth and invalid authorizations

• New interception block points cbSecurity_onInvalidAuthentication, cbSecurity_onInvalidAuhtorization

• You now have a defaultAuthorizationAction setting which defaults to redirect

• You now have a invalidAuthenticationEvent setting that can be used

• You now have a defaultAuthenticationAction setting which defaults to redirect

• You now have a invalidAuthorizationEvent setting that can be used

• If a rule is matched, we will store it in the prc as cbSecurity_matchedRule so you can see which security rule was used for processing invalid access actions.

• If a rule is matched we will store the validator results in prc as cbSecurity_validatorResults

• Ability for modules to register cbSecurity rules and setting overrides by registering a settings.cbSecurity key.

• New security rule visualizer for graphically seeing you rules and configuration. Can be locked down via the enableSecurityVisualizer setting. Disabled by default.

• Annotation based security for handlers and actions using the secured annotation. Which can be boolean or a list of permissions, roles or whatever you like.

• You can disable annotation based security by using the handlerAnnotationSecurity boolean setting.

• JWT Token Security Support

Improvements

• SSL Enforcement now cascades according to the following lookup: Global, rule, request

• Interfaces documented for easier extension interfaces.*

• Migration to script and code modernization

• New Module Layout

• Secured rules are now logged as warn() with the offending Ip address.

• New setting to turn on/off the loading of the security firewall: autoLoadFirewall. The interceptor will auto load and be registered as cbsecurity@global in WireBox.

Compat

• Adobe 11 Dropped

• Lucee 4.5 Dropped

• Migrate your root cbSecurity settings in your config/ColdBox.cfc to inside the moduleSettings

• IOC rules support dropped

• OCM rules support dropped

• validatorModel dropped in favor of just validator to be a WireBox Id

• Removed preEventSecurity it was too chatty and almost never used

• The function userValidator has been renamed to ruleValidator and also added the annotationValidator as well.

• rulesSource removed you can now use the rules setting

  • The rules can be: array, db, model, filepath

  • If the filepath has json or xml in it, we will use that as the source style

• rulesFile removed you can now use the rules setting.

About This Book

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by and cannot be altered or reproduced without author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - ​

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer that has been developing and designing software systems since the year 2000. He was born in in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at . Luis resides in Houston, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5

Contributors

Will de Bruin

Brad Wood

Leverage CommandBox to install into your ColdBox app:

System Requirements

• Lucee 5.x+

• ColdFusion 2016+

Module Settings

The module can be configured by adding a cbsecurity key in the moduleSettings structure within the config/Coldbox.cfc

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

Let's start exploring these sources.

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.

moduleSettings = {
	// CB Security
	cbSecurity : {
		// The global security rules
		"rules" : [
			// should use direct action and do a global redirect
			{
				"whitelist": "",
				"securelist": "admin",
				"match": "event",
				"roles": "admin",
				"permissions": "",
				"action" : "redirect"
			},
			// no action, use global default action
			{
				"whitelist": "",
				"securelist": "noAction",
				"match": "url",
				"roles": "admin",
				"permissions": ""
			},
			// Using overrideEvent only, so use an explicit override
			{
				"securelist": "ruleActionOverride",
				"match": "url",
				"overrideEvent": "main.login"
			},
			// direct action, use global override
			{
				"whitelist": "",
				"securelist": "override",
				"match": "url",
				"roles": "",
				"permissions": "",
				"action" : "override"
			},
			// Using redirect only, so use an explicit redirect
			{
				"securelist": "ruleActionRedirect",
				"match": "url",
				"redirect": "main.login"
			}
		]
	}
};

Security Settings

By Default, the security module will register itself for you using the module configuration settings you define in theconfig/ColdBox.cfc. Below you can find all the settings with their default value and description.

// Module Settings
moduleSettings = {
    // CB Security
    cbSecurity : {
        // The global invalid authentication event or URI or URL to go if an invalid authentication occurs
        "invalidAuthenticationEvent"    : "",
        // Default Authentication Action: override or redirect when a user has not logged in
        "defaultAuthenticationAction"    : "redirect",
        // The global invalid authorization event or URI or URL to go if an invalid authorization occurs
        "invalidAuthorizationEvent"        : "",
        // 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 or externally via a source
        // specify an array for inline, or a string (db|json|xml|model) for externally
        "rules"                            : [],
        // The validator is an object that will validate rules and annotations and provide feedback on either authentication or authorization issues.
        "validator"                        : "CBAuthValidator@cbsecurity",
        // The WireBox ID of the authentication service to use in cbSecurity which must adhere to the cbsecurity.interfaces.IAuthService interface.
        "authenticationService"          : "authenticationService@cbauth",
        // WireBox ID of the user service to use
        "userService"                     : "",
        // The name of the variable to use to store an authenticated user in prc scope if using a validator that supports it.
        "prcUserVariable"                 : "oCurrentUser",
        // If source is model, the wirebox Id to use for retrieving the rules
        "rulesModel"                    : "",
        // If source is model, then the name of the method to get the rules, we default to `getSecurityRules`
        "rulesModelMethod"                : "getSecurityRules",
        // If source is db then the datasource name to use
        "rulesDSN"                        : "",
        // If source is db then the table to get the rules from
        "rulesTable"                    : "",
        // If source is db then the ordering of the select
        "rulesOrderBy"                    : "",
        // If source is db then you can have your custom select SQL
        "rulesSql"                         : "",
        // Use regular expression matching on the rule match types
        "useRegex"                         : true,
        // Force SSL for all relocations
        "useSSL"                        : false,
        // Auto load the global security firewall
        "autoLoadFirewall"                : true,
        // Activate handler/action based annotation security
        "handlerAnnotationSecurity"        : true,
        // Activate security rule visualizer, defaults to false by default
        "enableSecurityVisualizer"        : false,
        // JWT Settings
        "jwt"                             : {
            // The issuer authority for the tokens, placed in the `iss` claim
            "issuer"                  : "",
            // The jwt secret encoding key to use
            "secretKey"               : getSystemSetting( "JWT_SECRET", "" ),
            // by default it uses the authorization bearer header, but you can also pass a custom one as well or as an rc variable.
            "customAuthHeader"        : "x-auth-token",
            // The expiration in minutes for the jwt tokens
            "expiration"              : 60,
            // If true, enables refresh tokens, longer lived tokens (not implemented yet)
            "enableRefreshTokens"     : false,
            // The default expiration for refresh tokens, defaults to 30 days
            "refreshExpiration"       : 43200,
            // encryption algorithm to use, valid algorithms are: HS256, HS384, and HS512
            "algorithm"               : "HS512",
            // Which claims neds to be present on the jwt token or `TokenInvalidException` upon verification and decoding
            "requiredClaims"          : [] ,
            // The token storage settings
            "tokenStorage"            : {
                // enable or not, default is true
                "enabled"       : true,
                // A cache key prefix to use when storing the tokens
                "keyPrefix"     : "cbjwt_",
                // The driver to use: db, cachebox or a WireBox ID
                "driver"        : "cachebox",
                // Driver specific properties
                "properties"    : {
                    "cacheName" : "default"
                }
            }
        }
    }
};

InvalidAuthentication-/ InvalidAuthorization events and default actions

The invalidAuthenticationEvent and invalidAuthorizationEvent keys can be used to provide default events when Authentication or Authorization failed. The defaultAuthenticationAction and defaultAuthorizationAction determine whether there will be a redirection or override. The default action is redirect, but especially for API's an override will be more appropriate. When using rule-based security you can override these keys for any individual rule.

Validator

You can place a global validator in the configuration settings, but you can also override the validator on a module by module basis as well. The default validator is using the CBAuth Validator.

Authentication Services

cbsecurity ships with the cbauth module that can provide you with a nice interface for authentication services. If you use the default authenticationService authenticationService@cbauth, you have to define the UserServiceClass in the cbauth module. However, you can plug in any WireBox ID and select your own authentication services.

User Services

cbsecurity will also require a user service if you will be dealing with any JWT security tokens. Just add your WireBox ID to the user service of your choice. If you are using cbauth, you have to define the UserServiceClass in the cbauth module.

Automatic Firewall

Please note that by default, the security firewall will be auto-registered for you. If you do NOT want the firewall to be automatically registered for you, then use the autoLoadFirewall setting and make it false. Then you can use the Custom Firewall approach below to register the firewall manually in the order of the interceptors that you would like.

autoLoadFirewall : false

Annotation Security

By default, annotation security is enabled. This will inspect ALL incoming event executions for the security annotations. If you do not want to use annotation security we recommend you turn it off to avoid the inspection of events.

handlerAnnotationSecurity : false

Security Visualizer

ColdBox security comes with a nice graphical visualizer for all the registered security rules and settings in your global firewall. You can enable it by using the enableSecurityVisualizer setting.

enableSecurityVisualizer :  true

You can then visit the /cbsecurity URL and you will be presented with this magical tool:

Module Settings

Each module can override some settings for cbsecurity according to its needs. You will create a cbsecurity struct within the module's settings struct in the ModuleConfig.cfc

settings = {
    // CB Security Module Settings
    cbsecurity : {
        // Module Relocation when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthenticationEvent"  : "api:Home.onInvalidAuth",
        // Default Auhtentication Action: override or redirect when a user has not logged in
        "defaultAuthenticationAction" : "override",
        // Module override event when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthorizationEvent"   : "api:Home.onInvalidAuthorization",
        // Default invalid action: override or redirect when an invalid access is detected, default is to redirect
        "defaultAuthorizationAction"  : "override",
        // The validator to use for this module
        "validator"                   : "JWTService@cbsecurity",
        // You can define your security rules here or externally via a source
        "rules"                       : [ { "secureList" : "api:Secure\.*" } ]
    }
}

The settings you see above are the only ones that module's support as of now.

Custom Firewalls

You can also register multiple instances of the cbsecurity module using different configurations by just adding them to your app's config or even your module's configuration. This will register a NEW firewall apart from the global security firewall registered using the global settings as defined above.

interceptors = [

    {
        class="cbsecurity.interceptors.Security",
        name="FirewallName",
        properties={
            // All Settings from above
        }

]

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.

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

Then your file can be something like this:

[
    {
        "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
    }
]

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:

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.

Rule Sources

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

• DB

• Inline

• JSON

• Model

• XML

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

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.

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.

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

Small but big release!

• Feature : cbauth upgraded to version 4

You can register ANY authentication provider with cbsecurity by using the authenticationService setting. The value must be a valid WireBox Id and the object must adhere to the following interface. The authentication services can be used in conjunction with our JWT services and more features coming in the future.

// CB Security
cbSecurity : {
    
    // The WireBox ID of the authentication service to use in cbSecurity which must adhere to the cbsecurity.interfaces.IAuthService interface.
    "authenticationService" : "authenticationService@cbauth"
    
}

Authentication Service Interface

This interface has been provided by convenience and it is not mandatory at runtime (cbsecurity.interfaces.IAuthService)

/**
 * Copyright since 2016 by Ortus Solutions, Corp
 * www.ortussolutions.com
 * ---
 * If you register an authentication service with cbsecurity it must adhere to this interface
 */
interface{

    /**
     * Get the authenticated user
     *
	   * @throws NoUserLoggedIn : If the user is not logged in
	   *
     * @return User that implements IAuthUser
     */
    any function getUser();

    /**
     * Verifies if a user is logged in
     */
    boolean function isLoggedIn();

    /**
     * Try to authenticate a user into the system. If the authentication fails an exception is thrown, else the logged in user object is returned
     *
     * @username The username to log in with
     * @password The password to log in with
     *
     * @throws InvalidCredentials
	   *
	   * @return User : The logged in user object
     */
    any function authenticate( required username, required password );

    /**
  	 * Login a user into our persistent scopes
  	 *
  	 * @user The user object to log in
  	 *
  	 * @return The same user object so you can do functional goodness
	   */
    function login( required user );

    /**
     * Logs out the currently logged in user from the system
     */
    function logout();


}

You can find the information for cbauth in its own book:

User Interface

As you can see from above, the authentication services all expect a User object to model your user in the system. So your User object must also adhere to the following methods modeled by the cbsecurity.interfaces.IAuthUser interface. This will allow the validators and JWT services to get the appropriate data it needs.

interface{

    /**
     * Return the unique identifier for the user
     */
    function getId();

    /**
     * Verify if the user has one or more of the passed in permissions
     *
     * @permission One or a list of permissions to check for access
     *
     */
    boolean function hasPermission( required permission );

}

User Services

If you will be using cbauth or any of our JWT features, then we will also require you register a user service class that can provide us with the right data to encapsulate security using the userService setting. We have provided this interface for your usage:

interface{

    /**
     * Verify if the incoming username/password are valid credentials.
     *
     * @username The username
     * @password The password
     */
    boolean function isValidCredentials( required username, required password );

    /**
     * Retrieve a user by username
     *
     * @return User that implements JWTSubject and/or IAuthUser
     */
    function retrieveUserByUsername( required username );

    /**
     * Retrieve a user by unique identifier
     *
     * @id The unique identifier
     *
     * @return User that implements JWTSubject and/or IAuthUser
     */
    function retrieveUserById( required id );
}

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.

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

Then your xml file can look like this:

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

We have seen how the module works on the concept of rules and how to declare them. Before we dig deeper and decompose the rules let's have a look at the processing of the rules first.

Rule Anatomy

Each rule is modeled by a struct with keys in it:

{
    "whitelist"     : "", 
    "securelist"    : "", 
    "match"            : "event",  // or url
    "roles"            : "", 
    "permissions"    : "", 
    "redirect"         : "", 
    "overrideEvent"    : "", 
    "useSSL"        : false, 
    "action"        : "redirect", // or override 
    "module"        : ""
};

The only required key is the secureList which is what you are trying to secure. The rest are optional and described below. Please note that you can add as many keys as you like to your security rules, which can contain much more context and information for the validators to use for validation.

Rules processing

When processing rules, it is important to realize these rules come as an array which will be processed in order, so make sure your more specific rules will be processed before the more generic ones.

Rule Elements

Rule Overrides

As we saw from the overview and our configuration sections. We can declare the default actions for authorizations and authentication issues and to which events/URLs to go if that happens. There can be a time where you can override those global/module settings directly within a rule. Let's explore those overrides:

Redirect

If you add a redirect element, then you will be explicitly overriding the global/module setting and if a match is made a redirect will occur.

{
    "secureList" : "*",
    "redirect" : "mysecret.event"
}

OverrideEvent

If you add an overrideEvent element, then you will be explicitly overriding the global/module setting and an event override will occur.

{
    "secureList" : "*",
    "overrideEvent" : "main.onInvalidEvent"
}

Action

If you add a action element, then you will be explicitly overriding the global/module setting and the action will be based on this value (override or event)

{
    "secureList" : "^api.*",
    "action" : "override"
}

White Lists

If a rule has a white list, then it means that you can declare what are the exceptions to ALLOW if the incoming URL/event was matched against the securedList. This is a great way to say, hey secure all but allow the following events:

{
    "secureList" : ".*",
    "whitelist : "^login"
}

Sometimes you want to make sure ALL events are secured, except for the ones specified, such as login events. If you add new functionality to your app it is easy to forget a new rule. To prevent unwanted access you could specify a LAST rule, which matches ALL event but NO permission at all. In that case you have to add a whitelist for all events which should still pass, for example:

{
    "secureList" : ".*",
    "whitelist" : "login",
    "permissions" : "nonExistingPermission"
}

The security module also allows you to secure your events via annotations instead of using security rules. The setting that controls this security feature is the handlerAnnotationSecurity which can see in the

The security module has a tiered approach to annotation security as it will check the handler component first and then the requested action method second. You can apply different security contexts to each level as you see fit.

See the diagram below for inspecting security based on annotations:

Secure Annotation

The firewall will inspect handlers for a secured annotation. This annotation can be added to the entire handler or to an action method 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.

Authorization Context

You can also give the annotation a value, which can be anything you like: A list of roles, a role, a list of permissions, metadata, JSON, etc. Whatever it is, this is called the authorization context and the user validator must be able to not only authenticate but authorize the context or an invalid authorization will occur.

The secured value will be passed to the validator's for authorization.

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.

_securedURL

The security module has the concept of a secured URL which is the actual URL that got intercepted and relocated because of a security exception. If the module detects an invalid authentication or authorization and an action must be issued, then the firewall will store this URL in the RC scope and flash it so it can be available in the next request (if a relocation occurs).

The flash RAM variable is called: _securedURL. This key will be persisted in the flash memory of the framework and when the user gets relocated to the redirect element, this key will be populated in the request collection automatically for you.

So always remember to use this key if you want to provide a seamless login experience to your users. You can easily place it in the login form:

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 )

The security firewall will announce some interception events when invalid access or authorizations occur within the system:

• cbSecurity_onInvalidAuthentication

• cbSecurity_onInvalidAuthorization

You will receive the following data in the interceptData struct in each interception call:

• 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.

With these interceptions you can build a nice auditing system, login tracking and much more.

component extends="coldbox.system.Interceptor"{

    function cbSecurity_onInvalidAuthentication( event, interceptData ){
        // do what you like here
    }
    
    function cbSecurity_onInvalidAuthorization( event, interceptData ){
        // do what you like here
    }

}

Stop Processing Actions

The intercept data has a key called processActions which defaults to true. This Boolean indicator tells the firewall to process the invalid authentication/authorization procedures. If you change this value to false, then the firewall will do NOTHING because it is expecting for YOU to have done the actions.

JWT Interception

If you are using our JWT facilities, then we will announce the following interceptions during JWT usage:

• cbSecurity_onJWTCreation

• cbSecurity_onJWTInvalidation

• cbSecurity_onJWTValidAuthentication

• cbSecurity_onJWTInvalidUser

• cbSecurity_onJWTInvalidClaims

• cbSecurity_onJWTExpiration

• cbSecurity_onJWTStorageRejection

• cbSecurity_onJWTValidParsing

• cbSecurity_onJWTInvalidateAllTokens

Check them all out in our JWT Interceptions Page.

CBAuth Interceptions

You can always find the latest interception points here:

cbauth announces several custom interception points. You can use these interception points to change request data or add additional values to session or request scopes. The preAuthentication and postAuthentication events fire during the standard authenticate() method call with a username and password. The preLogin and postLogin events fire during the login() method call. The preLogout and postLogout events fire during the logout() method call.

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:

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.

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

Other Layers:

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:

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.

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:

secureWhen( context, [errorMessage] )

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

// Using as a closure/lambda
cbSecurity.secureWhen( ( user ) => !user.isConfirmed() )
cbSecurity.secureWhen( ( user ) => !oEntry.canPublish( user ) )

// Using a boolean evaluation
cbSecurity.secureWhen( cbSecurity.none( "AUTHOR_ADMIN" ) && !cbSecurity.sameUser( oAuthor )  )
cbSecurity.whenNone( "AUTHOR_ADMIN", ( user ) => relocate() );

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

( user ) => {}
function( user );

ColdBox security ships with the cbauth validator that knows how to talk to the authentication service and validate authentication and authorization via permissions. All you need to do is use the WireBox ID of CBAuthValidator@cbsecurity in your validator setting:

cbsecurity = {

    validator = "CBAuthValidator@cbsecurity"

}

Just make sure your User object adheres to our interface of IAuthUser.

Since version 2.4.x we have added the cbcsrf module as a dependency of cbSecurity. Below is how you can use it:

Settings

Below are the settings you can use for this module. Remember you must create the cbcsrf struct in your ColdBox.cfc under the moduleSettings structure:

moduleSettings = {
    cbcsrf : {
        // By default we load up an interceptor that verifies all non-GET incoming requests against the token validations
			enableAutoVerifier     : false,
			// A list of events to exclude from csrf verification, regex allowed: e.g. stripe\..*
			verifyExcludes         : [],
			// By default, all csrf tokens have a life-span of 30 minutes. After 30 minutes, they expire and we aut-generate new ones.
			// If you do not want expiring tokens, then set this value to 0
			rotationTimeout        : 30,
			// Enable the /cbcsrf/generate endpoint to generate cbcsrf tokens for secured users.
			enableEndpoint         : false,
			// The WireBox mapping to use for the CacheStorage
			cacheStorage           : "CacheStorage@cbstorages",
			// Enable/Disable the cbAuth login/logout listener in order to rotate keys
			enableAuthTokenRotator : false
    }
};

Mixins

This module will add the following UDF mixins to handlers, interceptors, layouts and views:

• csrfToken() : To generate a token, using the default or a custom key

• csrfVerify() : Verify a valid token or not

• csrf() : To generate a hidden field (csrf) with the token

• csrfField() : Generate a random token in a hidden form element and javascript that will refresh the page automatically when the token expires

• csrfRotate() : To wipe and rotate the tokens for the user

Here are the method signatures:

/**
 * Provides a random token and stores it in the coldbox cache storages. You can also provide a specific key to store.
 *
 * @key A random token is generated for the key provided.
 * @forceNew If set to true, a new token is generated every time the function is called. If false, in case a token exists for the key, the same key is returned.
 *
 * @return csrf token
 */
string function csrfToken( string key='', boolean forceNew=false )

/**
 * Validates the given token against the same stored in the session for a specific key.
 *
 * @token Token that to be validated against the token stored in the session.
 * @key The key against which the token be searched.
 *
 * @return Valid or Invalid Token
 */
boolean function csrfVerify( required string token='', string key='' )

/**
 * Generate a random token and build a hidden form element so you can submit it with your form
 *
 * @key A random token is generated for the key provided.
 * @forceNew If set to true, a new token is generated every time the function is called. If false, in case a token exists for the key, the same key is returned.
 *
 * @return HTML of the hidden field (csrf)
 */
string function csrf( string key='', boolean forceNew=false )

/**
 * Generate a random token in a hidden form element and javascript that will refresh the page automatically when the token expires
 * 
 * @key A random token is generated for the key provided. CFID is the default
 * @forceNew If set to true, a new token is generated every time the function is called. If false, in case a token exists for the key, the same key is returned.
 *
 * @return HTML of the hidden field (csrf)
 */
string function csrfField( string key='', boolean forceNew=false )

/**
 * Clears out all csrf token stored
 */
function csrfRotate()

Mappings

The module also registers the following mapping in WireBox: @cbcsrf so you can call our service model directly.

component{

    property name="cbcsrf" inject="@cbcsrf";
    
}

Automatic Token Expiration

By default, the module is configured to rotate all user csrf tokens every 30 minutes. This means that every token that gets created has a maximum life-span of {rotationTimeout} minutes. If you do NOT want the tokens to EVER expire during the user's logged in session, then use the value of 0 zero.

It is recommended to rotate your keys often, in case your token get's compromised.

Token Rotation

We have provided several methods to rotate or clear out all of a user's tokens. If you are using cbAuth as your module of choice for authentication, then we will listen to logins and logouts and rotate the keys for you if you have enabled the enableAuthTokenRotator setting.

moduleSettings = {
    cbcsrf : {
			// Enable/Disable the cbAuth login/logout listener in order to rotate keys
			enableAuthTokenRotator : true
    }
};

If you are NOT using cbAuth then we recommend you leverage the csrfRotate() mixin or the cbsrf.rotate() method on the @cbsrf model and do the manual rotation yourself.

component{

    function doLogin( event, rc, prc ){
    
        if( valid login ){
            // login user
            csrfRotate();
        }
    }
    
    function logout( event, rc, prc  ){
        csrfRotate();
    }

}

Simple Example

Below is a simple example of manually verifying tokens in your handlers:

component extends="coldbox.system.EventHandler"{

     function signUp( event, rc, prc ){
        // Store this in a hidden field in the form
        prc.token = csrfGenerate();
        event.setView( "registration/signup" );
    }

     function signUpProcess( event, rc, prc ){
        // Verify CSFR token from form
        if( csrfVerify( rc.token ?: '' ) {
            // save form
        } else {
            // Something isn't right
            relocate( 'handler.signup' );
        }
    }
}

Automatic Token Verifier

We have included an interceptor that if loaded will verify all incoming requests to make sure the token has been passed or it will throw an exception.

The settings for this feature are:

cbcsrf : {
    // Enable the verifier
    enableAutoVerifier : true,
    
    // A list of events to exclude from csrf verification, regex allowed: e.g. stripe\..*
    verifyExcludes : [
    
    ]
}

You can also register an array of regular expressions that will be tested against the incoming event and if matched, it will allow the request through with no verification.

The verification process is as follows:

• If we are doing an integration test, then skip verification

• If the incoming HTTP Method is a get,options or head skip verification

• If the incoming event matches any of the verifyExcludes setting, then skip verification

• If the action is marked with a skipCsrf annotation, then skip verification

• If no rc.csrf exists and no x-csrf-token header exists, throw a

  TokenNotFoundException exception

• If the token is invalid then throw a TokenMismatchException exception

Please note that this verifier will check the following locations for the token:

1. The request collection (rc) via the cbcsrf key

2. The request HTTP header (x-csrf-token) key

skipCsrf Annotation

You can also annotate your event handler actions with a skipCsrf annotation and the verifier will also skip the verification process for those actions.

component{

    function doTestSave( event, rc, prc ) skipCsrf{


    }

}

/cbcsrf/generate Endpoint

This module also allows you to turn on the generation HTTP endpoint via the enableEndpoint boolean setting. When turned on the module will register the following route: GET /cbcsrf/generate/:key?. You can use this endpoint to generate tokens for your users via AJAX or UI only applications. Please note that you can pass an optional /:key URL parameter that will generate the token for that specific key.

This endpoint should be secured, so we have annotated it with a secured annotation so if you are using cbSecurity or cbGuard this endpoint will only be available to logged in users.

Registration