Skip to content
Newer
Older
100644 112 lines (62 sloc) 4.79 KB
6c6a57b @ryanb adding documentation placeholder
ryanb authored
1 = CanCan
2
39bffe9 @ryanb fixing github links in readme
ryanb authored
3 Wiki[https://github.com/ryanb/cancan/wiki] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
a13f78d @ryanb listing additional resources at top of readme page (including metrics…
ryanb authored
4
6c3e87e @ryanb updating readme and documentation
ryanb authored
5 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.
b1d3d66 @ryanb filling readme
ryanb authored
6
7
8 == Installation
9
2012311 @ryanb readme improvements
ryanb authored
10 In <b>Rails 3</b>, add this to your Gemfile and run the +bundle+ command.
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
ryanb authored
11
6c3e87e @ryanb updating readme and documentation
ryanb authored
12 gem "cancan"
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
ryanb authored
13
6c3e87e @ryanb updating readme and documentation
ryanb authored
14 In <b>Rails 2</b>, add this to your environment.rb file.
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
ryanb authored
15
6c3e87e @ryanb updating readme and documentation
ryanb authored
16 config.gem "cancan"
18dcf2a @ryanb mention Rails 3 installation in README - closes #56
ryanb authored
17
6c3e87e @ryanb updating readme and documentation
ryanb authored
18 Alternatively, you can install it as a plugin.
28eaf1b @ryanb releasing gem v0.1.0
ryanb authored
19
6c3e87e @ryanb updating readme and documentation
ryanb authored
20 rails plugin install git://github.com/ryanb/cancan.git
b1d3d66 @ryanb filling readme
ryanb authored
21
22
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
ryanb authored
23 == Getting Started
b1d3d66 @ryanb filling readme
ryanb authored
24
2012311 @ryanb readme improvements
ryanb authored
25 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.
6c3e87e @ryanb updating readme and documentation
ryanb authored
26
2012311 @ryanb readme improvements
ryanb authored
27
28 === 1. Define Abilities
29
30 User permissions are defined in an +Ability+ class. CanCan 1.5 includes a Rails 3 generator for creating this class.
b1d3d66 @ryanb filling readme
ryanb authored
31
120eafe @ryanb updating readme for 1.5
ryanb authored
32 rails g cancan:ability
25637bb @ryanb removing extra white space at end of lines
ryanb authored
33
2012311 @ryanb readme improvements
ryanb authored
34 See {Defining Abilities}[https://github.com/ryanb/cancan/wiki/defining-abilities] for details.
35
36
37 === 2. Check Abilities & Authorization
b1d3d66 @ryanb filling readme
ryanb authored
38
120eafe @ryanb updating readme for 1.5
ryanb authored
39 The current user's permissions can then be checked using the <tt>can?</tt> and <tt>cannot?</tt> methods in the view and controller.
b1d3d66 @ryanb filling readme
ryanb authored
40
41 <% if can? :update, @article %>
42 <%= link_to "Edit", edit_article_path(@article) %>
43 <% end %>
44
39bffe9 @ryanb fixing github links in readme
ryanb authored
45 See {Checking Abilities}[https://github.com/ryanb/cancan/wiki/checking-abilities] for more information
283f58e @ryanb improving readme with links to wiki
ryanb authored
46
2012311 @ryanb readme improvements
ryanb authored
47 The <tt>authorize!</tt> method in the controller will raise an exception if the user is not able to perform the given action.
b1d3d66 @ryanb filling readme
ryanb authored
48
49 def show
50 @article = Article.find(params[:id])
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
ryanb authored
51 authorize! :read, @article
b1d3d66 @ryanb filling readme
ryanb authored
52 end
53
2012311 @ryanb readme improvements
ryanb authored
54 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.
b1d3d66 @ryanb filling readme
ryanb authored
55
56 class ArticlesController < ApplicationController
f7480d1 @ryanb releasing gem v1.0.0 (backwards incompatible, see changelog)
ryanb authored
57 load_and_authorize_resource
25637bb @ryanb removing extra white space at end of lines
ryanb authored
58
b1d3d66 @ryanb filling readme
ryanb authored
59 def show
283f58e @ryanb improving readme with links to wiki
ryanb authored
60 # @article is already loaded and authorized
b1d3d66 @ryanb filling readme
ryanb authored
61 end
62 end
63
120eafe @ryanb updating readme for 1.5
ryanb authored
64 See {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/authorizing-controller-actions] for more information.
283f58e @ryanb improving readme with links to wiki
ryanb authored
65
2012311 @ryanb readme improvements
ryanb authored
66
67 === 3. Handle Unauthorized Access
68
6c3e87e @ryanb updating readme and documentation
ryanb authored
69 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+.
b1d3d66 @ryanb filling readme
ryanb authored
70
71 class ApplicationController < ActionController::Base
f919ac5 @ryanb releasing gem v1.0.1
ryanb authored
72 rescue_from CanCan::AccessDenied do |exception|
b2028c8 @ryanb moving :alert into redirect_to call in documentation
ryanb authored
73 redirect_to root_url, :alert => exception.message
b1d3d66 @ryanb filling readme
ryanb authored
74 end
75 end
76
39bffe9 @ryanb fixing github links in readme
ryanb authored
77 See {Exception Handling}[https://github.com/ryanb/cancan/wiki/exception-handling] for more information.
8903fee @ryanb removing unauthorized! in favor of authorize! and including more info…
ryanb authored
78
b1d3d66 @ryanb filling readme
ryanb authored
79
79995e4 @ryanb adding Lock It Down section to readme
ryanb authored
80 === 4. Lock It Down
81
82 If you want to ensure authorization happens on every action in your application, add +check_authorization+ to your ApplicationController.
83
84 class ApplicationController < ActionController::Base
85 check_authorization
86 end
87
88 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.
89
90
120eafe @ryanb updating readme for 1.5
ryanb authored
91 == Wiki Docs
37f482e @ryanb default ActiveRecordAdditions#can method action to :read and use 'sco…
ryanb authored
92
efa3ff1 @ryanb releasing 1.6.0
ryanb authored
93 * {Upgrading to 1.6}[https://github.com/ryanb/cancan/wiki/Upgrading-to-1.6]
120eafe @ryanb updating readme for 1.5
ryanb authored
94 * {Defining Abilities}[https://github.com/ryanb/cancan/wiki/Defining-Abilities]
95 * {Checking Abilities}[https://github.com/ryanb/cancan/wiki/Checking-Abilities]
96 * {Authorizing Controller Actions}[https://github.com/ryanb/cancan/wiki/Authorizing-Controller-Actions]
97 * {Exception Handling}[https://github.com/ryanb/cancan/wiki/Exception-Handling]
98 * {Changing Defaults}[https://github.com/ryanb/cancan/wiki/Changing-Defaults]
39bffe9 @ryanb fixing github links in readme
ryanb authored
99 * {See more}[https://github.com/ryanb/cancan/wiki]
df27653 @ryanb adding documentation for testing abilities - closes #6
ryanb authored
100
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
ryanb authored
101
102 == Questions or Problems?
103
2012311 @ryanb readme improvements
ryanb authored
104 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.
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
ryanb authored
105
2012311 @ryanb readme improvements
ryanb authored
106 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.
18b45d5 @ryanb adding Gemfile, to get specs running just bundle and rake - closes #163
ryanb authored
107
108
9d58226 @ryanb couple fixes in readme
ryanb authored
109 == Special Thanks
110
39bffe9 @ryanb fixing github links in readme
ryanb authored
111 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.
Something went wrong with that request. Please try again.