Roles and Permissions

There are three default role provided: admin,editor,user. You can easily add more via the web interface.

Controller Based Permissions

Any controller which calls super.config(restrictaccess=true) uses the central permissions system. The way this system works is by storing a dot notation path to the "controller/action": for example, if you have an admin folder, which contains a Users.cfc, which in it has an index action, this would be represented by admin.users.index internally. Any authenticated user which then has that string in their permissions scope is then allowed access.

Permissions "Cascade" (or inherit for a different term) too, so you could allow access:

• at the "highest" level, i.e, admin, which would then allow access to everything underneath it
• at the controller level e.g users, which would allow access to all methods in that controller
• or right down to the individual method in the controller, e.g index.

Named Permissions

In addition to the Controller based permissions, there are "Named" permissions which might be much more custom: for instance you might need a permission which dictates whether the User can use a certain feature, like canDoSomething; this can be useful is the permission checks you need to run are a bit more complex.

It's recommended to keep your named permissions in camelCase, and also make it a "positive" action: i.e, try and do canDoThis as opposed to canNotDoThis. Also, the named and controller permissions can interfere, so don't call a named permission admin as it might get confused with the global admin controller permission.

Role Permissions

For each role, you can assign permissions which anyone in that role will inherit. Typically you would have an admin who has a single top level permission of admin giving them access to everything underneath: but you might have an editor who is allowed to modify users, but isn't allowed to give them individual user permissions, hard delete or assume other user accounts. In that case you wouldn't give them the top level admin permission, but instead add permissions for each individual action in underneath admin.users, thus restricting their access to the more highly powered assume action for instance.

User Permissions

Permissions can also be added per user; so they could be in the user role, but could be escalated with certain permissions which they wouldn't usually have for maximum flexibility. User permissions are merged with role permissions in a user's session, and will override a role permission. Note that permission's can't be set to true or false, so you can't override a role permission with a user permission, only grant additional access.

Adding your own permissions

It's expected that you'd add your own permissions via the database migration system, since this app already uses that. Whilst it's an extra step in setting up your protected controllers, it's worth it!

Checking Controller Permissions in your code

To make a Controller adhere to the central controller permissions system:

controller extends="app.controllers.Controller" {
  function config(){
    super.config(restrictaccess=true);
  }
}

To check a permission quickly on an ad-hoc basis, use the hasPermissions() method:

if(hasPermission("admin.users.edit")){
  // Do something
}

Checking Named Permissions in your code

Named permissions can be checked in exactly the same way.

if(hasPermission("canDoSomething")){
  // Do stuff
}