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

About the developer

4.9K Stars 504 Forks MIT License 1.2K Commits 34 Opened issues


The authorization Gem for Ruby on Rails.

Services available


Need anything else?

Contributors list


Gem Version Github Actions badge Code Climate Badge

Wiki | RDocs | Screencast 1 | Screencast 2

CanCanCan is an authorization library for Ruby and Ruby on Rails which restricts what resources a given user is allowed to access.

All permissions can be defined in one or multiple ability files and not duplicated across controllers, views, and database queries, keeping your permissions logic in one place for easy maintenance and testing.

It consists of two main parts: 1. Authorizations library that allows you to define the rules to access different objects, and provides helpers to check for those permissions.

  1. Rails helpers to simplify the code in Rails Controllers by performing the loading and checking of permissions of models automatically and reduce duplicated code.

Sponsored by

Renuo AG

Modern Treasury

Bullet Train


Do you want to sponsor CanCanCan and show your logo here? Check our Sponsors Page.


Add this to your Gemfile:

gem 'cancancan'

and run the

bundle install

Define Abilities

User permissions are defined in an

rails g cancan:ability

Here follows an example of rules defined to read a Post model. ```ruby class Ability include CanCan::Ability

def initialize(user) can :read, Post, public: true

if user.present?  # additional permissions for logged in users (they can read their own posts)
  can :read, Post, user_id:

if user.admin? # additional permissions for administrators can :read, Post end end

end end ```

See Defining Abilities for details on how to define your rules.

Check Abilities

The current user's permissions can then be checked using the

methods in views and controllers.

See Checking Abilities for more information on how you can use these helpers.

Fetching records

One of the key features of CanCanCan, compared to other authorization libraries, is the possibility to retrieve all the objects that the user is authorized to access. The following:


will use your rules to ensure that the user retrieves only a list of posts that can be read. See Fetching records for details.

Controller helpers

CanCanCan expects a

method to exist in the controller. First, set up some authentication (such as Devise or Authlogic). See Changing Defaults if you need a different behavior.

3.1 Authorizations


method in the controller will raise an exception if the user is not able to perform the given action.
def show
  @post = Post.find(params[:id])
  authorize! :read, @post

3.2 Loaders

Setting this for every action can be tedious, therefore the

method is provided to automatically authorize all actions in a RESTful style resource controller. It will use a before action to load the resource into an instance variable and authorize it for every action.
class PostsController < ApplicationController

def show # @post is already loaded and authorized end

def index # @posts is already loaded with all posts the user is authorized to read end end

See Authorizing Controller Actions for more information.

3.3 Strong Parameters

You have to sanitize inputs before saving the record, in actions such as


For the

action, CanCanCan will load and authorize the resource but not change it automatically, so the typical usage would be something like:
def update
  if @post.update(post_params)
    # hurray
    render :edit

def post_params params.require(:post).permit(:body) end

For the

action, CanCanCan will try to initialize a new instance with sanitized input by seeing if your controller will respond to the following methods (in order):
  1. create_params
  2. _params
    such as
    (this is the default convention in rails for naming your param method)
  3. resource_params
    (a generically named method you could specify in each controller)


can now take a
option to specify a custom method in the controller to run to sanitize input.

You can associate the

option with a symbol corresponding to the name of a method that will get called:
class PostsController < ApplicationController
  load_and_authorize_resource param_method: :my_sanitizer

def create if # hurray else render :new end end


def my_sanitizer params.require(:post).permit(:name) end end

You can also use a string that will be evaluated in the context of the controller using

and needs to contain valid Ruby code.
load_and_authorize_resource param_method: ''

Finally, it's possible to associate

with a Proc object which will be called with the controller as the only argument:
load_and_authorize_resource param_method: { |c| c.params.require(:post).permit(:name) }

See Strong Parameters for more information.

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 CanCan::AccessDenied do |exception|
    respond_to do |format|
      format.json { head :forbidden, content_type: 'text/html' }
      format.html { redirect_to main_app.root_url, notice: exception.message }
      format.js   { head :forbidden, content_type: 'text/html' }

See Exception Handling for more information.

Lock It Down

If you want to ensure authorization happens on every action in your application, add

to your
class ApplicationController < ActionController::Base

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.

Wiki Docs


This repo is a continuation of the dead CanCan project. Our mission is to keep CanCan alive and moving forward, with maintenance fixes and new features. Pull Requests are welcome!

Any help is greatly appreciated, feel free to submit pull-requests or open issues.


If you have any question or doubt regarding CanCanCan which you cannot find the solution to in the documentation or our mailing list, please open a question on Stackoverflow with tag cancancan


If you find a bug please add an issue on GitHub or fork the project and send a pull request.


CanCanCan uses appraisals to test the code base against multiple versions of Rails, as well as the different model adapters.

When first developing, you need to run

bundle install
and then
bundle exec appraisal install
, to install the different sets.

You can then run all appraisal files (like CI does), with

appraisal rake
or just run a specific set
DB='sqlite' bundle exec appraisal activerecord_5.2.2 rake

See the CONTRIBUTING for more information.

Special Thanks

Many thanks to the CanCanCan 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.