CanTango
CanTango is an advanced Access Control (permissions) system for Rails 3. It:
- extends CanCan and offers a role oriented design
- integrates with role and authentication systems in a non-intrusive manner
- can cache rules between requests for increased performance
- can store rules in a permission store, including a YAML file, for easy administration
- works well with multiple user accounts and sub applications
- supports multiple Devise users
Will CanTango meet my Access Control (permission) requirements?
Installation
Ruby versions
CanTango has been tested to work with Ruby 1.9+ and currently doesn’t support Ruby 1.8.7 If you require ruby 1.8.7 support, please help patch it and make a pull request ;)
Install in current environment (or gemset)
gem install cantango
Install in application
Insert into Gemfile
gem 'cantango'
Run bundler in a terminal/console from the folder of your Gemfile (root folder of app)
$ bundle
Update Sept 1, 2011
Version 0.8.5 has been released.
CanTango now supports sugar-high 0.6’ where sweetloader’ has been extracted into its own gem.
- The Cache has been refactored
- Engines are now run in correct order (and only if active)
- The Cache Kompiler (for dynamic rules caching) and Moneta cache are now optional (via adapters)
- Permits are found and loaded via pre-registratio via the
#inherited
method for the base permits. You can also use the tango_permit macro. - Better visibility of the
Ability
flow, to allow one to see which rules are triggered by which permits (likely via a special :debug config mode, since it would affect performance).
The wiki will soon be updated to reflect these improvements and changes.
Quickstart
See the Quickstart guide in the wiki.
For devise integration, see Quickstart with Devise
The following scenarios demonstrate some of the problems CanTango can help solve in an elegant way
Generators
Cantango comes with a set of Generators to get your app dancing… Simply start with:
- cantango:install
To use the Permit generators please see the Generators wiki page ;)
Rails 3 configuration
The CanTango Configuration consists of a nice DSL that let’s you configure most of the things we imagine you would want to customize. Feel free to suggest more configuration options!
Access Control via Permits and Permissions
AC rules can be defined in both:
- Permissions (fx a yaml file)
- Permits (special classes)
AC rules can be defined for the following conceptual entities:
- User models
- User Account models
- Roles
- Role groups
- Users
Design overview
The default CanTango ability pattern is simple.
1. Return cached rules for ability candidate if available 2. Generate rules for candidate 3. Cache rules for candidate
An ability candidate is typically either a user or an account instance.
Caching can be enabled or disabled. To generate the rules, one or more engines are executed.
CanTango comes with the following engines:
You can however freely plugin or unplug engines as you wish as described in Pluggable engines
Dependencies, Adapters and Loading
CanTango had been designed to be minimally intrusive and not require too many external dependencies.
If you want to enable Moneta for caching or storage, you must execute an adapter macro: CanTango.adapter :moneta
This will setup lazy-loading of Moneta cache and Moneta store respectively.
If you want to enable compilation of dynamic rules (using blocks) you must use the :compiler
adapter
If you use any of these adapters, you must manually include the following in your Rails app Gemfile.
gem 'dkastner-moneta'
for moneta adapter and gem 'sourcify'
for the compiler adapter.
CanTango uses autoload_modules
from the sweetloader’ gem.
This ensures that all such modules are lazy-loaded. Thus if you configure CanTango to exclude an engine, the code for that engine will never be loaded, minimizing the load time and memory print.
You need help?
Please post ideas, questions etc. in the cantango group on Google.
Bugs, issues or feature request/ideas?
If you encounter bugs, raise an issue or:
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don’t break it in a future version unintentionally.
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- Send me a pull request. Bonus points for topic branches.
Contributors
Kristian Mandrup - Main architect - Designer of structure - Feature ideas - Initiator of project - Devise app integration specs
Stanislaw Pankevich - Main contributor of permissions engine - Caching of Procs for caching engine - Lots of bug fixes and specs - Tireless “worker” ;)
Copyright
Copyright © 2010 Kristian Mandrup. See LICENSE for details.