Wiki | RDocs | Screencast | IRC: #cancancan (freenode)
I made this fork to update uses of before_filter
to before_action
, as the former is being removed as of Rails 5.1. To use my github repository, add this to your gemfile:
gem 'cancancan', github: 'piedoom/cancancan', branch: 'rails5.0'
##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.
This branch represents work towards version 2.0. Please checkout the 1.x branch for the stable release. Use master at your own risk.
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!
I am currently focusing on the 1.x branch for the immediate future, making sure it is up to date as well as ensuring compatibility with Rails 4+. I will take a look into the 2.x branch and try to see what improvements, reorganizations and redesigns Ryan was attempting and go forward from there.
Any help is greatly appreciated, feel free to submit pull-requests or open issues.
In Rails 3 and 4, add this to your Gemfile and run the bundle install
command.
gem 'cancancan', '~> 1.10'
For Rails 5, add this to your Gemfile and run the bundle install
command.
gem 'cancancan', github: 'piedoom/cancancan', branch: 'rails5.0'
CanCanCan 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.
When using rails-api, you have to manually include the controller methods for CanCan:
class ApplicationController < ActionController::API
include CanCan::ControllerAdditions
end
User permissions are defined in an Ability
class. CanCan 1.5 includes a Rails 3 and 4 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 for details.
The current user's permissions can then be checked using the can?
and cannot?
methods in the view and controller.
<% if can? :update, @article %>
<%= link_to "Edit", edit_article_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 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 for more information.
When using strong_parameters
or Rails 4+, you have to sanitize inputs before saving the record, in actions such as :create
and :update
.
For the :update
action, CanCan will load and authorize the resource but not change it automatically, so the typical usage would be something like:
def update
if @article.update_attributes(update_params)
# hurray
else
render :edit
end
end
...
def update_params
params.require(:article).permit(:body)
end
For the :create
action, CanCan will try to initialize a new instance with sanitized input by seeing if your controller will respond to the following methods (in order):
create_params
<model_name>_params
such asarticle_params
(this is the default convention in rails for naming your param method)resource_params
(a generically named method you could specify in each controller)
Additionally, load_and_authorize_resource
can now take a param_method
option to specify a custom method in the controller to run to sanitize input.
You can associate the param_method
option with a symbol corresponding to the name of a method that will get called:
class ArticlesController < ApplicationController
load_and_authorize_resource param_method: :my_sanitizer
def create
if @article.save
# hurray
else
render :new
end
end
private
def my_sanitizer
params.require(:article).permit(:name)
end
end
You can also use a string that will be evaluated in the context of the controller using instance_eval
and needs to contain valid Ruby code. This does come in handy when using a PermittedParams class as suggested in Railscast 371:
load_and_authorize_resource param_method: 'permitted_params.article'
Finally, it's possible to associate param_method
with a Proc object which will be called with the controller as the only argument:
load_and_authorize_resource param_method: Proc.new { |c| c.params.require(:article).permit(:name) }
See Strong Parameters for more information.
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 for more information.
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 for more information.
- Upgrading to 1.6
- Defining Abilities
- Checking Abilities
- Authorizing Controller Actions
- Exception Handling
- Changing Defaults
- See more
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 may need to run bundle install
and then 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 appraisal activerecord_3.0 rake
.
See the CONTRIBUTING and spec/README for more information.
CanCan was inspired by declarative_authorization and aegis. Also many thanks to the CanCan contributors. See the CHANGELOG for the full list.