Installation
Leverage CommandBox to install into your ColdBox app:
# Latest version
install cbsecurity
# Bleeding Edge
install cbsecurity@beSystem Requirements
Lucee 5.x+
ColdFusion 2016+
Module Settings
The module can be configured by adding a cbsecurity key in the moduleSettings structure within the config/Coldbox.cfc
config/Coldbox.cfc
// Module Settings
moduleSettings = {
// CB Security
cbSecurity : {
// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
"invalidAuthenticationEvent" : "",
// Default Authentication Action: override or redirect when a user has not logged in
"defaultAuthenticationAction" : "redirect",
// The global invalid authorization event or URI or URL to go if an invalid authorization occurs
"invalidAuthorizationEvent" : "",
// Default Authorization Action: override or redirect when a user does not have enough permissions to access something
"defaultAuthorizationAction" : "redirect",
// You can define your security rules here or externally via a source
"rules" : [],
// The validator is an object that will validate rules and annotations and provide feedback on either authentication or authorization issues.
"validator" : "CBAuthValidator@cbsecurity",
// The WireBox ID of the authentication service to use in cbSecurity which must adhere to the cbsecurity.interfaces.IAuthService interface.
"authenticationService" : "authenticationService@cbauth",
// WireBox ID of the user service to use
"userService" : "",
// The name of the variable to use to store an authenticated user in prc scope if using a validator that supports it.
"prcUserVariable" : "oCurrentUser",
// If source is model, the wirebox Id to use for retrieving the rules
"rulesModel" : "",
// If source is model, then the name of the method to get the rules, we default to `getSecurityRules`
"rulesModelMethod" : "getSecurityRules",
// If source is db then the datasource name to use
"rulesDSN" : "",
// If source is db then the table to get the rules from
"rulesTable" : "",
// If source is db then the ordering of the select
"rulesOrderBy" : "",
// If source is db then you can have your custom select SQL
"rulesSql" : "",
// Use regular expression matching on the rule match types
"useRegex" : true,
// Force SSL for all relocations
"useSSL" : false,
// Auto load the global security firewall
"autoLoadFirewall" : true,
// Activate handler/action based annotation security
"handlerAnnotationSecurity" : true,
// Activate security rule visualizer, defaults to false by default
"enableSecurityVisualizer" : false,
// JWT Settings
"jwt" : {
// The issuer authority for the tokens, placed in the `iss` claim
"issuer" : "",
// The jwt secret encoding key to use. 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 or as an rc variable.
"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" }
}
}
}
};If you are using cbauth as your authenticationService (the default), you also need to configure cbauth.
Last updated