Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
CanCan extension with role oriented permission management, rules caching and much more

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
ideas
lib
spec
wiki
.document
.gitignore
.rspec
Gemfile
LICENSE.txt
README.textile
Rakefile
VERSION
cantango.gemspec

README.textile

CanTango

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

  • extends CanCan and offers a more role oriented design
  • integrates with role and authentication systems in a non-intrusive manner
  • can cache ability rules between requests for increased performance
  • can store abilites 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 Oct 17, 2011

Version 0.9.0 has been released.

Thee user _can? and cannot? API methods have been updated to work correctly when current_[user_class] and such methods (fx as generated by Devise) return an account and not a user instance.
In this case CanTango will attempt to call the #user method on the account to get the user.
In many cases for more advanced scenarios, it makes more sense to treat the devise models as accounts and have the user models defined separately and linked to one or more accounts.
The accounts would then have the credentials for the user in that partiular context and the user only the user specific details.

Now the #current_[type]_account methods are generated for each registered account and by default aliases the current_[type] methods (fx as exposed by devise). You can override this if you need to, but in most instances CanTango will now sort it all out depending on what kind of instance these methods return!

CanTango now also supports Access Control method wrappers directly on the models. Here an example:

class Project
  include CanTango::Filter

  tango_filter :publish, :edit, :assign_to => [:assignee]

  def publish
    self.publish = true
  end

  def edit
    # do some editing
  end

  def assign_to assignee
    self.assignee = assignee
  end
end

From your controller, you would then use these wrappers like this:

class ProjectsController < ApplicationController

  def edit
    project.edit_by current_user
  end

  def assign_to
    assignee_user = User.find params[assignee_id]
    project.assign_to_by current_user, assignee_user
  end
end

These AC wrapper methods would only call the wrapped methods if the user (first argument) is allowed to perform said operation!

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!

Abilities via Permits and Permissions

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

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

Debugging Abilities and Permits

See Debugging permits

Design overview

The default CanTango Ability pattern is simple.

1. Return cached ability rules for candidate if available
2. Generate rules for candidate
3. Cache rules for candidate

A 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

Copyright

Copyright © 2010 Kristian Mandrup. See LICENSE for details.

Something went wrong with that request. Please try again.