CanTango

IMPORTANT

CanTango in its current form is no longer being maintained.
The current version is somewhat unstable and NOT production ready.

If you are interested in the general ideas and concepts behind this project and would like to use it or see the ideas
live on, you are encouraged to look at the attempt of divinding this project into smaller maintainable gems:

These gems all follow the cantango-xxxx convention.

Alternatively, you can look at the following Node.js project and perhaps port it to Ruby and whatever prog. environment
you are using. It sports a much better/simpler design (learning from the faults in the cantango design).

https://github.com/kristianmandrup/authorize-mw/

Good luck!

Intro

CanTango is an advanced Access Control (permissions) system for Rails 3. It:

• extends CanCan and offers a more granular Object Oriented design
• integrates with role and authentication systems in a non-intrusive manner
• can cache ability rules between requests for increased performance
• allows for context specific Permits with rules
• supports multiple Devise users/accounts
• can store static ability rules in a permission store for easy administration
• manage the permission store from a web UI using the cantango_editor, a mountable Rails engine

A rewrite of Cantango can be found at CanTango permits

The Cantango rewrite currently lacks caching functionality and the permit_store is also incomplete.

The Cantango rewrite consists of a cantango-core and a set of individual gems with minimal inter-dependencies. Each of these gems have been designed in a test driven fashion with almost complete spec coverage so they should be much easier to develop in the future. The old Cantango got too bloated and big and became too hard to maintain in the end.

If you like this project, please give a hand or encouragement for me to finalize the new Cantango.

Will CanTango meet my Access Control requirements?

• CanCan vs CanTango
• CanTango overview

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 Nov 24, 2011

Version 0.9.4.7 has been released.

• Now enables configuration of role and role group systems directly:

Defaults:

• Role system – simple_roles
• Role group system – troles

You can override the defaults like this:

CanTango.config do |c|
  c.roles.role_system = :troles
end

Then CanTango should auto-configure to use the correct list methods of that system. You can even add your own role system with custom mappings. Here I tell CanTango that I’m using a system I call MyRoles and that the method added to role candidates (fx User) to return the list of roles, will be #list_of_roles and the method to check if he is in (or has) a specific role will be is_in_role?. Same goes for role groups, using role_groups.add_role_group_system.

CanTango.config do |c|
  c.roles.add_role_system :my_roles => {:list => :list_of_roles, :has => :is_in_role?}
end

The wiki has been rewritten and updated to reflect all latest design changes and feature additions.

I am now in the process of a major refactoring effort in the major-refactor branch.
I’ve split up cantango into separate gems which will be developed independently in the future (towards a 1.0 release), notably one gem for each engine. I might rename the “engine” concept into “component” so that developers don’t confuse it with Rails engines ;)

• cantango-cache
• permits
• permit_store

I might also extract the permission engine (currently known as user_ac). Lot’s of changes coming doewn the pipeline. Please help make CanTango much better and more stable! Thanks!

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

• Simple scenario
• Complex scenario

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 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!

Abilities via Permits and Permissions

Abilities are Access Control rules. With CanTango, the AC rules can be defined in both:

• Permissions (fx a yaml file)
• Permits (special classes)

Note: For the simplest cases, you can define a #permit_rules instance method directly in CanTango::Ability

Abilities can be defined for the following conceptual entities:

• User models
• User Account models
• Roles
• Role groups
• Users

You can even create your own Permit types to suit your own needs! This feature will be further improved in the upcoming 1.0 release.

Design overview

The default CanTango Ability pattern is simple.

1. Return cached ability rules for candidate if available (and cache is on)
2. Generate rules for candidate
3. Cache rules for candidate (if cache is on)

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:

• Permit engine
• Permission engine

You can however freely plugin or unplug engines as you wish as described in 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
• Stanislaw Pankevich

Copyright

Copyright © 2010 Kristian Mandrup. See LICENSE for details.