ryanb/cancan

= CanCan {}[http://badge.fury.io/rb/cancan] {}[http://travis-ci.org/ryanb/cancan] {}[https://codeclimate.com/github/ryanb/cancan]

Wiki[https://github.com/ryanb/cancan/wiki] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]

CanCan is an authorization library for Ruby on Rails which restricts what resources a given user is allowed to access. All permissions are defined in a single location (the +Ability+ class) and not duplicated across controllers, views, and database queries.

== Installation

In Rails 3, add this to your Gemfile and run the +bundle+ command.

gem “cancan”

In Rails 2, add this to your environment.rb file.

config.gem “cancan”

Alternatively, you can install it as a plugin.

rails plugin install git://github.com/ryanb/cancan.git

== Getting Started

CanCan expects a +current_user+ method to exist in the controller. First, set up some authentication (such as Authlogic[https://github.com/binarylogic/authlogic] or Devise[https://github.com/plataformatec/devise]). See {Changing Defaults}[https://github.com/ryanb/cancan/wiki/changing-defaults] if you need different behavior.

=== 1. Define Abilities

User permissions are defined in an +Ability+ class. CanCan 1.5 includes a Rails 3 generator for creating this class.

rails g cancan:ability

In Rails 2.3, just add a new class in app/models/ability.rb with the following contents:

class Ability include CanCan::Ability

def initialize(user)
end

end

See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details.

=== 2. Check Abilities & Authorization

The current user’s permissions can then be checked using the can? and cannot? methods in the view and controller.

See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information

The authorize! method in the controller will raise an exception if the user is not able to perform the given action.

def show @article = Article.find(params[:id]) authorize! :read, @article end

Setting this for every action can be tedious, therefore the +load_and_authorize_resource+ method is provided to automatically authorize all actions in a RESTful style resource controller. It will use a before filter to load the resource into an instance variable and authorize it for every action.

class ArticlesController < ApplicationController load_and_authorize_resource

def show
  # @article is already loaded and authorized
end

end

See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information.

=== 3. Handle Unauthorized Access

If the user authorization fails, a CanCan::AccessDenied exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.

class ApplicationController < ActionController::Base rescue_from CanCan::AccessDenied do |exception| redirect_to root_url, :alert => exception.message end end

See {Exception Handling}[https://github.com/ryanb/cancan/wiki/exception-handling] for more information.

=== 4. Lock It Down

If you want to ensure authorization happens on every action in your application, add +check_authorization+ to your ApplicationController.

class ApplicationController < ActionController::Base check_authorization end

This will raise an exception if authorization is not performed in an action. If you want to skip this add +skip_authorization_check+ to a controller subclass. See {Ensure Authorization}[https://github.com/ryanb/cancan/wiki/Ensure-Authorization] for more information.

== Wiki Docs

== Questions or Problems?

If you have any issues with CanCan which you cannot find the solution to in the documentation[https://github.com/ryanb/cancan/wiki], please add an {issue on GitHub}[https://github.com/ryanb/cancan/issues] or fork the project and send a pull request.

To get the specs running you should call +bundle+ and then +rake+. See the {spec/README}[https://github.com/ryanb/cancan/blob/master/spec/README.rdoc] for more information.

== Special Thanks

CanCan was inspired by declarative_authorization[https://github.com/stffn/declarative_authorization/] and aegis[https://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[https://github.com/ryanb/cancan/contributors]. See the CHANGELOG[https://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.