Skip to content

Latest commit

 

History

History
153 lines (92 loc) · 6.44 KB

README.rdoc

File metadata and controls

153 lines (92 loc) · 6.44 KB
Raw

CanCan ↑

<img src=“https://fury-badge.herokuapp.com/rb/cancan.png” alt=“Gem Version” /> <img src=“https://secure.travis-ci.org/ryanb/cancan.png?branch=master” /> <img src=“https://codeclimate.com/github/ryanb/cancan.png” />

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://github.com/ryanb/cancan.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 app/models/ability.rb with the following contents:

class Ability
  include CanCan::Ability

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

Strong Parameters ↑

When using strong_parameters or Rails 4+, you have to sanitize inputs before saving the record, in actions such as :create and :update.

By default, CanCan will try to sanitize the input on :create and :update routes by seeing if your controller will respond to the following methods (in order):

  • create_params or update_params (depending on the action you are performing)

  • <model_name>_params such as article_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.

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

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
  rescue_from CanCan::AccessDenied do |exception|
    redirect_to 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 skip_authorization_check to a controller subclass. See Ensure Authorization for more information.

Wiki Docs ↑

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 declarative_authorization and aegis. Also many thanks to the CanCan contributors. See the CHANGELOG for the full list.