@@ -21,6 +21,7 @@ Plugin features
2121 * Authorize CRUD (Create, Read, Update, Delete) activities
2222 * Query rewriting to automatically only fetch authorized records
2323* DSL for specifying Authorization rules in an authorization configuration
24+ * Support for Rails 4, with backwards compatibility through Rails 2
2425
2526
2627Requirements
@@ -36,6 +37,99 @@ There is a decl_auth screencast by Ryan Bates, nicely introducing the main conce
3637http://railscasts.com/episodes/188-declarative-authorization
3738
3839
40+ = Quick Start
41+
42+ === Installer
43+
44+ Declarative Authorization comes with an installer to make setup easy.
45+
46+ First, include declarative_authorization in your gemfile.
47+
48+ #! Gemfile
49+ gem 'declarative_authorization'
50+
51+ Next, bundle and install.
52+
53+ $ bundle
54+ $ rails g authorization:install [UserModel=User] [field:type field:type ...] [--create-user --commit --user-belongs-to-role]
55+
56+ This installer will create a Role model, an admin and a user role, and set a
57+ has_and_belongs_to_many relationship between the User model and the Role model.
58+ It will also add a `role_symbols` method to the user model to meet
59+ declarative_authorization's requirements. The default User model is User. You can override this by simply typing the name of a model as above.
60+
61+ You can create the model with the fields provided by using the `--create-user` option.
62+
63+ The `--commit` option will run `rake db:migrate` and `rake db:seed`.
64+
65+ The `--user-belongs-to-role` option will set up a one-to-many relationship between Users and Roles.
66+ That is, each user has a role_id column and can only have one role. Role inheritance can be used
67+ in authorization rules.
68+
69+ Finally, the installer also copies default authorization rules, as below.
70+
71+ === Generate Authorization Rules
72+
73+ To copy a default set of authorization rules which includes CRUD priveleges, run:
74+
75+ $ rails g authorization:rules
76+
77+ This command will copy the following to `config/authorization_rules.rb`. Remember
78+ to implement the requirements of this gem as described in the Installation section
79+ at the end of this README if you do not use the above installer.
80+
81+ authorization do
82+ role :guest do
83+ # add permissions for guests here, e.g.
84+ # has_permission_on :conferences, :to => :read
85+ end
86+
87+ # permissions on other roles, such as
88+ # role :admin do
89+ # has_permission_on :conferences, :to => :manage
90+ # end
91+ # role :user do
92+ # has_permission_on :conferences, :to => [:read, :create]
93+ # has_permission_on :conferences, :to => [:update, :delete] do
94+ # if_attribute :user_id => is {user.id}
95+ # end
96+ # end
97+ # See the readme or GitHub for more examples
98+ end
99+
100+ privileges do
101+ # default privilege hierarchies to facilitate RESTful Rails apps
102+ privilege :manage, :includes => [:create, :read, :update, :delete]
103+ privilege :create, :includes => :new
104+ privilege :read, :includes => [:index, :show]
105+ privilege :update, :includes => :edit
106+ privilege :delete, :includes => :destroy
107+ end
108+
109+ === Controller Authorization
110+
111+ For RESTful controllers, add `filter_resource_access`:
112+
113+ class MyRestfulController < ApplicationController
114+ filter_resource_access
115+ ...
116+ end
117+
118+ For a non-RESTful controller, you can use `filter_access_to`:
119+
120+ class MyOtherController < ApplicationController
121+ filter_access_to :all
122+ # or a group: filter_access_to [:action1, :action2]
123+ ...
124+ end
125+
126+ === View Authorization
127+
128+ Declarative Authorization will use `current_user` to check authorization.
129+
130+ <%= link_to 'Edit Post', edit_post_path(@post) if permitted_to? :update, @post %>
131+
132+
39133= Authorization Data Model
40134
41135 ----- App domain ----|-------- Authorization conf ---------|------- App domain ------
@@ -92,6 +186,15 @@ filter_access_to with the appropriate parameters to protect the CRUD methods.
92186See Authorization::AuthorizationInController::ClassMethods for options on
93187nested resources and custom member and collection actions.
94188
189+ By default, declarative_authorization will enable filter_resource_access compatibility with strong_parameters in Rails 4. If you want to disable this behavior, you can use the `:strong_parameters` option.
190+
191+ class EmployeesController < ApplicationController
192+ filter_resource_access :strong_parameters => false
193+ ...
194+ end
195+
196+ Simalarly, you can use `:strong_parameters => true` if you are using strong_parameters in Rails 3.
197+
95198If you prefer less magic or your controller has no resemblance with the resource
96199controllers, directly calling filter_access_to may be the better option. Examples
97200are given in the following. E.g. the privilege index users is required for
0 commit comments