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.

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

• 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

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

• 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

• 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

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

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

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)

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!

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

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 )

Small but big release!

• Feature : cbauth upgraded to version 4

Features

• Feature : Migrated from the jwt to the jwtcfml () 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 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

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.