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.
In Rails 3, add this to your Gemfile and run the
In Rails 2, add this to your environment.rb file.
Alternatively, you can install it as a plugin.
rails plugin install git://github.com/ryanb/cancan.git
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 include :: def initialize(user) end end
See Defining Abilities for details.
2. Check Abilities & Authorization
The current user's permissions can then be checked using the
cannot? methods in the view and
<% if can? :update, @article %> <%= link_to "Edit", edit_article_path(@article) %> <% end %>
See Checking Abilities for more information
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]) :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 def show # @article is already loaded and authorized end end
See Authorizing Controller Actions for more information.
3. Handle Unauthorized Access
If the user authorization fails, a
exception will be raised. You can catch this and modify its behavior in the
class ApplicationController < ActionController::Base rescue_from :: do |exception| redirect_to root_url, :alert => exception. end end
See Exception Handling for more information.
4. Lock It Down
If you want to ensure authorization happens on every action in your
check_authorization to your
class ApplicationController < ActionController::Base end
This will raise an exception if authorization is not performed in an
action. If you want to skip this add
to a controller subclass. See Ensure
Authorization for more information.
Questions or Problems?
To get the specs running you should call
bundle and then
rake. See the spec/README
for more information.