cancan/README.rdoc

112 lines
4.8 KiB
Plaintext
Raw Normal View History

2009-11-17 01:03:54 +00:00
= CanCan
2011-01-08 21:25:45 +00:00
Wiki[https://github.com/ryanb/cancan/wiki] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
2010-10-05 23:18:35 +00:00
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.
2009-11-17 05:23:06 +00:00
== Installation
2011-01-18 19:55:46 +00:00
In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
2010-10-05 23:18:35 +00:00
gem "cancan"
2010-10-05 23:18:35 +00:00
In <b>Rails 2</b>, add this to your environment.rb file.
2010-10-05 23:18:35 +00:00
config.gem "cancan"
2010-10-05 23:18:35 +00:00
Alternatively, you can install it as a plugin.
2009-11-17 06:15:10 +00:00
2010-10-05 23:18:35 +00:00
rails plugin install git://github.com/ryanb/cancan.git
2009-11-17 05:23:06 +00:00
== Getting Started
2009-11-17 05:23:06 +00:00
2011-01-18 19:55:46 +00:00
CanCan expects a +current_user+ method to exist in the controller. First, set up some authentication (such as Authlogic[https://github.com/binarylogic/authlogic] or Devise[https://github.com/plataformatec/devise]). See {Changing Defaults}[https://github.com/ryanb/cancan/wiki/changing-defaults] if you need different behavior.
2010-10-05 23:18:35 +00:00
2011-01-18 19:55:46 +00:00
=== 1. Define Abilities
User permissions are defined in an +Ability+ class. CanCan 1.5 includes a Rails 3 generator for creating this class.
2009-11-17 05:23:06 +00:00
2011-01-11 08:21:42 +00:00
rails g cancan:ability
2011-01-18 19:55:46 +00:00
See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details.
=== 2. Check Abilities & Authorization
2009-11-17 05:23:06 +00:00
2011-01-11 08:21:42 +00:00
The current user's permissions can then be checked using the <tt>can?</tt> and <tt>cannot?</tt> methods in the view and controller.
2009-11-17 05:23:06 +00:00
<% if can? :update, @article %>
<%= link_to "Edit", edit_article_path(@article) %>
<% end %>
2011-01-08 21:25:45 +00:00
See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information
2010-04-17 18:45:41 +00:00
2011-01-18 19:55:46 +00:00
The <tt>authorize!</tt> method in the controller will raise an exception if the user is not able to perform the given action.
2009-11-17 05:23:06 +00:00
def show
@article = Article.find(params[:id])
authorize! :read, @article
2009-11-17 05:23:06 +00:00
end
2011-01-18 19:55:46 +00:00
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.
2009-11-17 05:23:06 +00:00
class ArticlesController < ApplicationController
load_and_authorize_resource
2009-11-17 05:23:06 +00:00
def show
2010-04-17 18:45:41 +00:00
# @article is already loaded and authorized
2009-11-17 05:23:06 +00:00
end
end
2011-01-11 08:21:42 +00:00
See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information.
2010-04-17 18:45:41 +00:00
2011-01-18 19:55:46 +00:00
=== 3. Handle Unauthorized Access
If the user authorization fails, a <tt>CanCan::Unauthorized</tt> exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.
2009-11-17 05:23:06 +00:00
class ApplicationController < ActionController::Base
rescue_from CanCan::Unauthorized do |exception|
redirect_to root_url, :alert => exception.message
2009-11-17 05:23:06 +00:00
end
end
2011-01-08 21:25:45 +00:00
See {Exception Handling}[https://github.com/ryanb/cancan/wiki/exception-handling] for more information.
2009-11-17 05:23:06 +00:00
2011-02-22 17:37:53 +00:00
=== 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}[https://github.com/ryanb/cancan/wiki/Ensure-Authorization] for more information.
2011-01-11 08:21:42 +00:00
== Wiki Docs
2011-03-11 07:59:13 +00:00
* {Upgrading to 1.6}[https://github.com/ryanb/cancan/wiki/Upgrading-to-1.6]
2011-01-11 08:21:42 +00:00
* {Defining Abilities}[https://github.com/ryanb/cancan/wiki/Defining-Abilities]
* {Checking Abilities}[https://github.com/ryanb/cancan/wiki/Checking-Abilities]
* {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/Authorizing-Controller-Actions]
* {Exception Handling}[https://github.com/ryanb/cancan/wiki/Exception-Handling]
* {Changing Defaults}[https://github.com/ryanb/cancan/wiki/Changing-Defaults]
2011-01-08 21:25:45 +00:00
* {See more}[https://github.com/ryanb/cancan/wiki]
== Questions or Problems?
2011-01-18 19:55:46 +00:00
If you have any issues with CanCan which you cannot find the solution to in the documentation[https://github.com/ryanb/cancan/wiki], please add an {issue on GitHub}[https://github.com/ryanb/cancan/issues] or fork the project and send a pull request.
2011-01-18 19:55:46 +00:00
To get the specs running you should call +bundle+ and then +rake+. See the {spec/README}[https://github.com/ryanb/cancan/blob/master/spec/README.rdoc] for more information.
2009-11-17 06:31:27 +00:00
== Special Thanks
2011-01-08 21:25:45 +00:00
CanCan was inspired by declarative_authorization[https://github.com/stffn/declarative_authorization/] and aegis[https://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[https://github.com/ryanb/cancan/contributors]. See the CHANGELOG[https://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.