Authorization Gem for Ruby on Rails.
Go to file
Will Bradley acc76446c5 Making initial changes to add authorize after update 2013-06-28 23:34:07 -04:00
lib Making initial changes to add authorize after update 2013-06-28 23:34:07 -04:00
spec fix matches_conditons_hash for string values on 1.8 2013-05-07 11:23:08 -07:00
.gitignore checks if active record responds to 'joins', so this can work with internuity's quick_scopes gem; added .swp files to git ignore 2010-11-13 02:21:56 +08:00
.rbenv-version adding a .rbenv-version file 2012-05-10 14:24:13 -07:00
.rspec adding Gemfile, to get specs running just bundle and rake - closes #163 2010-10-05 10:09:37 -07:00
.rvmrc simplifying .rvmrc 2011-03-08 15:23:31 -08:00
.travis.yml removing jruby/rubinius from travis.yml for now until I figure out why they aren't passing 2011-09-28 16:24:03 -07:00
CHANGELOG.rdoc releasing 1.6.10 2013-05-07 11:29:15 -07:00 add contributing guide 2012-10-13 21:01:46 +03:00
Gemfile Use latest with_model gem 2011-11-02 22:37:37 -04:00
LICENSE improving DataMapper adapter and specs 2011-01-05 13:22:06 -08:00
README.rdoc add gem version badge (thanks Gemfury) 2012-12-11 16:58:20 -08:00
Rakefile adding spec_all task for running specs for all model adapters 2010-12-30 15:50:40 -08:00
cancan.gemspec releasing 1.6.10 2013-05-07 11:29:15 -07:00
init.rb turning into a funtioning Rails plugin 2009-11-16 19:24:04 -08:00


= CanCan {<img src="" alt="Gem Version" />}[] {<img src="" />}[] {<img src="" />}[]

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 <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.

  gem "cancan"

In <b>Rails 2</b>, 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 `app/models/ability.rb` with the folowing 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 <tt>can?</tt> and <tt>cannot?</tt> 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 <tt>authorize!</tt> 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

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

    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 <tt>CanCan::AccessDenied</tt> 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

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

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

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