Configuration

Security Settings

By Default, the security module will register itself for you using the module configuration settings you define in theconfig/ColdBox.cfc. Below you can find all the settings with their default value and description.
config/Coldbox.cfc
1
// Module Settings
2
moduleSettings = {
3
// CB Security
4
cbSecurity : {
5
// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
6
"invalidAuthenticationEvent" : "",
7
// Default Authentication Action: override or redirect when a user has not logged in
8
"defaultAuthenticationAction" : "redirect",
9
// The global invalid authorization event or URI or URL to go if an invalid authorization occurs
10
"invalidAuthorizationEvent" : "",
11
// Default Authorization Action: override or redirect when a user does not have enough permissions to access something
12
"defaultAuthorizationAction" : "redirect",
13
// You can define your security rules here or externally via a source
14
// specify an array for inline, or a string (db|json|xml|model) for externally
15
"rules" : [],
16
// The validator is an object that will validate rules and annotations and provide feedback on either authentication or authorization issues.
17
"validator" : "[email protected]",
18
// The WireBox ID of the authentication service to use in cbSecurity which must adhere to the cbsecurity.interfaces.IAuthService interface.
19
"authenticationService" : "[email protected]",
20
// WireBox ID of the user service to use
21
"userService" : "",
22
// The name of the variable to use to store an authenticated user in prc scope if using a validator that supports it.
23
"prcUserVariable" : "oCurrentUser",
24
// If source is model, the wirebox Id to use for retrieving the rules
25
"rulesModel" : "",
26
// If source is model, then the name of the method to get the rules, we default to `getSecurityRules`
27
"rulesModelMethod" : "getSecurityRules",
28
// If source is db then the datasource name to use
29
"rulesDSN" : "",
30
// If source is db then the table to get the rules from
31
"rulesTable" : "",
32
// If source is db then the ordering of the select
33
"rulesOrderBy" : "",
34
// If source is db then you can have your custom select SQL
35
"rulesSql" : "",
36
// Use regular expression matching on the rule match types
37
"useRegex" : true,
38
// Force SSL for all relocations
39
"useSSL" : false,
40
// Auto load the global security firewall
41
"autoLoadFirewall" : true,
42
// Activate handler/action based annotation security
43
"handlerAnnotationSecurity" : true,
44
// Activate security rule visualizer, defaults to false by default
45
"enableSecurityVisualizer" : false,
46
// JWT Settings
47
"jwt" : {
48
// The issuer authority for the tokens, placed in the `iss` claim
49
"issuer" : "",
50
// The jwt secret encoding key to use
51
"secretKey" : getSystemSetting( "JWT_SECRET", "" ),
52
// by default it uses the authorization bearer header, but you can also pass a custom one as well or as an rc variable.
53
"customAuthHeader" : "x-auth-token",
54
// The expiration in minutes for the jwt tokens
55
"expiration" : 60,
56
// If true, enables refresh tokens, longer lived tokens (not implemented yet)
57
"enableRefreshTokens" : false,
58
// The default expiration for refresh tokens, defaults to 30 days
59
"refreshExpiration" : 43200,
60
// encryption algorithm to use, valid algorithms are: HS256, HS384, and HS512
61
"algorithm" : "HS512",
62
// Which claims neds to be present on the jwt token or `TokenInvalidException` upon verification and decoding
63
"requiredClaims" : [] ,
64
// The token storage settings
65
"tokenStorage" : {
66
// enable or not, default is true
67
"enabled" : true,
68
// A cache key prefix to use when storing the tokens
69
"keyPrefix" : "cbjwt_",
70
// The driver to use: db, cachebox or a WireBox ID
71
"driver" : "cachebox",
72
// Driver specific properties
73
"properties" : {
74
"cacheName" : "default"
75
}
76
}
77
}
78
}
79
};
Copied!

InvalidAuthentication-/ InvalidAuthorization events and default actions

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

Validator

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

Authentication Services

cbsecurity ships with the cbauth module that can provide you with a nice interface for authentication services. If you use the default authenticationService [email protected], you have to define the UserServiceClass in the cbauth module. However, you can plug in any WireBox ID and select your own authentication services.
If you are using cbauth as your authenticationService (the default), you also need to configure cbauth.

User Services

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

Automatic Firewall

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

Annotation Security

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

Security Visualizer

ColdBox security comes with a nice graphical visualizer for all the registered security rules and settings in your global firewall. You can enable it by using the enableSecurityVisualizer setting.
1
enableSecurityVisualizer : true
Copied!
You can then visit the /cbsecurity URL and you will be presented with this magical tool:
Important The visualizer is disabled by default and if it detects an environment of production, it will disable itself.

Module Settings

Each module can override some settings for cbsecurity according to its needs. You will create a cbsecurity struct within the module's settings struct in the ModuleConfig.cfc
module/ModuleConfig.cfc
1
settings = {
2
// CB Security Module Settings
3
cbsecurity : {
4
// Module Relocation when an invalid access is detected, instead of each rule declaring one.
5
"invalidAuthenticationEvent" : "api:Home.onInvalidAuth",
6
// Default Auhtentication Action: override or redirect when a user has not logged in
7
"defaultAuthenticationAction" : "override",
8
// Module override event when an invalid access is detected, instead of each rule declaring one.
9
"invalidAuthorizationEvent" : "api:Home.onInvalidAuthorization",
10
// Default invalid action: override or redirect when an invalid access is detected, default is to redirect
11
"defaultAuthorizationAction" : "override",
12
// The validator to use for this module
13
"validator" : "[email protected]",
14
// You can define your security rules here or externally via a source
15
"rules" : [ { "secureList" : "api:Secure\.*" } ]
16
}
17
}
Copied!
The settings you see above are the only ones that module's support as of now.

Custom Firewalls

You can also register multiple instances of the cbsecurity module using different configurations by just adding them to your app's config or even your module's configuration. This will register a NEW firewall apart from the global security firewall registered using the global settings as defined above.
config/Coldbox.cfc
1
interceptors = [
2
3
{
4
class="cbsecurity.interceptors.Security",
5
name="FirewallName",
6
properties={
7
// All Settings from above
8
}
9
10
]
Copied!