Added

• Official Adobe 2023 Support

• Gitflows for testing all engines and all versions of ColdBox

• Added transientCache=false to auth User to avoid any issues when doing security operations

• Added population control for auth User for extra security

Fixed

• User auth was not serializing the id of the user in the mementifier config

Added

• Added guest() method to CBSecurity model and Authorizable delegate

Added

• Migrations table for security logs

• New bootsrap icons + css + js

• New github support files

Fixed

• getActionsReport() was not defaulting the type's structure, so exceptions would arise when there was no data in the visualizer

Added

• Added a new helper: createPassword() on the CBSecurity model to generate secure, random passwords with letters, symbols, and numbers.

• cbcsrf Upgraded to version 3, which we missed in the previous release.

Compatibility

• Dropped Adobe ColdFusion 2016

• New JwtAuthValidator instead of mixing concerns with the JwtService. You will have to update your configuration to use this validator instead of the JwtService

• All settings have changed. They are not single-level anymore. They are now grouped by functionality. Please see the Configuration area for the new approach.

Added

• New ability for the firewall to log all action events to a database table.

• If enabled, a new visualizer can visualize all settings and firewall events via the log table.

• New Basic Auth validator and basic auth user credentials storage system. This will allow you to secure apps where no database interaction is needed or required.

• New global and rule action: block and the firewall will block the request with a 401 Unauthorized page.

• New event cbSecurity_onFirewallBlock announced whenever the firewall blocks a request into the system with a 403.

• DBTokenStorage now rotates using the async scheduler and not direct usage anymore.

• Ability to set the cbcsrf module settings into the cbsecurity settings as csrf.

• We now default the user service class and the auth token rotation events according to the user authentication service (cbauth, etc.); no need to duplicate work.

• New rule-based IP security. You can add a allowedIPs key into any rule and add which IP Addresses are allowed into the match. By default, it matches all IPs.

• New rule-based HTTP method security. You can add a httpMethods key into any rule and add which HTTP methods are allowed into the match. By default, it matches all HTTP Verbs.

• New securityHeaders configuration to allow a developer to protect their apps from common exploits: XSS, HSTS, Content Type Options, host header validation, IP validation, clickjacking, non-SSL redirection, and much more.

• The security firewall now stores the authenticated user according to the prcUserVariable on authenticated calls via preProcess() no matter the validator used

• Dynamic Custom Claims: You can pass a function/closure as the value for a custom claim, and it will be evaluated at runtime, passing in the current claims before being encoded

• Allow passing in custom refresh token claims to attempt() and fromUser() and refreshToken() : refreshCustomClaims

• Added TokenInvalidException and TokenExpiredException to the refreshToken endpoint

Fixed

• Disable lastAccessTimeouts for JWT CacheTokenStorage BOX-128

• Fix spelling of property datasource on queryExecute that was causing a read issue.

Luis Fernando Majano Lainez

Luis is passionate about 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 are his favorite books(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

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

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

Charitable Proceeds

Shalom Children's Home

Shalom Children’s Home is one of the ministries dear to our hearts 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. A child sponsorship program supports the home.

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

System Requirements

• A database for optional firewall logging

• ColdBox 6+

• ColdBox 7+ for delegates and basic auth support only

Mixins

The following mixins are registered once the module is installed:

Configuration Settings

By default cbsecurity is configured to work with cbauth as the authentication service. You only need to provide a user service class that knows how to connect to your database to retrieve and validate credentials. You can also use the in-built basic authentication users as well.

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 3.0

Version 3 is a major rewrite of this module. It drops Adobe 2016 support and enhances the way the firewall is configured. It also add major capabilities for security headers, csrf settings and much more.

It also introduces the ability for the firewall to do 401 response blocks as actions for security rules. The CBSecurity visualizer is also a major addition that allows a developer or manager to visualize the performance of the firewall and visualize all the configurations necessary for operation.

Finally, we have introduced basic authentication for your applications with an optional user credential in-memory storage.

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!

CBSecurity 3 is a major release and it will require some updates in order for you to fully upgrade your previous versions.

Adobe 2016

This engine is no longer supported

JwtService Validator Deprecated

In the previous releases the validator for JWT was JwtService@cbsecurity. This has now changed to JwtAuthValidator@cbsecurity. So make sure you update your configurations.

CBAuthValidator Deprecated

The CBAuthValidator has been renamed to just AuthValidator. This validator is now not cbauth focused but IAuthService focused. It also supports role and permission based authorization.

Settings Structure

The entire settings structure has been redesigned to support many features in a a more concise and block approach. All top-level settings have been removed and added to specific sections. Please review the Configuration section in detail to see where the new settings belongs to.

The basicAuth key is used to store user credentials that will be used with Basic Authentication and how the passwords are stored in memory.

/**
 * --------------------------------------------------------------------------
 * Basic Auth
 * --------------------------------------------------------------------------
 * These settings are used so you can configure the hashing patterns of the user storage
 * included with cbsecurity.  These are only used if you are using the `BasicAuthUserService` as
 * your service of choice alongside the `BasicAuthValidator`
 */
basicAuth : {
	// Hashing algorithm to use
	hashAlgorithm  : "SHA-512",
	// Iterates the number of times the hash is computed to create a more computationally intensive hash.
	hashIterations : 5,
	// User storage: The `key` is the username. The value is the user credentials that can include
	// { roles: "", permissions : "", firstName : "", lastName : "", password : "" }
	users          : {}
}

HashAlgorithm

This is the default algorithm used when hashing the user storage passwords in memory. The default is SHA-512

hashAlgorithm  : "SHA-256",

HashIterations

Iterates the number of times the hash is computed to create a more computationally intensive hash. The default is 5

hashIterations  : 10,

Users

This is the in-memory user storage system. It's a struct and each key represents a unique username in the storage system. Each user can then have the following attributes, but in reality, you can add as many attributes as you want.

• password - The only mandatory attribute.

• firstName

• lastName

• roles

• permissions

users : {
    "lmajano" : { password : "test", permissions : "read,write",
    "guest" : { password : "guest", permissions : "read" }
}

The ColdBox cbsecurity module is a collection of modules to help secure your ColdBox 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 of incoming events or URL patterns

  • Handler annotations

• 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 ) which can be plug-and-play with your own or third-party modules

• Basic Authentication services that provide basic user credential storage and browser challenges

• A graphical user interface for visualizing the firewall and operational settings we lovingly call the CBSecurity Visualizer

• Industry-standard response headers to protect against XSS, clickjacking, frame busting, and much more

• Generate secure and random passwords

Module composition

Features

• Ability to have global security rules

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

• You can use ColdFusion authentication security

• Can leverage any custom authentication provider

• Plug any Authentication service or can leverage cbauth by default

• Ability to distinguish between invalid authentication and authorization and determine the process's outcome.

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

• The ability for each module to define its 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 in 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

Security Settings

By default, the security module will register itself for you using the module configuration settings you define in theconfig/ColdBox.cfc. You can create a cbsecurity key in the modulesettings or if you are in ColdBox 7 you can create a config/modules/cbsecurity.cfc as well.

Here you can see how to configure CBSecurity, but you can also navigate to the different configuration sections for an in-depth overview of those settings:

ColdBox Config

// Module Settings
moduleSettings = {
    cbauth = {
	// This is the path to your user object that contains the credential validation methods
	userServiceClass = ""
    },

    cbsecurity = {
	/**
	 * --------------------------------------------------------------------------
	 * Authentication Services
	 * --------------------------------------------------------------------------
	 * Here you will configure which service is in charge of providing authentication for your application.
	 * By default we leverage the cbauth module which expects you to connect it to a database via your own User Service.
	 *
	 * Available authentication providers:
	 * - cbauth : Leverages your own UserService that determines authentication and user retrieval
	 * - basicAuth : Leverages basic authentication and basic in-memory user registration in our configuration
	 * - custom : Any other service that adheres to our IAuthService interface
	 */
	authentication : {
		// The WireBox ID of the authentication service to use which must adhere to the cbsecurity.interfaces.IAuthService interface.
		"provider"        : "authenticationService@cbauth",
		// WireBox ID of the user service to use when leveraging user authentication, we default this to whatever is set
		// by cbauth or basic authentication. (Optional)
		"userService"     : "",
		// The name of the variable to use to store an authenticated user in prc scope on all incoming authenticated requests
		"prcUserVariable" : "oCurrentUser"
	},

	/**
	 * --------------------------------------------------------------------------
	 * Basic Auth
	 * --------------------------------------------------------------------------
	 * These settings are used so you can configure the hashing patterns of the user storage
	 * included with cbsecurity.  These are only used if you are using the `BasicAuthUserService` as
	 * your service of choice alongside the `BasicAuthValidator`
	 */
	basicAuth : {
		// Hashing algorithm to use
		hashAlgorithm  : "SHA-512",
		// Iterates the number of times the hash is computed to create a more computationally intensive hash.
		hashIterations : 5,
		// User storage: The `key` is the username. The value is the user credentials that can include
		// { roles: "", permissions : "", firstName : "", lastName : "", password : "" }
		users          : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * CSRF - Cross Site Request Forgery Settings
	 * --------------------------------------------------------------------------
	 * These settings configures the cbcsrf module. Look at the module configuration for more information
	 */
	csrf : {
		// 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 : true
	},
	/**
	 * --------------------------------------------------------------------------
	 * Firewall Settings
	 * --------------------------------------------------------------------------
	 * The firewall is used to block/check access on incoming requests via security rules or via annotation on handler actions.
	 * Here you can configure the operation of the firewall and especially what Validator will be in charge of verifying authentication/authorization
	 * during a matched request.
	 */
	firewall : {
		// Auto load the global security firewall automatically, else you can load it a-la-carte via the `Security` interceptor
		"autoLoadFirewall"            : true,
		// The Global validator is an object that will validate the firewall rules and annotations and provide feedback on either authentication or authorization issues.
		"validator"                   : "CBAuthValidator@cbsecurity",
		// Activate handler/action based annotation security
		"handlerAnnotationSecurity"   : true,
		// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
		"invalidAuthenticationEvent"  : "",
		// Default Auhtentication 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",
		// Firewall database event logs.
		"logs" : {
			"enabled"    : false,
			"dsn"        : "",
			"schema"     : "",
			"table"      : "cbsecurity_logs",
			"autoCreate" : true
		},
		// Firewall Rules, this can be a struct of detailed configuration
		// or a simple array of inline rules
		"rules"                       : {
			// Use regular expression matching on the rule match types
			"useRegex" : true,
			// Force SSL for all relocations
			"useSSL"   : false,
			// A collection of default name-value pairs to add to ALL rules
			// This way you can add global roles, permissions, redirects, etc
			"defaults" : {},
			// You can store all your rules in this inline array
			"inline"   : [],
			// If you don't store the rules inline, then you can use a provider to load the rules
			// The source can be a json file, an xml file, model, db
			// Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
			"provider" : { "source" : "", "properties" : {} }
		}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Visualizer
	 * --------------------------------------------------------------------------
	 * This is a debugging panel that when active, a developer can visualize security settings and more.
	 * You can use the `securityRule` to define what rule you want to use to secure the visualizer but make sure the `secured` flag is turned to true.
	 * You don't have to specify the `secureList` key, we will do that for you.
	 */
	visualizer : {
		"enabled"      : false,
		"secured"      : false,
		"securityRule" : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Headers
	 * --------------------------------------------------------------------------
	 * This section is the way to configure cbsecurity for header detection, inspection and setting for common
	 * security exploits like XSS, ClickJacking, Host Spoofing, IP Spoofing, Non SSL usage, HSTS and much more.
	 */
	securityHeaders                     : {
		// Master switch for security headers
		"enabled" : true,
		// If you trust the upstream then we will check the upstream first for specific headers
		"trustUpstream"         : false,
		// Content Security Policy
		// Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks,
		// including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft, to
		// site defacement, to malware distribution.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
		"contentSecurityPolicy" : {
			// Disabled by defautl as it is totally customizable
			"enabled" : false,
			// The custom policy to use, by default we don't include any
			"policy"  : ""
		},
		// The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in
		// the Content-Type headers should be followed and not be changed => X-Content-Type-Options: nosniff
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
		"contentTypeOptions" : { "enabled" : true },
		"customHeaders"      : {
			// Name : value pairs as you see fit.
		},
		// Disable Click jacking: X-Frame-Options: DENY OR SAMEORIGIN
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
		"frameOptions" : { "enabled" : true, "value" : "SAMEORIGIN" },
		// HTTP Strict Transport Security (HSTS)
		// The HTTP Strict-Transport-Security response header (often abbreviated as HSTS)
		// informs browsers that the site should only be accessed using HTTPS, and that any future attempts to access it
		// using HTTP should automatically be converted to HTTPS.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security,
		"hsts"         : {
			"enabled"           : true,
			// The time, in seconds, that the browser should remember that a site is only to be accessed using HTTPS, 1 year is the default
			"max-age"           : "31536000",
			// See Preloading Strict Transport Security for details. Not part of the specification.
			"preload"           : false,
			// If this optional parameter is specified, this rule applies to all of the site's subdomains as well.
			"includeSubDomains" : false
		},
		// Validates the host or x-forwarded-host to an allowed list of valid hosts
		"hostHeaderValidation" : {
			"enabled"      : false,
			// Allowed hosts list
			"allowedHosts" : ""
		},
		// Validates the ip address of the incoming request
		"ipValidation" : {
			"enabled"    : false,
			// Allowed IP list
			"allowedIPs" : ""
		},
		// The Referrer-Policy HTTP header controls how much referrer information (sent with the Referer header) should be included with requests.
		// Aside from the HTTP header, you can set this policy in HTML.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
		"referrerPolicy"     : { "enabled" : true, "policy" : "same-origin" },
		// Detect if the incoming requests are NON-SSL and if enabled, redirect with SSL
		"secureSSLRedirects" : { "enabled" : false },
		// Some browsers have built in support for filtering out reflected XSS attacks. Not foolproof, but it assists in XSS protection.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection,
		// X-XSS-Protection: 1; mode=block
		"xssProtection"      : { "enabled" : true, "mode" : "block" }
	},

	/**
	 * --------------------------------------------------------------------------
	 * Json Web Tokens Settings
	 * --------------------------------------------------------------------------
	 * Here you can configure the JWT services for operation and storage.  In order for your firewall
	 * to leverage JWT authentication/authorization you must make sure you use the `JwtAuthValidator` as your
	 * validator of choice; either globally or at the module level.
	 */
	jwt                          : {
		// The issuer authority for the tokens, placed in the `iss` claim
		"issuer"                  : "",
		// The jwt secret encoding key, defaults to getSystemEnv( "JWT_SECRET", "" )
		"secretKey"               : getSystemSetting( "JWT_SECRET", "" ),
		// by default it uses the authorization bearer header, but you can also pass a custom one as well.
		"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"          : 10080,
		// The Custom header to inspect for refresh tokens
		"customRefreshHeader"        : "x-refresh-token",
		// If enabled, the JWT validator will inspect the request for refresh tokens and expired access tokens
		// It will then automatically refresh them for you and return them back as
		// response headers in the same request according to the customRefreshHeader and customAuthHeader
		"enableAutoRefreshValidator" : false,
		// Enable the POST > /cbsecurity/refreshtoken API endpoint
		"enableRefreshEndpoint"      : true,
		// 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"
			}
		}
	}
};

ColdBox 7 Config

In ColdBox 7 you can segregate module configurations so they are more manageable and have their own identity. Just create a config/modules/cbsecurity.cfc with a nice configure() method:

component{
    
    function configure(){
        return {
	/**
	 * --------------------------------------------------------------------------
	 * Authentication Services
	 * --------------------------------------------------------------------------
	 * Here you will configure which service is in charge of providing authentication for your application.
	 * By default we leverage the cbauth module which expects you to connect it to a database via your own User Service.
	 *
	 * Available authentication providers:
	 * - cbauth : Leverages your own UserService that determines authentication and user retrieval
	 * - basicAuth : Leverages basic authentication and basic in-memory user registration in our configuration
	 * - custom : Any other service that adheres to our IAuthService interface
	 */
	authentication : {
		// The WireBox ID of the authentication service to use which must adhere to the cbsecurity.interfaces.IAuthService interface.
		"provider"        : "authenticationService@cbauth",
		// WireBox ID of the user service to use when leveraging user authentication, we default this to whatever is set
		// by cbauth or basic authentication. (Optional)
		"userService"     : "",
		// The name of the variable to use to store an authenticated user in prc scope on all incoming authenticated requests
		"prcUserVariable" : "oCurrentUser"
	},

	/**
	 * --------------------------------------------------------------------------
	 * Basic Auth
	 * --------------------------------------------------------------------------
	 * These settings are used so you can configure the hashing patterns of the user storage
	 * included with cbsecurity.  These are only used if you are using the `BasicAuthUserService` as
	 * your service of choice alongside the `BasicAuthValidator`
	 */
	basicAuth : {
		// Hashing algorithm to use
		hashAlgorithm  : "SHA-512",
		// Iterates the number of times the hash is computed to create a more computationally intensive hash.
		hashIterations : 5,
		// User storage: The `key` is the username. The value is the user credentials that can include
		// { roles: "", permissions : "", firstName : "", lastName : "", password : "" }
		users          : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * CSRF - Cross Site Request Forgery Settings
	 * --------------------------------------------------------------------------
	 * These settings configures the cbcsrf module. Look at the module configuration for more information
	 */
	csrf : {
		// 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 : true
	},
	/**
	 * --------------------------------------------------------------------------
	 * Firewall Settings
	 * --------------------------------------------------------------------------
	 * The firewall is used to block/check access on incoming requests via security rules or via annotation on handler actions.
	 * Here you can configure the operation of the firewall and especially what Validator will be in charge of verifying authentication/authorization
	 * during a matched request.
	 */
	firewall : {
		// Auto load the global security firewall automatically, else you can load it a-la-carte via the `Security` interceptor
		"autoLoadFirewall"            : true,
		// The Global validator is an object that will validate the firewall rules and annotations and provide feedback on either authentication or authorization issues.
		"validator"                   : "CBAuthValidator@cbsecurity",
		// Activate handler/action based annotation security
		"handlerAnnotationSecurity"   : true,
		// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
		"invalidAuthenticationEvent"  : "",
		// Default Auhtentication 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",
		// Firewall database event logs.
		"logs" : {
			"enabled"    : false,
			"dsn"        : "",
			"schema"     : "",
			"table"      : "cbsecurity_logs",
			"autoCreate" : true
		},
		// Firewall Rules, this can be a struct of detailed configuration
		// or a simple array of inline rules
		"rules"                       : {
			// Use regular expression matching on the rule match types
			"useRegex" : true,
			// Force SSL for all relocations
			"useSSL"   : false,
			// A collection of default name-value pairs to add to ALL rules
			// This way you can add global roles, permissions, redirects, etc
			"defaults" : {},
			// You can store all your rules in this inline array
			"inline"   : [],
			// If you don't store the rules inline, then you can use a provider to load the rules
			// The source can be a json file, an xml file, model, db
			// Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
			"provider" : { "source" : "", "properties" : {} }
		}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Visualizer
	 * --------------------------------------------------------------------------
	 * This is a debugging panel that when active, a developer can visualize security settings and more.
	 * You can use the `securityRule` to define what rule you want to use to secure the visualizer but make sure the `secured` flag is turned to true.
	 * You don't have to specify the `secureList` key, we will do that for you.
	 */
	visualizer : {
		"enabled"      : false,
		"secured"      : false,
		"securityRule" : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Headers
	 * --------------------------------------------------------------------------
	 * This section is the way to configure cbsecurity for header detection, inspection and setting for common
	 * security exploits like XSS, ClickJacking, Host Spoofing, IP Spoofing, Non SSL usage, HSTS and much more.
	 */
	securityHeaders                     : {
		// Master switch for security headers
		"enabled" : true,
		// If you trust the upstream then we will check the upstream first for specific headers
		"trustUpstream"         : false,
		// Content Security Policy
		// Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks,
		// including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft, to
		// site defacement, to malware distribution.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
		"contentSecurityPolicy" : {
			// Disabled by defautl as it is totally customizable
			"enabled" : false,
			// The custom policy to use, by default we don't include any
			"policy"  : ""
		},
		// The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in
		// the Content-Type headers should be followed and not be changed => X-Content-Type-Options: nosniff
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
		"contentTypeOptions" : { "enabled" : true },
		"customHeaders"      : {
			// Name : value pairs as you see fit.
		},
		// Disable Click jacking: X-Frame-Options: DENY OR SAMEORIGIN
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
		"frameOptions" : { "enabled" : true, "value" : "SAMEORIGIN" },
		// HTTP Strict Transport Security (HSTS)
		// The HTTP Strict-Transport-Security response header (often abbreviated as HSTS)
		// informs browsers that the site should only be accessed using HTTPS, and that any future attempts to access it
		// using HTTP should automatically be converted to HTTPS.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security,
		"hsts"         : {
			"enabled"           : true,
			// The time, in seconds, that the browser should remember that a site is only to be accessed using HTTPS, 1 year is the default
			"max-age"           : "31536000",
			// See Preloading Strict Transport Security for details. Not part of the specification.
			"preload"           : false,
			// If this optional parameter is specified, this rule applies to all of the site's subdomains as well.
			"includeSubDomains" : false
		},
		// Validates the host or x-forwarded-host to an allowed list of valid hosts
		"hostHeaderValidation" : {
			"enabled"      : false,
			// Allowed hosts list
			"allowedHosts" : ""
		},
		// Validates the ip address of the incoming request
		"ipValidation" : {
			"enabled"    : false,
			// Allowed IP list
			"allowedIPs" : ""
		},
		// The Referrer-Policy HTTP header controls how much referrer information (sent with the Referer header) should be included with requests.
		// Aside from the HTTP header, you can set this policy in HTML.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
		"referrerPolicy"     : { "enabled" : true, "policy" : "same-origin" },
		// Detect if the incoming requests are NON-SSL and if enabled, redirect with SSL
		"secureSSLRedirects" : { "enabled" : false },
		// Some browsers have built in support for filtering out reflected XSS attacks. Not foolproof, but it assists in XSS protection.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection,
		// X-XSS-Protection: 1; mode=block
		"xssProtection"      : { "enabled" : true, "mode" : "block" }
	},

	/**
	 * --------------------------------------------------------------------------
	 * Json Web Tokens Settings
	 * --------------------------------------------------------------------------
	 * Here you can configure the JWT services for operation and storage.  In order for your firewall
	 * to leverage JWT authentication/authorization you must make sure you use the `JwtAuthValidator` as your
	 * validator of choice; either globally or at the module level.
	 */
	jwt                          : {
		// The issuer authority for the tokens, placed in the `iss` claim
		"issuer"                  : "",
		// The jwt secret encoding key, defaults to getSystemEnv( "JWT_SECRET", "" )
		"secretKey"               : getSystemSetting( "JWT_SECRET", "" ),
		// by default it uses the authorization bearer header, but you can also pass a custom one as well.
		"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"          : 10080,
		// The Custom header to inspect for refresh tokens
		"customRefreshHeader"        : "x-refresh-token",
		// If enabled, the JWT validator will inspect the request for refresh tokens and expired access tokens
		// It will then automatically refresh them for you and return them back as
		// response headers in the same request according to the customRefreshHeader and customAuthHeader
		"enableAutoRefreshValidator" : false,
		// Enable the POST > /cbsecurity/refreshtoken API endpoint
		"enableRefreshEndpoint"      : true,
		// 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"
			}
		}
	};
    }
}

Module Settings

Each module can also have its own CBSecurity settings which override or collaborate with the global settings. So what can a module do:

• Have its own validator

• Have its own security rules

• Have its own invalid authentication event and action

• Have its own invalid authorization event and action

You will create a cbsecurity struct within the module's settings struct in the ModuleConfig.cfc

settings = {
    // CB Security Module Settings
    cbsecurity : {
      firewall : {
        // 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",
        // Inline rules
        "rules"                       : [ { "secureList" : "api:Secure\.*" } ]
        // Full rules
        // or a simple array of inline rules
	"rules"                       : {
	    // Use regular expression matching on the rule match types
	    "useRegex" : true,
	    // Force SSL for all relocations
	    "useSSL"   : false,
	    // A collection of default name-value pairs to add to ALL rules
	    // This way you can add global roles, permissions, redirects, etc
	    "defaults" : {},
	    // You can store all your rules in this inline array
	    "inline"   : [],
	    // If you don't store the rules inline, then you can use a provider to load the rules
	    // The source can be a json file, an xml file, model, db
	    // Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
	    "provider" : { "source" : "", "properties" : {} }
	}
      }
    }
}

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.

CBSecurity also allows you to store your security rules in a database as long as all the columns match the keys of the rules as we saw in the rule anatomy.

You will use the db as the source and fill out the available db properties:

// CB Security
cbSecurity : {
  firewall : {
    rules : {
      provider : {
        "source" : "db",
        "properties" : {
            "dsn" : "myapp",
            "sql" : "",
            "table" : "securityRules",
            "orderBy" : "order asc"
        }
      }
    }
  }
}

• The dsn property is the name of the datasource to use

• The table property is what table the rules are stored in

• The orderBy property is what order by SQL to use, by default it is empty

• The sql property is what SQL to execute to retrieve the rules. The default is select * from ${table}

You can place all your security rules inside of a JSON file and then tell CBSecurity where they are:

// CB Security
cbSecurity : {
  firewall : {
    rules : {
      provider : {
        "source" : "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
    }
]

Global Configuration

Here is the default configuration for our JSON Web Tokens integration:

cbsecurity : {
    /**
     * --------------------------------------------------------------------------
     * Json Web Tokens Settings
     * --------------------------------------------------------------------------
     * Here you can configure the JWT services for operation and storage.  In order for your firewall
     * to leverage JWT authentication/authorization you must make sure you use the `JwtAuthValidator` as your
     * validator of choice; either globally or at the module level.
     */
    jwt                     : {
        // The issuer authority for the tokens, placed in the `iss` claim
        issuer                          : "",
        // The jwt secret encoding key, defaults to getSystemEnv( "JWT_SECRET", "" )
        // This key is only effective within the `config/Coldbox.cfc`. Specifying within a module does nothing.
        secretKey               : getSystemSetting( "JWT_SECRET", "" ),
        // by default it uses the authorization bearer header, but you can also pass a custom one as well.
        customAuthHeader        : "x-auth-token",
        // The expiration in minutes for the jwt tokens
        expiration              : 60, 
        // If true, enables refresh tokens, token creation methods will return a struct instead
        // of just the access token. e.g. { access_token: "", refresh_token : "" }
        enableRefreshTokens        : false,
        // The default expiration for refresh tokens, defaults to 30 days
        refreshExpiration          : 10080,
        // The Custom header to inspect for refresh tokens
        customRefreshHeader        : "x-refresh-token",
        // If enabled, the JWT validator will inspect the request for refresh tokens and expired access tokens
        // It will then automatically refresh them for you and return them back as
        // response headers in the same request according to the customRefreshHeader and customAuthHeader
        enableAutoRefreshValidator : false,
        // Enable the POST > /cbsecurity/refreshtoken API endpoint
        enableRefreshEndpoint      : true,
        // 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"
            }
        }
    }
}

issuer

The issuer authority for the tokens is placed in the iss claim of the token. If empty, we will use the event.buildLink() to create the issuer. By default, our validators also check that tokens are created by the same issuer.

secretKey

The secret key is used to sign the JWT tokens. By default, it will try to load an environment variable called JWT_SECRET , if that setting is also empty, we will auto-generate a secret token that will last as long as the ColdFusion application scope lasts. So technically, your secret will rotate only if a secret is not specified.

Also, this key is ignored in modules. To specify a fixed key to be used in your modules, you will have to configure it by adding a cbsecurity key settings in the moduleSettings structure within the config/Coldbox.cfc.

customAuthHeader

By default, our jwt services will look into the authorization header for a bearer token. However, it can also look in a custom header by this name, which defaults to x-auth-token. Finally, if not found, it will also look into the rc scope for a rc[ 'x-auth-token' ] as well.

expiration

The default expiration in minutes for the JWT tokens. Defaults to 60 minutes

algorithm

The encryption algorithm to use for the tokens. The default is HS512, but the available ones for are:

• HS256

• HS384

• HS512

• RS256

• RS384

• RS512

• ES256

• ES384

• ES512

In the case of the RS and ES algorithms, asymmetric keys are expected to be provided in unencrypted PEM or JWK format (in the latter case, first deserialize the JWK to a CFML struct). When using PEM, private keys must be encoded in PKCS#8 format.

If your private key is not currently in this format, conversion should be straightforward:

$ openssl pkcs8 -topk8 -nocrypt -in privatekey.pem -out privatekey.pk8

When decoding tokens, either a public key or certificate can be provided. (If a certificate is provided, the public key will be extracted.)

requiredClaims

This is an array of claim names that each token MUST have in order to be authenticated. If a token comes in but does not have these claims in the payload structure, it will be deemed invalid.

tokenStorage

By default, our JWT services will store tokens in CacheBox for you in order to be able to invalidate them. We ship with two providers for token storage: db and cachebox.

Enabled

By default, the token storage is enabled.

KeyPrefix

The key prefix to use when storing the keys in permanent storage. Defaults to cbjwt_

Driver

The driver to use. It can be either db or cachebox or your own WireBox Id for using custom storage.

Properties

A struct of properties to configure each storage with.

Refresh Token Configuration

Refresh tokens have several configuration items; check them out in our refresh token configuration section.

Here are the default settings for configuring the security firewall in CBSecurity:

/**
 * --------------------------------------------------------------------------
 * Firewall Settings
 * --------------------------------------------------------------------------
 * The firewall is used to block/check access on incoming requests via security rules or via annotation on handler actions.
 * Here you can configure the operation of the firewall and especially what Validator will be in charge of verifying authentication/authorization
 * during a matched request.
 */
firewall : {
	// Auto load the global security firewall automatically, else you can load it a-la-carte via the `Security` interceptor
	"autoLoadFirewall"            : true,
	// The Global validator is an object that will validate the firewall rules and annotations and provide feedback on either authentication or authorization issues.
	"validator"                   : "CBAuthValidator@cbsecurity",
	// Activate handler/action based annotation security
	"handlerAnnotationSecurity"   : true,
	// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
	"invalidAuthenticationEvent"  : "",
	// Default Auhtentication 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",
	// Firewall database event logs.
	"logs" : {
		"enabled"    : false,
		"dsn"        : "",
		"schema"     : "",
		"table"      : "cbsecurity_logs",
		"autoCreate" : true
	}
	// Firewall Rules, this can be a struct of detailed configuration
	// or a simple array of inline rules
	"rules"                       : {
		// Use regular expression matching on the rule match types
		"useRegex" : true,
		// Force SSL for all relocations
		"useSSL"   : false,
		// A collection of default name-value pairs to add to ALL rules
		// This way you can add global roles, permissions, redirects, etc
		"defaults" : {},
		// You can store all your rules in this inline array
		"inline"   : [],
		// If you don't store the rules inline, then you can use a provider to load the rules
		// The source can be a json file, an xml file, model, db
		// Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
		"provider" : { "source" : "", "properties" : {} }
	}
},

AutoLoadFirewall

The security firewall is always enabled by default, but you can disable it globally if you like.

autoLoadFirewall : false

HandlerAnnotationSecurity

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

handlerAnnotationSecurity : false

Validator

This global validator will be used to validate authentication/authorization. The default is CBAuthValidator@cbsecurity. This object needs to match the interface: cbsecurity.interfaces.ISecurityValidator . The available validators we ship are:

• CBAuth Validator: this is the default validator, which uses 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 role-based security.

• Basic Auth Validator: This validator secures your app via basic authentication browser challenges to incoming requests. It can also work with the BasicAuthUserService and provide you a basic user credentials storage within your configuration file.

• JWT Validator: If you want to use JSON Web Tokens, the JWT Validator provides authorization and authentication by validating incoming access/refresh tokens via headers for RESTFul API communications.

• Custom Validator: You can define your own authentication and authorization engines and plug them into the cbsecurity framework.

validator : "BasicAuthValidator@cbsecurity"

InvalidAuthenticationEvent

This setting is used to set the global event that will be executed or redirected to if an invalid authentication is detected. Usually, you want to direct users to a login screen.

"invalidAuthenticationEvent"  : "security.login",

DefaultAuthenticationAction

We set the default event above, but how do we get there? This setting is the action the firewall will take when an invalid authentication event is detected.

1. redirect - Redirect them to the invalidAuthenticationEvent

2. override - Override the incoming event to the invalidAuthenticationEvent

3. block - Block the request entirely with a 401 Not Authorized response.

InvalidAuthorizationEvent

This setting is used to set the global event that will be executed or redirected to if an invalid authorization is detected. Usually, you could direct them to a not authorized page.

"invalidAuthorizationEvent"  : "dashboard.notAuthorized",

DefaultAuthorizationAction

We set the default event above, but how do we get there? This setting is the action the firewall will take when an invalid authorization event is detected.

1. redirect - Redirect them to the invalidAuthorizationEvent

2. override - Override the incoming event to the invalidAuthorizationEvent

3. block - Block the request entirely with a 401 Not Authorized response.

Logs

You can enable the firewall logs, and CBSecurity will log all blocks the firewall detects. By default, it is disabled, but if you enable the logs, we will create the table for you.

"logs" : {
    "enabled"    : false,
    "dsn"        : "",
    "schema"     : "",
    "table"      : "cbsecurity_logs",
    "autoCreate" : true
}

We have also included a migrations file so you can add this to your database migrations schemas. Just run: migrate create create_cbsecurity_logs_table and fill it out with this:

component {

	variables.INDEX_COLUMNS = [
		"userId",
		"userAgent",
		"ip",
		"host",
		"httpMethod",
		"path",
		"referer"
	];

	function up( schema, qb ){
		schema.create( "cbsecurity_logs", function( table ){
			table.string( "id", 36 ).primaryKey();
			table.timestamp( "logDate" ).withCurrent();
			table.string( "action" );
			table.string( "blockType" );
			table.string( "ip" );
			table.string( "host" );
			table.string( "httpMethod" );
			table.string( "path" );
			table.string( "queryString" );
			table.string( "referer" ).nullable();
			table.string( "userAgent" );
			table.string( "userId" ).nullable();
			table.longText( "securityRule" ).nullable();
			table.index( [ "logDate", "action", "blockType" ], "idx_cbsecurity" );

			INDEX_COLUMNS.each( ( key ) => {
				table.index( [ arguments.key ], "idx_cbsecurity_#arguments.key#" );
			} );
		} );
	}

	function down( schema, qb ){
		schema.drop( "cbsecurity_logs" );
	}

}

Rules

This key defines where rules come from and how they interact with the firewall. The rules key can be of two types:

• An array of rules

• A struct of configuration with a rule source

Array of Rules

This is the shorthand way of defining global rules.

"rules" : [
	// should use direct action and do a global redirect
	{
		"whitelist"   : "",
		"securelist"  : "admin",
		"match"       : "event",
		"roles"       : "admin",
		"permissions" : "",
		"action"      : "redirect",
		"httpMethods" : "*"
	},
	// Match only put/post
	{
		"whitelist"   : "",
		"securelist"  : "putpost",
		"match"       : "event",
		"roles"       : "",
		"permissions" : "",
		"action"      : "block",
		"httpMethods" : "put,post"
	},
	{
		"whitelist"   : "",
		"securelist"  : "cfide",
		"match"       : "url",
		"roles"       : "",
		"permissions" : "",
		"action"      : "redirect",
		"allowedIPs"  : "10.0.0.1"
	},
	// no action, use global default action
	{
		"whitelist"   : "",
		"securelist"  : "noAction",
		"match"       : "url",
		"roles"       : "admin",
		"permissions" : "",
		"httpMethods" : "*"
	}
]

Rule Configuration

If this setting is a struct, you can configure how the rules behave and where they come from JSON, XML, database, model, etc.

"rules" : {
    // Use regular expression matching on the rule match types
    "useRegex" : true,
    // Force SSL for all relocations
    "useSSL"   : false,
    // A collection of default name-value pairs to add to ALL rules
    // This way you can add global roles, permissions, redirects, etc
    "defaults" : {},
    // You can store all your rules in this inline array
    "inline"   : [],
    // If you don't store the rules inline, then you can use a provider to load the rules
    // The source can be a json file, an xml file, model, db
    // Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
    "provider" : { "source" : "", "properties" : {} }
}

useRegex

This is true by default. It tells the firewall to use regular expression matching against white and secure lists in a rule.

useSSL

If true then if a security rule needs to do a redirect, it will force the redirect to SSL. This defaults to false.

defaults

This is a collection of name-value pairs that each security rule will inherit by default.

defaults : {
    action : "block",
    roles  : "users"
}

inline

This is an array that holds all the rules you can define in CFML. This is the same as making the entire rules key an array of rules.

"rules" : {
    // You can store all your rules in this inline array
    "inline"   : [
	// should use direct action and do a global redirect
	{
		"whitelist"   : "",
		"securelist"  : "admin",
		"match"       : "event",
		"roles"       : "admin",
		"permissions" : "",
		"action"      : "redirect",
		"httpMethods" : "*"
	},
	// Match only put/post
	{
		"whitelist"   : "",
		"securelist"  : "putpost",
		"match"       : "event",
		"roles"       : "",
		"permissions" : "",
		"action"      : "block",
		"httpMethods" : "put,post"
	}
    ]
}

provider

The provider key is how you can define rules from the following sources:

• A JSON file

• An XML file

• From a model object via a method call

• From a database

Here are the different ways you can define rules from other sources rather than inline:

Provider

The provider key is the WireBox ID of the authentication service that must adhere to our interface.

UserService

This key is not mandatory and will be automatically filled out from the cbauth user service class by default. This class is used for CBSecurity to know how to retrieve users and validate credentials from whatever storage system you use. This value can be a WireBox ID, and the object must adhere to our interface: cbsecurity.interfaces.IUserService.

prcUserVariable

This is a convenience setting that tells CBSecurity into which prc (private request context) variable to store the authenticated user on EVERY request. This allows your entire codebase to talk to a single variable for the authenticated user.

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:

CBSecurity Security Firewall

With CBSecurity, you can secure all your incoming ColdBox events from execution through security rules or discrete annotations within your handler's code. You will also be able to leverage our CBSecurity service model to secure any code context anywhere, from execution blocks to views and much more.

The module wraps itself around the preProcess interception point (The first execution of a ColdBox request) will try to validate if the request has been authenticated and authorized to execute.

Validators

This is done via security rules and/or annotations on the requested handler actions and through a CBSecurity Validator which knows how to authenticate and authorize the request. CBSecurity ships with many validators:

• Auth Validator: this is the default validator, which provides authentication and permission-based security through our IAuthService and IAuthUser interfaces.

• 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 role-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 via headers for RESTFul API communications.

• Custom Validator: You can define your own authentication and authorization engines and plug them into 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.

The validator has two options to determine if the user will be allowed access:

You can use rules, annotations, or even both. Rules are much more flexible and can be visualized in our security visualizer. Also, note that 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. It can also determine if the firewall should block the request.

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

• If firewall database logging is turned on, we will log the block in our database logs so the visualizer can represent them.

• The current requested URL will be flashed into ColdBox Flash 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 or a firewall block).

• If the type is authorization the default action (defaultAuthorizationAction) for that type will be executed (An override or a relocation or a firewall block).

Security Rules vs. Annotation Security

Here are the basics of a security rule which can be defined in JSON, XML, database or CFML. Please note that only the following keys are mandatory:

• securelist

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 are very static.

• Annotations can protect events. Rules can protect events and incoming URLs.

• Rules allow you to change your actions (override, redirect, or block) and target 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 or any method of your choice

Rule Anatomy

A rule is a struct that can be composed of the following elements. All of them are optional except the secureList.

Global Rules

Rules can be declared globally in your config/ColdBox.cfc or they can also be placed in any custom module in your application. Here is the shorthand approach to defining rules:

As you can see, you can combine all the security rule keys as you see fit. Here is the same config, but the rules will come from a JSON file:

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. This 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, etc. Whatever it is, this is the authorization context, and the user validator must be able to authenticate but authorize the context, or an invalid authorization will occur. Ultimately it's up to the Validator to decide what that value does and means.

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 Validators

As we mentioned at the beginning of this overview, the security module will use a Validator object 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(). The validator can also be selected on a per module basis as well.

Each validator must return a struct with the following keys:

• allow:boolean A Boolean indicator if authentication or authorization was violated and we should block or not. True = allow, false = block

• type:stringOf(authentication|authorization) A string that indicates the type of violation: authentication or authorization.

• messages:string Info or debugging messages

AuthValidator

ColdBox security ships with the AuthValidator@cbsecurity which is the default validator in the configuration setting validator. This validator can talk to ANY authentication service as long as it implements our IAuthService interface. The typical methods it calls on your authentication service are:

• isLoggedIn()

• getUser()

It will then also talk to the User object returned from getUser() which must implement the IAuthUser interface. The typical methods called on your User object are:

• hasRole()

• hasPermission()

These methods are used in order to determine authorizations.

BasicAuthValidator

This validator also ships with CBSecurity which will challenge users with browser-based basic authentication. When used, it will use whatever authentication system and user service you have configured. If you don't change the default settings, then CBSecurity will switch to using the BasicAuthUserService which allows you to store user credentials in your configuration file. Let's see how to do that:

With this configuration, the basic auth validator will allow users to log in via the browser's basic authentication. What about logging out then? Well, you have two options:

1. Close your browser, which clears the session

2. We ship with an endpoint to call for securely logging out: /cbsecurity/basicauth/logout

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:

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 three outcomes:

• Relocation to another event or URL

• An event override

• A firewall 401 Not Authorized block

Interceptions

Authentication / Authorization

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.

Firewall Blocks

• cbSecurity_onFirewallBlock - When the firewall blocks an incoming request with a 403

You will receive the following data in the interceptData struct:

• type : The type of block: hostheader or ipvalidation

• config : The configuration structure of the rule

• incomingIP : The incoming ip if the type is ipValiation

• incomingHost : The incoming host if the type is hostHeader

CBSecurity Model

The CBSecurity model was introduced in version 2.3.0, and it provides you with a way to provide authorization checks, utility security methods, and security 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:

Once injected, you can leverage it using our extraordinary 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] )

Action Context Methods

When a 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 )

Authentication Methods

You can leverage the model to do the following authentication-related methods:

• authenticate( username, password ) : Authenticate a user

• getAuthService() : Get the configured auth service

• getUserService() : Get the configured user service

• getUser() : Get the authenticated user

• isLoggedIn() : Verify if a request is logged in

• logout() : Logout via the configured auth service

Utility Methods

You can use the following methods to assist in your programming needs:

• createPassword( length:32, letters:true, numbers:true, symbols:true ) : Generate a random and secure password

• getRealIP( trustUpstream : true ) : Get a request's actual IP address

• getRealHost( trustUpstream : true ) : Get a request's actual hostname used

Security Visualizer

This module also ships with a security visualizer that will provide you with the following features:

• Visual representation of all settings

• Firewall reports

• Firewall activity logs

• Firewall rule simulator

• Much more

You can access it via the /cbsecurity endpoint.

Here are the quick visualizer configurations:

You can also secure it by adding secured = true which will create a new rule in the firewall where authentication is required in order to access the /cbsecurity endpoint. You can also modify the security rule by leveraging the securityRule key with whatever key options you would like to add.

JSON Web Tokens (JWT) REST Security

CBSecurity ships with the cbsrf module and can be configured in line with the cbsecurity key.

EnableAutoVerifier

By default, this setting is turned off. If you turn it on, then every non-GET request will be verified that it contains a valid incoming csrf token via a header or the incoming rc.

VerifyExcludes

A list of regex patterns that will match against the incoming event. If matched, then that event will be excluded from the auto-verifier.

RotationTimeout

All csrf tokens have a life span of 30 minutes. But you can control how long they live with this setting.

EnableEndpoint

This setting enables the GET /cbcsrf/generate endpoint to generate csrf tokens for secured users. You can use this endpoint to generate user tokens 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.

CacheStorage

EnableAuthTokenRotator

This setting is enabled by default and what it does is that it will rotate a user's secret keys when they login/logout via any authentication service registered with CBSecurity.

If you prefer to store your rules your way, CBSecurity can talk to any WireBox ID or model and get the rules from them by using the model source in the rule provider.

• The model property is any WireBox ID or classpath

• The method property is the name of the method to call to get an array of rules back

CBSecurity comes bundled with tons of security response features to help developers be secure-minded about their applications. Here are the defaults for configuring the security headers in CBSecurity.

TrustUpstream

This boolean flag tells CBSecurity whether to inspect x-forwarded- headers FIRST instead of traditional host/IP headers. If you trust your proxies, then turn this setting to true.

ContentSecurityPolicy

The Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for data theft, site defacement, and malware distribution.

By default, this policy is disabled as it requires a custom policy to be written according to your needs. Once you have a policy available, you can add it to the configuration.

ContentTypeOptions

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should be followed and not be changed. This produces the following header => X-Content-Type-Options: nosniff

CustomHeaders

You can fill out this struct with the custom headers you would like to send out on EVERY request. The header value can be a simple value to return always or a closure/lambda that will be executed at runtime and the value sent on every request.

Please note that the closure accepts the incoming event, rc, and prc variables.

FrameOptions

HSTS - HTTP Strict Transport Security

The HTTP Strict-Transport-Security response header (often abbreviated as HSTS) informs browsers that the site should only be accessed using HTTPS and that any future attempts to access it using HTTP should automatically be converted to HTTPS. Here are the defaults we use in CBSecurity:

HostHeaderValidation

This configuration setting can restrict access to your application for ONLY a specific list of hosts. This prevents host spoofing. If an invalid host is detected, a 401 Not Authorized response will be sent back to the user. This setting is disabled by default.

IPValidation

This configuration setting can restrict access to your application for ONLY a specific list of IP addresses. This prevents IP spoofing. If an invalid IP is detected, then a 401 Not Authorized response will be sent back to the user. This setting is disabled by default.

ReferrerPolicy

The Referrer-Policy HTTP header controls how much referrer information (sent with the Referer header) should be included with requests. Aside from the HTTP header, you can set this policy in HTML. This setting is enabled by default with a policy of same-origin.

Here are some available policies:

SecureSSLRedirects

Detect if the incoming requests are NON-SSL and redirect with SSL alongside any incoming query strings and host information if enabled. By default, this setting is disabled.

XSSProtection

Some browsers have built-in support for filtering out reflected XSS attacks. Not foolproof, but it assists in XSS protection. By default, it is enabled and a block mode is produced.

You can place all your security rules inside of an XML file and then tell CBSecurity where they are:

Then your XML file can look like this:

You can leverage the CBSecurity model to get insight into some aspects of the authentication process or do authentication via the configured authentication service if needed.

Configured Services

• getAuthService() - Get access to the configured authentication service

• getUserService() - Get access to the configured user service

Authentication Context

• authenticate( username, password ) - Authenticate a request

• getUser() - Get the authenticated user of the current request

• guest() - Verify if the users is NOT logged in, but a guest

• isLoggedIn() - Verify if the current request has authenticated

• logout() - Logout the authenticated user

CBSecurity also allows you to secure your events via annotations instead of security rules. The setting that controls this security feature is called handlerAnnotationSecurity , which can be set in the configuration section.

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. This means we need a user to be authenticated to access the action.

// Secure the entire handler
component secured{

	function index(event,rc,prc){}
	function list(event,rc,prc){}

}
// Same as this
component secured=true{
}

// Do NOT secure the handler
component secured=false{
}
// Same as this, no annotation!
component{

	function index(event,rc,prc) secured{
	}

	function list(event,rc,prc) secured="list"{

	}
	
}

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 authenticate and authorize the context, or an invalid authorization will occur.

// Secure this handler
component secured="admin,users"{

	function index(event,rc,prc) secured="list"{

	}
	
	function save(event,rc,prc) secured="write"{

	}

}

The secured value will be passed to the validator 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.

CBSecurity supports the concept of HTTP basic authentication in your ColdBox applications. Please note that this is a quick and easy way to provide security, but not the safest by any means. You have been warned!

What is Basic Authentication?

In the context of an HTTP transaction, basic access authentication is a method for an HTTP user agent (e.g. a web browser) to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the Base64 encoding of ID and password joined by a single colon :.

Configuration

The first step is configuring your application to use basic authentication as the validator of choice. We will configure two things:

• Validator: BasicAuthValidator@cbsecurity

• Basic auth settings: Where you configure users, passwords, roles, permissions, and encryption

CBSecurity allows you to use basic authentication with ANY authentication service.

cbsecurity : {
    
    basicAuth : {
	users : {
	  "lmajano" : { password : 'test', permissions : "", roles : "admin" }
	}
    },
    
    firewall : {
        // Global Relocation when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthenticationEvent" : "main.index",
        // Default invalid action: override or redirect when an invalid access is detected, default is to redirect
        "defaultAuthenticationAction" : "redirect",
        // Global override event when an invalid access is detected, instead of each rule declaring one.
        "invalidAuthorizationEvent"  : "main.index",
        // Default invalid action: override or redirect when an invalid access is detected, default is to redirect
        "defaultAuthorizationAction" : "redirect",
        // Firewall Validator
        "validator"                   : "BasicAuthValidator@cbsecurity"
    }

}

This is the most basic configuration where we register a single user and tell the firewall to use the basic auth validator. Since the default authentication service is cbauth I don't have to register it. Finally, since CBSecurity detects the BasicAuthValidatorand no registered user class, it will register the BasicAuthUserService as well for you.

All I have to do now is create security rules or annotations, and CBSecurity will leverage the browser's Basic Authentication Prompt when those resources are trying to be accessed. Once you put in your credentials, it will verify them against the registered users in the basicAuth configuration dictionary.

Logout

Since Basic Authentication ONLY focuses on login, logout is left out of the equation. In CBSecurity, we have created a special event so you can securely log out users from basic authentication, which you can hit with ANY HTTP verb.

/cbsecurity/basicauth/logout

This will call the logout method of the authentication service and set the following HTTP headers for you so your session can be rotated:

event
    .setHTTPHeader( name = "WWW-Authenticate", value = "basic realm='Please enter your credentials'" )
    .setHTTPHeader( name = "Cache-Control", value = "no-cache, must-revalidate, max-age=0" )
    .renderData( data = "<h1>Logout Successful!</h1>", statusCode = 401 );

Ultimately, you can close your browser too.

ColdBox Request Context

ColdBox also supports the concept of basic authentication retrieval since the early version 2 days. ColdBox can detect, parse and give you a struct of username and password by leveraging the request context's getHTTPBasicCredentials() method.

function preHandler( event, action, eventArguments ){
    var authDetails = event.getHTTPBasicCredentials();
    if( !securityService.authenticate( authDetails.username, authDetails.password ) ) {
        event.renderData( type="JSON", data={ message = 'Please check your credentials' }, statusCode=401, statusMessage="You're not authorized to do that");
    }
}

The CBSecurity visualizer is a tool that will allow you to visualize all of your configuration settings, firewall logs, and much more. By default, the visualizer is disabled.

If enabled, you can visit the /cbsecurity entry point, and you will get the visualizer rendered.

Configuration

Here are the configuration settings for the visualizer:

/**
* --------------------------------------------------------------------------
* Security Visualizer
* --------------------------------------------------------------------------
* This is a debugging panel that when active, a developer can visualize security settings and more.
* You can use the `securityRule` to define what rule you want to use to secure the visualizer but make sure the `secured` flag is turned to true.
* You don't have to specify the `secureList` key, we will do that for you.
*/
visualizer : {
	"enabled"      : false,
	"secured"      : false,
	"securityRule" : {}
},

enabled

secured

We highly encourage you to ensure the visualizer is ONLY accessible if you have authenticated into your system. By using a secured=true then CBSecurity will incorporate a rule to secure the visualizer for ONLY authenticated users. If you want to be picky, use the securityRule setting.

securityRule

We also recommend that ONLY certain users have access to the visualizer. You can accomplish this by adding the keys to the security rule created for the visualizer. For example, I only want admins or users with the cbsecurity-visualizer permission to access it.

visualizer : {
	"enabled"      : true,
	"secured"      : true,
	"securityRule" : {
		"roles" : "admins",
		"permissions" : "cbsecurity-visualizer"
	}
}

Requirements

Please note that the security visualizer can ONLY visualize if you have firewall logs enabled. If no logs are enabled or configured, then the visualizer WILL NOT WORK. Here is a simple logs configuration in the firewall

firewall : {

    "logs" : {
        "enabled"    : true,
        "dsn"        : "myapp",
        "schema"     : "",
        "table"      : "cbsecurity_logs",
        "autoCreate" : true
    }
    
}

Explicit Authorizations

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

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

cbSecurity Model Retrieval

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

We have seen by now that rules can be defined in disk, databases, or created at runtime. These security rules all share a common anatomy and processing; let's explore it.

Rule Anatomy

A struct models each rule with keys in it internally in CBSecurity. So no matter where these rules come from, at the end of the day, they are registered as an array of structs internally.

{
	"id"            : created automatically as a UUID,
	// A list of white list events or Uri's
	"whiteList"     : "", 
	// A list of secured list events or Uri's
	"secureList"    : "", 
	// Match the event or a url
	"match"         : "event", 
	// Attach a list of roles to the rule
	"roles"         : "", 
	// Attach a list of permissions to the 
	"permissions"   : "", rule
	// If rule breaks, and you have a redirect it will redirect here
	"redirect"      : "", 
	// If rule breaks, and you have an event, it will override it
	"overrideEvent" : "", 
	// Force SSL,
	"useSSL"        : false, 
	// The action to use (redirect|override|block) when no redirect or overrideEvent is defined in the rule.
	"action"        : "", 
	// metadata we can add so mark rules that come from modules
	"module"        : "", 
	// Match all HTTP methods or particular ones as a list
	"httpMethods"   : "*",
	// The rule only matches if the IP list matches. It can be a list of IPs to match. 
	"allowedIPs"    : "*" 
}

The only required key is the secureList which is what you are trying to secure. The rest are optional.

Rule Elements