Need help with cancan?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

6.3K Stars 813 Forks MIT License 419 Commits 245 Opened issues


Authorization Gem for Ruby on Rails.

Services available


Need anything else?

Contributors list

= CanCan {Gem Version}[] {}[] {}[]

Wiki[] | RDocs[] | Screencast[]

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://

== Getting Started

CanCan expects a +current_user+ method to exist in the controller. First, set up some authentication (such as Authlogic[] or Devise[]). See {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

with the following contents:

class Ability include CanCan::Ability

def initialize(user)


See {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.

<% if can? :update, @article %> <%= linkto "Edit", editarticle_path(@article) %> <% end %>

See {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 +loadandauthorize_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 loadandauthorize_resource

def show
  # @article is already loaded and authorized


See {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 rescuefrom CanCan::AccessDenied do |exception| redirectto root_url, :alert => exception.message end end

See {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 +skipauthorizationcheck+ to a controller subclass. See {Ensure Authorization}[] for more information.

== Wiki Docs

  • {Upgrading to 1.6}[]
  • {Defining Abilities}[]
  • {Checking Abilities}[]
  • {Authorizing Controller Actions}[]
  • {Exception Handling}[]
  • {Changing Defaults}[]
  • {See more}[]

== Questions or Problems?

If you have any issues with CanCan which you cannot find the solution to in the documentation[], please add an {issue on GitHub}[] 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}[] for more information.

== Special Thanks

CanCan was inspired by declarativeauthorization[] and aegis[]. Also many thanks to the CanCan contributors[]. See the CHANGELOG[] for the full list.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.