Clone this wiki locally
My ultimate goal in CanCan 2.0 is to make the behavior more intuitive. I've seen times in the issue tracker where it is used in a way it wasn't intended, or cases it authorized access when they didn't think it should. I'm taking all of this into account.
The biggest change is that basic controller action authorization will be handled by default. This means everything will be locked down with one simple
enable_authorization call. The
load_and_authorize_resource behavior is still there, but now only necessary if needing to check permission on resource instances.
This means abilities will be more focused on controller actions than resource classes, but this doesn't mean resources are being left in the dust. Another big feature is that you can add fine-grain permissions on specific resource attributes. See the Resource Attributes section below.
CanCan 2.0 is still in very early development. Currently little of what I'm describing here works, but I am writing the readme first. See the 2.0 branch for progress on the implementation and the issue tracker for feedback.
First add authentication if you haven't already. This can be done through Devise, Authlogic, etc. The only thing CanCan requires by default is a
current_user method in the controller.
To install CanCan, add it to your Gemfile and run the
gem "cancan", "2.0" # not yet available
Next generate an Ability class, this is where your permissions will be defined.
rails g cancan:ability
Then enable authorization in your ApplicationController or any controller you want authorization to happen in.
class ApplicationController < ActionController::Base enable_authorization end
This will add an authorization check locking down every controller action. If you try visiting a page a
CanCan::Unauthorized exception will be raised since you have not granted the user ability to access it. You can customize the behavior of this exception by passing a block.
enable_authorization do |exception| redirect_to root_url, :alert => exception.message end
or you can rescue from the exception itself.
enable_authorization rescue_from CanCan::Unauthorized do |exception| redirect_to root_url, :alert => exception.message end
Here it will redirect the user to the home page with an alert message when unauthorized. If you do this, make sure the user has permission to access the home page.
If you're using devise and only want to enable authorization for non-devise controllers, then you can achieve it like the code below.
enable_authorization do |exception| redirect_to root_url, :alert => exception.message end unless :devise_controller?
You grant access to controller actions through the
Ability class. The
current_user is passed into the
initialize method allowing you to define permissions based on user attributes.
def initialize(user) if user can :access, :all else can :access, :home end end
As you can see here, if a logged in user exists he can access the entire application, but guest users can only access the HomeController.
The first argument to
can is the name of the controller action. Using
:access here will allow access to all actions on that controller. The second argument is the name of the controller. Using
:all here will represent all controllers. Either one can be an array to represent multiple actions and controllers.
can [:create, :update], [:posts, :comments]
Here the user will be able to create and update both posts and comments. You don't need to mention the
edit actions because CanCan includes some default aliases. See the Aliases page for details.
You can check permissions in any controller or view using the
<% if can? :create, :comments %> <%= link_to "New Comment", new_comment_path %> <% end %>
Here the link will only show up if one can create comments.
In CanCan 2.0, there's a slight change in the way in which can rules are evaluated. A more specific
can rule below a general
can rule will overwrite it.
can :read, :projects can :read, :projects, :title => 'Sir'
The specific rule in the end will override a previous generic rule.
What if you need to change authorization based on a model's attributes? You can do so by passing a hash of conditions as the last argument to
can. For example, if you want to only allow one to access projects which he owns you can set the
can :access, :projects, :user_id => user.id
A block can also be used for complex condition checks just like in CanCan 1, but here it is not necessary.
If you try visiting any of the project pages at this point you will see a
CanCan::InsufficientCheck exception is raised. This is because the default authorization has no way to check permissions on the
@project instance. You can check permissions on an object manually using the
def edit @project = Project.find(params[:id]) authorize! :edit, @project end
However this can get tedious. Instead CanCan provides a
load_and_authorize_resource method to load the
@project instance in every controller action and authorize it.
class ProjectsController < ApplicationController load_and_authorize_resource def edit # @project already loaded here and authorized end end
index (and other collection actions) will load the
@projects instance which automatically limits the projects the user is allowed to access. This is a scope so you can make further calls to
where to limit what is returned from the database.
You can check permissions on instances using the
can? method as well.
<%= link_to "Edit Project", edit_project_path if can? :update, @project %>
Here it will only show the edit link if the
It is possible to define permissions on specific resource attributes. For example, if you want to allow a user to only update the name and priority of a project, pass that as the third argument to
can :update, :projects, [:name, :priority]
If you use this in combination with
load_and_authorize_resource it will ensure that only those two attributes exist in
params[:project] when updating the project. If you do this everywhere it will not be necessary to use
attr_accessible in your models.
You can combine this with a hash of conditions. For example, here the user can only update the price if the product isn't discontinued.
can :update, :products, :price, :discontinued => false
You can check permissions on specific attributes to determine what to show in the form.
<%= f.text_field :name if can? :update, @project, :name %>
What do you think?
Please submit any feedback to the issue tracker. If you want CanCan 2.0 to work a certain way, now is the time to request it.