GitBook: [master] 17 pages modified

README.md

@@ -1,3 +1,88 @@
-# My Awesome Book
+# Introduction
+
+## WELCOME TO THE COLDBOX SECURITY MODULE
+
+This module will provide your application with a security rule engine.
+
+### LICENSE Apache License, Version 2.0.
+
+### IMPORTANT LINKS
+
+* [http://www.coldbox.org/forgebox/view/cbsecurity](http://www.coldbox.org/forgebox/view/cbsecurity)
+
+### SYSTEM REQUIREMENTS
+
+* Lucee 4.5+
+* ColdFusion 9+
+
+## INSTRUCTIONS
+
+Just drop into your **modules** folder or use CommandBox to install
+
+`box install cbsecurity`
+
+You will then need to configure the interceptor via the `cbsecurity` settings in your main `ColdBox.cfc` or you can also declare the interceptor manually by leveraging the class: `cbsecurity.interceptors.Security`. If you define the `cbsecurity` settings, then the module will load the interceptor automatically for you with those settings.
+
+You can find all the documentation here: [https://github.com/ColdBox/cbox-security/wiki](https://github.com/ColdBox/cbox-security/wiki)
+
+### Security Rules
+
+Security rules can come from xml, json, query, memory or custom locations. You will find some examples in this module's `config` folder.
+
+### Settings
+
+Below are the security settings you can use for this module. Remember you must create the `cbsecurity` struct in your `ColdBox.cfc`:
+
+```javascript
+cbsecurity = {
+    // By default all rules are evulated as regular expressions
+    useRegex = true,
+    // Verify queries that they have all required columns, by default it is relaxed
+    queryChecks = false,
+    // Will verify rules of execute before ANY event. Be careful, can be intensive, usually the preProcess is enough.
+    preEventSecurity = false,
+    // The class path of a CFC that will validate rules, optional
+    validator = "class.path",
+    // The WireBox ID of the object to validate rules, optional
+    validatorModel = "wireboxID",
+    // The bean ID of the object in the ioc module that will validate the rules, optional
+    validatorIOC = "beanID.from.ioc.module",
+    // Where to look for security rules
+    rulesSource = "xml,json,db,model,ioc,ocm",
+    // The location of a rules file, aplies to XML and JSON only
+    rulesFile = "path.to.file",
+    // Rules DB Properties
+    rulesDSN = "datasource",
+    rulesTable = "table",
+    rulesSQL = "select * from rulesTable",
+    rulesOrderBy = "",
+    // Model Rule Properties
+    rulesModel = "wirebox.id",
+    rulesModelMethod = "method",
+    rulesModelArgs = "comma-delimmited list of args",
+    // IOC properties
+    rulesBean = "bean.id",
+    rulesBeanMethod = "method",
+    rulesBeanArgs = "comma-delimmited list of args",
+    // Cache key that has rules in the 'default' provider
+    rulesOCMKey = "key.from.default.provider"
+}
+```
+
+### Manual Interceptor Declaration
+
+Here is a sample declaration you can use in your `ColdBox.cfc`:
+
+```javascript
+// Security Interceptor declaration.
+interceptors = [
+    { class="cbsecurity.interceptors.Security",
+      name="CBSecurity",
+      properties={
+        // please add the properties you want here to configure the security interceptor
+        rulesFile = "/cbsecurity/config/security.json.cfm",
+        rulesSource = "json"
+     } }
+];
+```
 
-This file file serves as your book's preface, a great place to describe your book's content and ideas.

SUMMARY.md

@@ -1,3 +1,18 @@
-# Summary
+# Table of contents
+
+* [Introduction](README.md)
+* [Overview](untitled.md)
+* [How It Works](home.md)
+* [Declaring the Interceptor](first-chapter/README.md)
+  * [XML Properties](first-chapter/xml-properties.md)
+  * [JSON Properties](first-chapter/json-properties.md)
+  * [DB Properties](first-chapter/untitled.md)
+  * [IOC Properties](first-chapter/ioc-properties.md)
+  * [OCM Properties](first-chapter/ocm-properties.md)
+* [Security Rules](untitled-1/README.md)
+  * [Sample JSON Rules](untitled-1/sample-json-rules.md)
+  * [Sample XML Rules](untitled-1/sample-xml-rules.md)
+* [\_securedURL key](_securedurl-key.md)
+* [Default Security](default-security.md)
+* [Custom Security Validator Object](custom-security-validator-object.md)
 
-* [First Chapter](chapter1.md)

_securedurl-key.md

@@ -0,0 +1,25 @@
+# \_securedURL key
+
+When the security module is about to relocate _redirect_ element, it will save the incoming URL that was requested in a flash RAM variable called: `_securedURL`. This key will be persisted in the flash memory of the framework and when the user get's relocated to the `redirect` element, this key will exist in the request collection. You can then use this to store where they came from and do proper redirections. So always remember to use this key if you want to provide a seamless login experience to your users. You can easily place it in the login form:
+
+```markup
+#html.startForm(action=prc.xehDoLogin,name="loginForm",novalidate="novalidate")#
+    <---< Secured URL --->
+    #html.hiddenField(name="_securedURL",value=event.getValue('_securedURL',''))#
+
+    #html.textfield(name="username",label="Username: ",size="40",required="required",class="textfield",value=prc.rememberMe)#
+    #html.passwordField(name="password",label="Password: ",size="40",required="required",class="textfield")#
+    
+    <div id="loginButtonbar">
+    #html.checkBox(name="rememberMe",value=true,checked=(len(prc.rememberMe)))# 
+    #html.label(field="rememberMe",content="Remember Me  ",class="inline")#
+    #html.submitButton(value="  Log In  ",class="buttonred")#
+    </div>
+    
+    <br/>
+    <img src="#prc.cbRoot#/includes/images/lock.png" alt="lostPassword" />
+    <a href="#event.buildLink(prc.xehLostPassword)#">Lost your password?</a> 
+    
+#html.endForm()#
+```
+

custom-security-validator-object.md

@@ -0,0 +1,80 @@
+# Custom Security Validator Object
+
+A security validator object is a simple CFC that implements the following function:
+
+```text
+boolean userValidator( rule:struct, controller:coldbox.system.web.Controller )
+```
+
+This function must return a `boolean` variable and it must validate a user according to the rule that just ran by testing the fields that get sent in as a rule. Where this method exists is up to you. It will also receive a reference to the current ColdBox controller. You can use the controller to call other plugins, persist keys, or anything you like \(please see the controller API\). The important note here is that the rule structure contains all the elements/columns you defined in your xml or query. Below is a real life example:
+
+```text
+<!---  User Validator for security --->
+<cffunction name="userValidator" access="public" returntype="boolean" output="false" hint="Verifies that the user is in any permission">
+    <!---************************************************************** --->
+    <cfargument name="rule"     required="true" type="struct"   hint="The rule to verify">
+    <cfargument name="controller" type="any" required="true" hint="The coldbox controller" />
+    <!---************************************************************** --->
+    <!---  Local call to get the user object from the session --->
+    <cfset var oUser = getUserSession()>
+    <!---  The results boolean variable I will return --->
+    <cfset var results = false>
+    <!---  The permission I am checkin --->
+    <cfset var thisPermission = "">
+            
+    <!---  Authorized Check, if true, then see if user is valid. This column is an additional column in my query --->
+    <cfif arguments.rule['authorize_check'] and oUser.getisAuthorized()>
+        <!---  I first check if the user is authorized or not if set in the db rules --->
+        <cfset results = true>
+    </cfif>
+    
+    <!---  Loop Over Permissions to see if my user is in any of them. --->
+    <cfloop list="#arguments.rule['permissions']#" index="thisPermission">
+    
+        <!---  My user object has a method called check permission that I call with a permission to validate --->
+        <cfif oUser.checkPermission( thisPermission ) >
+            <!---  This permission existed, I only need one to match as per my business logic, so let's return and move on --->
+            <cfset results = true>
+            <cfbreak>
+        </cfif>
+    </cfloop>
+    
+    <!---  I now return whether the user can view the incoming rule or not --->
+    <cfreturn results>
+</cffunction>
+```
+
+Or, in `cfscript`:
+
+```javascript
+/** 
+ * User Validator for security
+ * 
+ * @hint Verifies that the user is in any permission
+ * @rule.hint The rule to verify
+ * @controller.hint The ColdBox controller
+ */
+public boolean function userValidator( required struct rule, required any controller ) {
+    // Local call to get the user object from the session
+    var user = getUserSession();
+
+    // Authorized Check, if true, then see if user is valid. This column is an additional column in my query
+    if ( arguments.rule['authorize_check'] and user.getIsAuthorized() ) {
+        return true;
+    }
+
+    // Loop Over Permissions to see if my user is in any of them.
+    var permissionsArray = ListToArray(arguments.rule['permissions']);
+    for (var permission in permissionsArray) {
+        // My user object has a method called check permission that I call with a permission to validate
+        if ( user.checkPermission( permission ) ) {
+            // This permission existed, I only need one to match as per my business logic, so let's return and move on
+            return true;
+        }
+    }
+
+    // If we got here, the user does not have permission
+    return false;
+}
+```
+

default-security.md

@@ -0,0 +1,25 @@
+# Default Security
+
+This module will try to use ColdFusion's `cflogin + cfloginuser`authentication by default. However, if you are using your own authentication mechanisms you can still use this module by implementing a Security Validator Object \(See next section\). Below we can see a sample on how to use the `cflogin` tag:
+
+Example:
+
+```text
+<cflogin>
+    
+    Your login logic here
+    
+    <---  Log in the user with appropriate credentials --->
+    <cfloginuser name="name" password="password" roles="ROLES HERE">
+</cflogin>
+
+<---  Some Real sample --->
+<cflogin>
+    <cfif getUserService().authenticate(rc.username,rc.password)>
+        <cfloginuser name="#rc.username#" password="#rc.password#" roles="#getUserService().getRoles(rc.username)#" />
+    </cfif>
+</cflogin>
+```
+
+For more information about `cflogin, cfloginuser and cflogout`, please visit the docs [http://cfdocs.org/security-functions](http://cfdocs.org/security-functions)
+

first-chapter/README.md

@@ -0,0 +1,32 @@
+# Declaring the Interceptor
+
+In order to enable ColdBox security you must register the Security interceptor in your parent or other module configuration's `interceptors` section:
+
+```javascript
+interceptors = [
+    { 
+        class       = "cbSecurity.interceptors.Security", 
+        name        = "ApplicationSecurity", 
+        properties  = {
+            // Security properties go here.
+        }
+    }
+];
+```
+
+{% hint style="info" %}
+**IMPORTANT** If you are using SES or URL mappings in your application, make sure that you declare the security interceptor after the SES interceptor. Interceptors require order, so security needs for the URL to be translated first.
+{% endhint %}
+
+### Global Properties
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `useRegex` | boolean | false | true | By default all secure and white lists are matched using regular expressions. You can disable it if you like and use plain old string matching. |
+| `queryChecks` | boolean | false | false | Flag that tells the interceptor to validate the columns in the security rules. This makes sure all columns have the same columns. By default it is in relaxed mode so all columns are used. |
+| `preEventSecurity` | boolean | false | false | This turns on the `preEvent`execution point that will make sure that before any event is fired internally, that its verified against the security rules. Only use this if you really want to secure all internal events, else this can hinder performance. |
+| `ruleSource` | string | true | --- | Where to look for the rules as described above, this value has to be a choice from the following list `xml,json,db,model,ioc or ocm`. |
+| `validator` | string | false | --- | The class path of the validator object to use. The interceptor will create the object for you and cache it internally. If the object has an `init()` method, the interceptor will call it for you. |
+| `validatorModel` | string | false | --- | The model name of the security validator to use for custom validations. The interceptor will call `getModel()` with the name of this property to be retrieved via [WireBox](http://wirebox.ortusbooks.com/) |
+| `validatorIOC` | string | false | --- | The bean name of the security validator to use for custom validations. The interceptor will ask the IoC module for the bean according to this property |
+

first-chapter/ioc-properties.md

@@ -0,0 +1,23 @@
+---
+description: Inversion of Control Properties
+---
+
+# IOC Properties
+
+The following are properties used when the source of the rules is ioc or coming from an IoC module
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `rulesBean` | string | true if rulesSource = ioc | --- | The bean name to ask the IoC module for that has the rules |
+| `rulesBeanMethod` | string | true if rulesSource = ioc | --- | The method in the bean to call that will return a query of rules |
+| `rulesBeanArgs` | string | false | --- | A comma-delimited list of arguments to send into the method. This is an optional argument and if not set, the method will be called with no arguments |
+
+```javascript
+interceptors = [
+    {class="cbsecurity.interceptors.Security", name="ApplicationSecurity", properties={
+        useRegex = true, rulesSource = "ioc", validatorModel = "SecurityService",
+        rulesBean = "SecurityService", rulesBeanMethod = "getRules", rulesBeanArgs = "sorting=true"
+    }}
+];
+```
+

first-chapter/json-properties.md

@@ -0,0 +1,20 @@
+# JSON Properties
+
+The following are properties used when the source of the rules is json
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `rulesfile` | string | true if rulesSource = JSON | --- | The location of the security rules json file |
+
+```javascript
+interceptors = [
+    {class="cbsecurity.interceptors.Security", name="ApplicationSecurity", properties={
+        useRegex = true, rulesSource = "json", validatorModel = "SecurityService",
+        rulesFile = "config/security.json.cfm"
+    }}
+];
+```
+
+
+
+

first-chapter/ocm-properties.md

@@ -0,0 +1,21 @@
+---
+description: ColdBox OCM (Object Cache Manager)
+---
+
+# OCM Properties
+
+The following are properties used when the source of the rules is `ocm` or coming from the CacheBox
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `rulesOCMKey` | string | true | --- | The cache key to use to retrieve the rules from the ColdBox default cache provider |
+
+```javascript
+interceptors = [
+    {class="cbsecurity.interceptors.Security", name="ApplicationSecurity", properties={
+        useRegex = true, rulesSource = "ocm", validatorModel = "SecurityService",
+        rulesOCMKey = "qSecurityRules"
+    }}
+];
+```
+

first-chapter/untitled.md

@@ -0,0 +1,20 @@
+# DB Properties
+
+The following are properties used when the source of the rules is db or coming from the database.
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `rulesDSN` | string | true if rulesSource = db | --- | The dsn to use if the rules are coming from a database |
+| `rulesTable` | string | true if rulesSource = db | --- | The table where the rules are |
+| `rulesSQL` | string | false | `select* from rulesTable` | The custom SQL statement to use to retrieve the rules according to the rulesTable property. If not set, the default of select\* from rulesTable will be used. |
+| `rulesOrderBy` | string | false | --- | The column to order the rules by. If not chosen, the interceptor will not order the query, just select it. |
+
+```javascript
+interceptors = [
+    {class="cbsecurity.interceptors.Security", name="ApplicationSecurity", properties={
+        useRegex = true, rulesSource = "db", validatorModel = "SecurityService",
+        rulesDSN = "myApp", rulesTable = "securityRules", rulesOrderBy = "order asc"
+    }}
+];
+```
+

first-chapter/xml-properties.md

@@ -0,0 +1,19 @@
+# XML Properties
+
+The following are properties used when the source of the rules is xml
+
+| Property | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `rulesfile` | string | true if rulesSource = xml | --- | The location of the security rules xml file |
+
+```javascript
+interceptors = [
+    {class="cbsecurity.interceptors.Security", name="ApplicationSecurity", properties={
+        useRegex = true, rulesSource = "xml", validatorModel = "SecurityService",
+        rulesFile = "config/security.xml.cfm"
+    }}
+];
+```
+
+
+