Skip to content
This repository
Newer
Older
100644 152 lines (91 sloc) 6.985 kb
6c6a57be »
2009-11-16 adding documentation placeholder
1 = CanCan
2
66ff1f2e »
2010-07-21 removing metrics link in readme, farewell Caliper :(
3 Wiki[http://wiki.github.com/ryanb/cancan] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
a13f78d6 »
2009-12-30 listing additional resources at top of readme page (including metrics…
4
13427e18 »
2010-08-06 updating readme
5 CanCan is an authorization solution for Ruby on Rails for restricting what a given user is allowed to access throughout the application. It does not care how your user roles are defined, it simply focusses on keeping permission logic in a single location (the +Ability+ class) so it is not duplicated across controllers, views, and database queries.
f4669634 »
2010-04-16 allow access to classes when using hash conditions since you'll gener…
6
13427e18 »
2010-08-06 updating readme
7 By default, the +current_user+ method is required, so if you have not already, set up some authentication (such as Authlogic[http://github.com/binarylogic/authlogic] or Devise[http://github.com/plataformatec/devise]). See {Changing Defaults}[http://wiki.github.com/ryanb/cancan/changing-defaults] if you need different behavior.
b1d3d66e »
2009-11-16 filling readme
8
9
10 == Installation
11
13427e18 »
2010-08-06 updating readme
12 To install CanCan, include the gem in the environment.rb in Rails 2.3.
baeef0b9 »
2010-04-15 adding conditions behavior to Ability#can and fetch with Ability#cond…
13
f7480d1f »
2009-12-13 releasing gem v1.0.0 (backwards incompatible, see changelog)
14 config.gem "cancan"
baeef0b9 »
2010-04-15 adding conditions behavior to Ability#can and fetch with Ability#cond…
15
18dcf2a1 »
2010-07-21 mention Rails 3 installation in README - closes #56
16 Or the Gemfile in Rails 3.
17
18 gem "cancan"
19
283f58ee »
2010-04-17 improving readme with links to wiki
20 Alternatively it can be installed as a plugin.
28eaf1bc »
2009-11-16 releasing gem v0.1.0
21
22 script/plugin install git://github.com/ryanb/cancan.git
b1d3d66e »
2009-11-16 filling readme
23
24
f7480d1f »
2009-12-13 releasing gem v1.0.0 (backwards incompatible, see changelog)
25 == Getting Started
b1d3d66e »
2009-11-16 filling readme
26
13427e18 »
2010-08-06 updating readme
27 First, define a class called +Ability+ in "models/ability.rb" or anywhere else in the load path. It should look something like this.
b1d3d66e »
2009-11-16 filling readme
28
29 class Ability
30 include CanCan::Ability
25637bb3 »
2010-07-21 removing extra white space at end of lines
31
1edf5831 »
2009-11-17 BACKWARDS INCOMPATIBLE: use Ability#initialize instead of 'prepare' t…
32 def initialize(user)
b1d3d66e »
2009-11-16 filling readme
33 if user.admin?
34 can :manage, :all
35 else
36 can :read, :all
37 end
38 end
39 end
40
4322da9d »
2009-11-17 expanding readme documentation
41 This is where all permissions will go. See the "Defining Abilities" section below for more information.
b1d3d66e »
2009-11-16 filling readme
42
283f58ee »
2010-04-17 improving readme with links to wiki
43 The current user's permissions can be accessed using the "can?" and "cannot?" methods in the view and controller.
b1d3d66e »
2009-11-16 filling readme
44
45 <% if can? :update, @article %>
46 <%= link_to "Edit", edit_article_path(@article) %>
47 <% end %>
48
283f58ee »
2010-04-17 improving readme with links to wiki
49 See {Checking Abilities}[http://wiki.github.com/ryanb/cancan/checking-abilities] for more information
50
51 The "authorize!" method in the controller will raise an exception if the user is not able to perform the given action.
b1d3d66e »
2009-11-16 filling readme
52
53 def show
54 @article = Article.find(params[:id])
8903feee »
2010-04-16 removing unauthorized! in favor of authorize! and including more info…
55 authorize! :read, @article
b1d3d66e »
2009-11-16 filling readme
56 end
57
b9995c61 »
2010-04-17 minor changes to readme
58 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 each action.
b1d3d66e »
2009-11-16 filling readme
59
60 class ArticlesController < ApplicationController
f7480d1f »
2009-12-13 releasing gem v1.0.0 (backwards incompatible, see changelog)
61 load_and_authorize_resource
25637bb3 »
2010-07-21 removing extra white space at end of lines
62
b1d3d66e »
2009-11-16 filling readme
63 def show
283f58ee »
2010-04-17 improving readme with links to wiki
64 # @article is already loaded and authorized
b1d3d66e »
2009-11-16 filling readme
65 end
66 end
67
283f58ee »
2010-04-17 improving readme with links to wiki
68 See {Authorizing Controller Actions}[http://wiki.github.com/ryanb/cancan/authorizing-controller-actions] for more information
69
b9995c61 »
2010-04-17 minor changes to readme
70 If the user authorization fails, a CanCan::AccessDenied exception will be raised. You can catch this and modify its behavior in the +ApplicationController+.
b1d3d66e »
2009-11-16 filling readme
71
72 class ApplicationController < ActionController::Base
f919ac53 »
2009-12-14 releasing gem v1.0.1
73 rescue_from CanCan::AccessDenied do |exception|
ef22de68 »
2009-12-15 adding custom message argument to unauthorized! method - closes #18
74 flash[:error] = exception.message
b1d3d66e »
2009-11-16 filling readme
75 redirect_to root_url
76 end
77 end
78
283f58ee »
2010-04-17 improving readme with links to wiki
79 See {Exception Handling}[http://wiki.github.com/ryanb/cancan/exception-handling] for more information.
8903feee »
2010-04-16 removing unauthorized! in favor of authorize! and including more info…
80
b1d3d66e »
2009-11-16 filling readme
81
82 == Defining Abilities
83
283f58ee »
2010-04-17 improving readme with links to wiki
84 As shown above, the +Ability+ class is where all user permissions are defined. The user model is passed into the initialize method so the permissions can be modified based on any user attributes. CanCan makes no assumptions about how roles are handled in your application. See {Role Based Authorization}[http://wiki.github.com/ryanb/cancan/role-based-authorization] for an example.
b1d3d66e »
2009-11-16 filling readme
85
283f58ee »
2010-04-17 improving readme with links to wiki
86 The +can+ method is used to define permissions and requires two arguments. The first one is the action you're setting the permission for, the second one is the class of object you're setting it on.
b1d3d66e »
2009-11-16 filling readme
87
88 can :update, Article
89
283f58ee »
2010-04-17 improving readme with links to wiki
90 You can pass an array for either of these parameters to match any one. In this case the user will have the ability to update or destroy both articles and comments.
b1d3d66e »
2009-11-16 filling readme
91
92 can [:update, :destroy], [Article, Comment]
93
283f58ee »
2010-04-17 improving readme with links to wiki
94 Use :+manage+ to represent any action and :+all+ to represent any class. Here are some examples.
b1d3d66e »
2009-11-16 filling readme
95
283f58ee »
2010-04-17 improving readme with links to wiki
96 can :manage, Article # has permissions to do anything to articles
97 can :read, :all # has permission to read any model
98 can :manage, :all # has permission to do anything to any model
99
100 You can pass a hash of conditions as the third argument to further restrict what the user is able to access. Here the user will only have permission to read active projects which he owns.
b1d3d66e »
2009-11-16 filling readme
101
baeef0b9 »
2010-04-15 adding conditions behavior to Ability#can and fetch with Ability#cond…
102 can :read, Project, :active => true, :user_id => user.id
103
283f58ee »
2010-04-17 improving readme with links to wiki
104 See {Defining Abilities with Hashes}[http://wiki.github.com/ryanb/cancan/defining-abilities-with-hashes] for more information.
baeef0b9 »
2010-04-15 adding conditions behavior to Ability#can and fetch with Ability#cond…
105
283f58ee »
2010-04-17 improving readme with links to wiki
106 Blocks can also be used if you need more control.
baeef0b9 »
2010-04-15 adding conditions behavior to Ability#can and fetch with Ability#cond…
107
108 can :update, Project do |project|
109 project && project.groups.include?(user.group)
b1d3d66e »
2009-11-16 filling readme
110 end
111
283f58ee »
2010-04-17 improving readme with links to wiki
112 If the block returns true then the user has that :+update+ ability for that project, otherwise he will be denied access. See {Defining Abilities with Blocks}[http://wiki.github.com/ryanb/cancan/defining-abilities-with-blocks] for more information.
0f49b547 »
2009-11-17 adding 'cannot?' method which performs opposite check of 'can?' - clo…
113
b1d3d66e »
2009-11-16 filling readme
114
d4405e60 »
2009-11-25 adding cannot method to define which abilities cannot be done - closes
115 == Aliasing Actions
116
b9995c61 »
2010-04-17 minor changes to readme
117 You will usually be working with four actions when defining and checking permissions: :+read+, :+create+, :+update+, :+destroy+. These aren't the same as the 7 RESTful actions in Rails. CanCan automatically adds some default aliases for mapping those actions.
d4405e60 »
2009-11-25 adding cannot method to define which abilities cannot be done - closes
118
119 alias_action :index, :show, :to => :read
120 alias_action :new, :to => :create
121 alias_action :edit, :to => :update
122
283f58ee »
2010-04-17 improving readme with links to wiki
123 Notice the +edit+ action is aliased to +update+. If the user is able to update a record he also has permission to edit it. You can define your own aliases in the +Ability+ class
d4405e60 »
2009-11-25 adding cannot method to define which abilities cannot be done - closes
124
283f58ee »
2010-04-17 improving readme with links to wiki
125 alias_action :update, :destroy, :to => :modify
126 can :modify, Comment
127 can? :update, Comment # => true
f7480d1f »
2009-12-13 releasing gem v1.0.0 (backwards incompatible, see changelog)
128
283f58ee »
2010-04-17 improving readme with links to wiki
129 See {Custom Actions}[http://wiki.github.com/ryanb/cancan/custom-actions] for information on adding other actions.
f7480d1f »
2009-12-13 releasing gem v1.0.0 (backwards incompatible, see changelog)
130
131
37f482e8 »
2010-04-15 default ActiveRecordAdditions#can method action to :read and use 'sco…
132 == Fetching Records
133
283f58ee »
2010-04-17 improving readme with links to wiki
134 In the controller +index+ action you may want to fetch only the records which the user has permission to read. You can do this with the +accessible_by+ scope.
37f482e8 »
2010-04-15 default ActiveRecordAdditions#can method action to :read and use 'sco…
135
240c2810 »
2010-04-15 renaming ActiveRecordAdditions#can method to accessible_by since it f…
136 @articles = Article.accessible_by(current_ability)
37f482e8 »
2010-04-15 default ActiveRecordAdditions#can method action to :read and use 'sco…
137
283f58ee »
2010-04-17 improving readme with links to wiki
138 See {Fetching Records}[http://wiki.github.com/ryanb/cancan/fetching-records] for more information.
df276536 »
2009-11-17 adding documentation for testing abilities - closes #6
139
37f482e8 »
2010-04-15 default ActiveRecordAdditions#can method action to :read and use 'sco…
140
283f58ee »
2010-04-17 improving readme with links to wiki
141 == Additional Docs
37f482e8 »
2010-04-15 default ActiveRecordAdditions#can method action to :read and use 'sco…
142
13427e18 »
2010-08-06 updating readme
143 * {Upgrading to 1.3}[http://wiki.github.com/ryanb/cancan/upgrading-to-13]
144 * {Nested Resources}[http://wiki.github.com/ryanb/cancan/nested-resources]
283f58ee »
2010-04-17 improving readme with links to wiki
145 * {Testing Abilities}[http://wiki.github.com/ryanb/cancan/testing-abilities]
146 * {Accessing Request Data}[http://wiki.github.com/ryanb/cancan/accessing-request-data]
e1652ea4 »
2010-04-17 adding admin namespace wiki page link to readme
147 * {Admin Namespace}[http://wiki.github.com/ryanb/cancan/admin-namespace]
283f58ee »
2010-04-17 improving readme with links to wiki
148 * {See more}[http://wiki.github.com/ryanb/cancan/]
df276536 »
2009-11-17 adding documentation for testing abilities - closes #6
149
9d582265 »
2009-11-16 couple fixes in readme
150 == Special Thanks
151
5eae169d »
2010-07-21 mentioning CanCan contributors in README
152 CanCan was inspired by declarative_authorization[http://github.com/stffn/declarative_authorization/] and aegis[http://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[http://github.com/ryanb/cancan/contributors]. See the CHANGELOG[http://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.
Something went wrong with that request. Please try again.