timcharper-declarative_authorization 0.4.1.2
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGELOG +135 -0
- data/MIT-LICENSE +20 -0
- data/README.rdoc +503 -0
- data/Rakefile +43 -0
- data/app/controllers/authorization_rules_controller.rb +259 -0
- data/app/controllers/authorization_usages_controller.rb +23 -0
- data/app/helpers/authorization_rules_helper.rb +218 -0
- data/app/views/authorization_rules/_change.erb +58 -0
- data/app/views/authorization_rules/_show_graph.erb +37 -0
- data/app/views/authorization_rules/_suggestions.erb +48 -0
- data/app/views/authorization_rules/change.html.erb +169 -0
- data/app/views/authorization_rules/graph.dot.erb +68 -0
- data/app/views/authorization_rules/graph.html.erb +40 -0
- data/app/views/authorization_rules/index.html.erb +17 -0
- data/app/views/authorization_usages/index.html.erb +36 -0
- data/authorization_rules.dist.rb +20 -0
- data/config/routes.rb +7 -0
- data/garlic_example.rb +20 -0
- data/init.rb +5 -0
- data/lib/declarative_authorization.rb +15 -0
- data/lib/declarative_authorization/authorization.rb +683 -0
- data/lib/declarative_authorization/development_support/analyzer.rb +252 -0
- data/lib/declarative_authorization/development_support/change_analyzer.rb +253 -0
- data/lib/declarative_authorization/development_support/change_supporter.rb +620 -0
- data/lib/declarative_authorization/development_support/development_support.rb +243 -0
- data/lib/declarative_authorization/helper.rb +60 -0
- data/lib/declarative_authorization/in_controller.rb +623 -0
- data/lib/declarative_authorization/in_model.rb +162 -0
- data/lib/declarative_authorization/maintenance.rb +198 -0
- data/lib/declarative_authorization/obligation_scope.rb +345 -0
- data/lib/declarative_authorization/rails_legacy.rb +14 -0
- data/lib/declarative_authorization/reader.rb +472 -0
- data/test/authorization_test.rb +971 -0
- data/test/controller_filter_resource_access_test.rb +511 -0
- data/test/controller_test.rb +465 -0
- data/test/dsl_reader_test.rb +157 -0
- data/test/helper_test.rb +171 -0
- data/test/maintenance_test.rb +46 -0
- data/test/model_test.rb +1694 -0
- data/test/schema.sql +54 -0
- data/test/test_helper.rb +134 -0
- metadata +119 -0
data/CHANGELOG
ADDED
@@ -0,0 +1,135 @@
|
|
1
|
+
* Rails 3 support
|
2
|
+
|
3
|
+
* Support shallow nested resources [jjb]
|
4
|
+
|
5
|
+
* Allow multiple authorization rules files [kaichen]
|
6
|
+
|
7
|
+
** RELEASE 0.4 (November 15, 2009) **
|
8
|
+
|
9
|
+
* Implemented controller namespace handling [sb]
|
10
|
+
|
11
|
+
* Improved if_attribute to allow nesting of has_many associations [sb]
|
12
|
+
|
13
|
+
* Improved if_permitted_to: allow has_many associations and improved context inference [sb]
|
14
|
+
|
15
|
+
* Added option on handling non-existant auto-loaded object [sb]
|
16
|
+
|
17
|
+
* Added with_user as module method [sb]
|
18
|
+
|
19
|
+
* Change support i18n [sb]
|
20
|
+
|
21
|
+
** RELEASE 0.3.2.3 (October 12, 2009) **
|
22
|
+
|
23
|
+
* Switched to gemcutter [sb]
|
24
|
+
|
25
|
+
* Fixed has_role? for guest user. Closes #8 [sb]
|
26
|
+
|
27
|
+
* Fixed unnecessary DB query with named scopes [sb, ledermann]
|
28
|
+
|
29
|
+
* Change support: suggestions: grouping, sorting by affected users [sb]
|
30
|
+
|
31
|
+
* Fixed context inference from AR objects for STI by switching to #class.name.tableize [sb]
|
32
|
+
|
33
|
+
* Allow multiple contexts as arguments to has_permission_on [Jeroen van Dijk]
|
34
|
+
|
35
|
+
** RELEASE 0.3.2.2 (August 27, 2009) **
|
36
|
+
|
37
|
+
* Fix without_access_control test cases [sb]
|
38
|
+
|
39
|
+
* Fixed error on debug logging (Closes #6) [sb]
|
40
|
+
|
41
|
+
* Fixed without_access_control instance method in TestHelper [sb]
|
42
|
+
|
43
|
+
** RELEASE 0.3.2.1 (August 14, 2009) **
|
44
|
+
|
45
|
+
* Fix gemspec for Rdoc generation [sb]
|
46
|
+
|
47
|
+
** RELEASE 0.3.2 (August 13, 2009) **
|
48
|
+
|
49
|
+
* Fix for model-level permitted_to?/! [sb]
|
50
|
+
|
51
|
+
** RELEASE 0.3.1 (August 12, 2009) **
|
52
|
+
|
53
|
+
* Change Support: Suggestion grouping, sort by affected users [sb]
|
54
|
+
|
55
|
+
* Changed context derived from objects to #class.name.tableize to fix STI [sb]
|
56
|
+
|
57
|
+
* Simplified controller authorization with filter_resource_access [sb]
|
58
|
+
|
59
|
+
* Allow passing explicit context in addition to object in permitted_to? [Olly Lylo, sb]
|
60
|
+
|
61
|
+
* Change Supporter: suggest changes to authorization rules [sb]
|
62
|
+
|
63
|
+
* Added permitted_to!/? in model [Eike Carls]
|
64
|
+
|
65
|
+
* New test helper: should_(not_)_be_allowed_to(privilege, object_or_context) [sb]
|
66
|
+
|
67
|
+
** RELEASE 0.3 (April 20, 2009) **
|
68
|
+
|
69
|
+
* New option :join_by for has_permission_on to allow AND'ing of statements in one has_permission_on block [sb]
|
70
|
+
|
71
|
+
* Allow using_access_control to be called directly on ActiveRecord::Base, globally enabling model security [sb]
|
72
|
+
|
73
|
+
* New operator: intersects_with, comparing two Enumerables in if_attribute [sb]
|
74
|
+
|
75
|
+
* Improved if_permitted_to syntax: if the attribute is left out, permissions are checked on for the current object [sb]
|
76
|
+
|
77
|
+
* Added #has_role_with_hierarchy? method to retrieve explicit and calculated roles [jeremyf]
|
78
|
+
|
79
|
+
* Added a simple rules analyzer to help improve authorization rules [sb]
|
80
|
+
|
81
|
+
* Gemified plugin. Needed to restructure the lib path contents [sb]
|
82
|
+
|
83
|
+
* Added handling of Authorization::AuthorizationInController::ClassMethods.filter_access_to parameters that are of the form [:show, :update] instead of just :show, :update. [jeremyf]
|
84
|
+
|
85
|
+
* Added authorization usage helper for checking filter_access_to usage in controllers [sb]
|
86
|
+
|
87
|
+
* Added a authorization rules browser. See README for more information [sb]
|
88
|
+
|
89
|
+
* Added Model.using_access_control? to check if a model has model security activated [sb]
|
90
|
+
|
91
|
+
* Changed Authorization::ObligationScope#map_table_alias_for [Brian Langenfeld]
|
92
|
+
* Fixed to prevent bad aliases from being produced.
|
93
|
+
|
94
|
+
* Changed Authorization::Attribute#validate? [Brian Langenfeld]
|
95
|
+
* Encountering a nil value when evaluating an attribute now raises a NilAttributeValueError, instead of an AuthorizationError. We leave it to the caller to decide what to do about it.
|
96
|
+
|
97
|
+
* Changed Authorization::Engine#permit! [Brian Langenfeld]
|
98
|
+
* We now convert incoming privileges to symbols (e.g. 'read' is made equivalent to :read). This ensures the privileges will match those defined in the authorization rules file.
|
99
|
+
* The method now properly infers context when checking against an association (e.g. user.posts). We do this by leveraging ActiveRecord builder method 'new' to instantiate a proper object we can work with.
|
100
|
+
* When testing rules for positive results (via Authorization::Attribute#validate?), we now rescue NilAttributeValueError exceptions, simply causing the rule to return a negative result (instead of barfing).
|
101
|
+
|
102
|
+
* Changed Authorization::ObligationScope#rebuild_join_options! [Brian Langenfeld]
|
103
|
+
* If we're dealing with multiple obligations we have to check (i.e. ones that result in OR'd conditions), we now use :include instead of :joins for our generated scope. This does seem like a kludge, but until ActiveRecord scopes support unions (for checking obligations individually and consolidating the results), we don't have much choice. Something to revisit later, for sure.
|
104
|
+
|
105
|
+
** RELEASE 0.2 (February 2, 2009) **
|
106
|
+
|
107
|
+
* added negative operators: is_not, not_in, does_not_contain [sb]
|
108
|
+
|
109
|
+
* changed user.roles to user.role_symbols to reduce interferance with associations [sb]
|
110
|
+
|
111
|
+
* Ruby 1.9 and Rails 2.3 compatibility [sb]
|
112
|
+
|
113
|
+
* if_permitted_to for has_permission_on blocks for DRYer auth rules [sb]
|
114
|
+
|
115
|
+
* ObligationScope rewrite of query rewriting [Brian Langenfeld]
|
116
|
+
|
117
|
+
* changed exception hierarchy to begin at StandardError [sb]
|
118
|
+
|
119
|
+
* :is_in operator [sb]
|
120
|
+
|
121
|
+
* added has_role? helper [sb]
|
122
|
+
|
123
|
+
* made plugin thread-safe [sb]
|
124
|
+
|
125
|
+
* added maintenance and test helpers [sb]
|
126
|
+
|
127
|
+
* changed default permission denied response to 403 Forbidden [sb]
|
128
|
+
|
129
|
+
* descriptions for titles and roles [sb]
|
130
|
+
|
131
|
+
* fixed for PostgreSQL [Mark Mansour]
|
132
|
+
|
133
|
+
* improved DSL syntax: allow for array of contexts in has_permission_on [sb]
|
134
|
+
|
135
|
+
** RELEASE 0.1 (August 22, 2008) **
|
data/MIT-LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2008 [name of plugin creator]
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.rdoc
ADDED
@@ -0,0 +1,503 @@
|
|
1
|
+
= Declarative Authorization
|
2
|
+
|
3
|
+
The declarative authorization plugin offers an authorization mechanism inspired
|
4
|
+
by _RBAC_. The most notable distinction to other authorization plugins is the
|
5
|
+
declarative approach. That is, authorization rules are not defined
|
6
|
+
programmatically in between business logic but in an authorization configuration.
|
7
|
+
|
8
|
+
With programmatic authorization rules, the developer needs to specify which roles are
|
9
|
+
allowed to access a specific controller action or a part of a view, which is
|
10
|
+
not DRY. With a growing application code base roles' permissions often
|
11
|
+
change and new roles are introduced. Then, at several places of the source code
|
12
|
+
the changes have to be implemented, possibly leading to omissions and thus hard
|
13
|
+
to find errors. In these cases, a declarative approach as offered by decl_auth
|
14
|
+
increases the development and maintenance efficiency.
|
15
|
+
|
16
|
+
|
17
|
+
Plugin features
|
18
|
+
* Authorization at controller action level
|
19
|
+
* Authorization helpers for Views
|
20
|
+
* Authorization at model level
|
21
|
+
* Authorize CRUD (Create, Read, Update, Delete) activities
|
22
|
+
* Query rewriting to automatically only fetch authorized records
|
23
|
+
* DSL for specifying Authorization rules in an authorization configuration
|
24
|
+
|
25
|
+
|
26
|
+
Requirements
|
27
|
+
* An authentication mechanism
|
28
|
+
* User object in Controller#current_user
|
29
|
+
* (For model security) Setting Authorization.current_user
|
30
|
+
* User objects need to respond to a method :role_symbols that returns an
|
31
|
+
array of role symbols
|
32
|
+
See below for installation instructions.
|
33
|
+
|
34
|
+
|
35
|
+
There is a decl_auth screencast by Ryan Bates, nicely introducing the main concepts:
|
36
|
+
http://railscasts.com/episodes/188-declarative-authorization
|
37
|
+
|
38
|
+
|
39
|
+
= Authorization Data Model
|
40
|
+
|
41
|
+
----- App domain ----|-------- Authorization conf ---------|------- App domain ------
|
42
|
+
|
43
|
+
includes includes
|
44
|
+
.--. .---.
|
45
|
+
| v | v
|
46
|
+
.------. can_play .------. has_permission .------------. requires .----------.
|
47
|
+
| User |----------->| Role |----------------->| Permission |<-----------| Activity |
|
48
|
+
'------' * * '------' * * '------------' 1 * '----------'
|
49
|
+
|
|
50
|
+
.-------+------.
|
51
|
+
1 / | 1 \ *
|
52
|
+
.-----------. .---------. .-----------.
|
53
|
+
| Privilege | | Context | | Attribute |
|
54
|
+
'-----------' '---------' '-----------'
|
55
|
+
|
56
|
+
In the application domain, each *User* may be assigned to *Roles* that should
|
57
|
+
define the users' job in the application, such as _Administrator_. On the
|
58
|
+
right-hand side of this diagram, application developers specify which *Permissions*
|
59
|
+
are necessary for users to perform activities, such as calling a controller action,
|
60
|
+
viewing parts of a View or acting on records in the database. Note that
|
61
|
+
Permissions consist of an *Privilege* that is to be performed, such as _read_,
|
62
|
+
and a *Context* in that the Operation takes place, such as _companies_.
|
63
|
+
|
64
|
+
In the authorization configuration, Permissions are assigned to Roles and Role
|
65
|
+
and Permission hierarchies are defined. *Attributes* may be employed to allow
|
66
|
+
authorization according to dynamic information about the context and the
|
67
|
+
current user, e.g. "only allow access on employees that belong to the
|
68
|
+
current user's branch."
|
69
|
+
|
70
|
+
|
71
|
+
= Examples
|
72
|
+
|
73
|
+
A fully functional example application can be found at
|
74
|
+
http://github.com/stffn/decl_auth_demo_app
|
75
|
+
|
76
|
+
Details on the demonstrated methods can be found in the API docs, either
|
77
|
+
generated by yourself or at http://www.tzi.org/~sbartsch/declarative_authorization
|
78
|
+
|
79
|
+
== Controller
|
80
|
+
|
81
|
+
If authentication is in place, there are two ways to enable user-specific
|
82
|
+
access control on controller actions. For resource controllers, which more
|
83
|
+
or less follow the CRUD pattern, +filter_resource_access+ is the simplest
|
84
|
+
approach. It sets up instance variables in before filters and calls
|
85
|
+
filter_access_to with the appropriate parameters to protect the CRUD methods.
|
86
|
+
|
87
|
+
class EmployeesController < ApplicationController
|
88
|
+
filter_resource_access
|
89
|
+
...
|
90
|
+
end
|
91
|
+
|
92
|
+
See Authorization::AuthorizationInController::ClassMethods for options on
|
93
|
+
nested resources and custom member and collection actions.
|
94
|
+
|
95
|
+
If you prefer less magic or your controller has no resemblance with the resource
|
96
|
+
controllers, directly calling filter_access_to may be the better option. Examples
|
97
|
+
are given in the following. E.g. the privilege index users is required for
|
98
|
+
action index. This works as a first default configuration for RESTful
|
99
|
+
controllers, with these privileges easily handled in the authorization
|
100
|
+
configuration, which will be described below.
|
101
|
+
|
102
|
+
class EmployeesController < ApplicationController
|
103
|
+
filter_access_to :all
|
104
|
+
def index
|
105
|
+
...
|
106
|
+
end
|
107
|
+
...
|
108
|
+
end
|
109
|
+
|
110
|
+
When custom actions are added to such a controller, it helps to define more
|
111
|
+
clearly which privileges are the respective requirements. That is when the
|
112
|
+
filter_access_to call may become more verbose:
|
113
|
+
|
114
|
+
class EmployeesController < ApplicationController
|
115
|
+
filter_access_to :all
|
116
|
+
# this one would be included in :all, but :read seems to be
|
117
|
+
# a more suitable privilege than :auto_complete_for_user_name
|
118
|
+
filter_access_to :auto_complete_for_employee_name, :require => :read
|
119
|
+
def auto_complete_for_employee_name
|
120
|
+
...
|
121
|
+
end
|
122
|
+
...
|
123
|
+
end
|
124
|
+
|
125
|
+
For some actions it might be necessary to check certain attributes of the
|
126
|
+
object the action is to be acting on. Then, the object needs to be loaded
|
127
|
+
before the action's access control is evaluated. On the other hand, some actions
|
128
|
+
might prefer the authorization to ignore specific attribute checks as the object is
|
129
|
+
unknown at checking time, so attribute checks and thus automatic loading of
|
130
|
+
objects needs to be enabled explicitly.
|
131
|
+
|
132
|
+
class EmployeesController < ApplicationController
|
133
|
+
filter_access_to :update, :attribute_check => true
|
134
|
+
def update
|
135
|
+
# @employee is already loaded from param[:id] because of :attribute_check
|
136
|
+
end
|
137
|
+
end
|
138
|
+
|
139
|
+
You can provide the needed object through before_filters. This way, you have
|
140
|
+
full control over the object that the conditions are checked against. Just make
|
141
|
+
sure, your before_filters occur before any of the filter_access_to calls.
|
142
|
+
|
143
|
+
class EmployeesController < ApplicationController
|
144
|
+
before_filter :new_employee_from_params, :only => :create
|
145
|
+
before_filter :new_employee, :only => [:index, :new]
|
146
|
+
filter_access_to :all, :attribute_check => true
|
147
|
+
|
148
|
+
def create
|
149
|
+
@employee.save!
|
150
|
+
end
|
151
|
+
|
152
|
+
protected
|
153
|
+
def new_employee_from_params
|
154
|
+
@employee = Employee.new(params[:employee])
|
155
|
+
end
|
156
|
+
end
|
157
|
+
|
158
|
+
If the access is denied, a +permission_denied+ method is called on the
|
159
|
+
current_controller, if defined, and the issue is logged.
|
160
|
+
For further customization of the filters and object loading, have a look at
|
161
|
+
the complete API documentation of filter_access_to in
|
162
|
+
Authorization::AuthorizationInController::ClassMethods.
|
163
|
+
|
164
|
+
|
165
|
+
== Views
|
166
|
+
|
167
|
+
In views, a simple permitted_to? helper makes showing blocks according to the
|
168
|
+
current user's privileges easy:
|
169
|
+
|
170
|
+
<% permitted_to? :create, :employees do %>
|
171
|
+
<%= link_to 'New', new_employee_path %>
|
172
|
+
<% end %>
|
173
|
+
|
174
|
+
Only giving a symbol :employees as context prevents any checks of attributes
|
175
|
+
as there is no object to check against. For example, in case of nested resources
|
176
|
+
a new object may come in handy:
|
177
|
+
|
178
|
+
<% permitted_to? :create, Branch.new(:company => @company) do
|
179
|
+
# or @company.branches.new
|
180
|
+
# or even @company.branches %>
|
181
|
+
<%= link_to 'New', new_company_branch_path(@company) %>
|
182
|
+
<% end %>
|
183
|
+
|
184
|
+
Lists are straight-forward:
|
185
|
+
|
186
|
+
<% for employee in @employees %>
|
187
|
+
<%= link_to 'Edit', edit_employee_path(employee) if permitted_to? :update, employee %>
|
188
|
+
<% end %>
|
189
|
+
|
190
|
+
See also Authorization::AuthorizationHelper.
|
191
|
+
|
192
|
+
|
193
|
+
== Models
|
194
|
+
|
195
|
+
There are two destinct features for model security built into this plugin:
|
196
|
+
authorizing CRUD operations on objects as well as query rewriting to limit
|
197
|
+
results according to certain privileges.
|
198
|
+
|
199
|
+
See also Authorization::AuthorizationInModel.
|
200
|
+
|
201
|
+
=== Model security for CRUD opterations
|
202
|
+
To activate model security, all it takes is an explicit enabling for each
|
203
|
+
model that model security should be enforced on, i.e.
|
204
|
+
|
205
|
+
class Employee < ActiveRecord::Base
|
206
|
+
using_access_control
|
207
|
+
...
|
208
|
+
end
|
209
|
+
|
210
|
+
Thus,
|
211
|
+
Employee.create(...)
|
212
|
+
fails, if the current user is not allowed to :create :employees according
|
213
|
+
to the authorization rules. For the application to find out about what
|
214
|
+
happened if an operation is denied, the filters throw
|
215
|
+
Authorization::NotAuthorized exceptions.
|
216
|
+
|
217
|
+
As access control on read are costly, with possibly lots of objects being
|
218
|
+
loaded at a time in one query, checks on read need to be actived explicitly by
|
219
|
+
adding the :include_read option.
|
220
|
+
|
221
|
+
=== Query rewriting through named scopes
|
222
|
+
When retrieving large sets of records from databases, any authorization needs
|
223
|
+
to be integrated into the query in order to prevent inefficient filtering
|
224
|
+
afterwards and to use LIMIT and OFFSET in SQL statements. To keep authorization
|
225
|
+
rules out of the source code, this plugin offers query rewriting mechanisms
|
226
|
+
through named scopes. Thus,
|
227
|
+
|
228
|
+
Employee.with_permissions_to(:read)
|
229
|
+
|
230
|
+
returns all employee records that the current user is authorized to read. In
|
231
|
+
addition, just like normal named scopes, query rewriting may be chained with
|
232
|
+
the usual find method:
|
233
|
+
|
234
|
+
Employee.with_permissions_to(:read).find(:all, :conditions => ...)
|
235
|
+
|
236
|
+
If the current user is completely missing the permissions, an
|
237
|
+
Authorization::NotAuthorized exception is raised. Through
|
238
|
+
Model.obligation_conditions, application developers may retrieve
|
239
|
+
the conditions for manual rewrites.
|
240
|
+
|
241
|
+
|
242
|
+
== Authorization Rules
|
243
|
+
|
244
|
+
Authorization rules are defined in config/authorization_rules.rb
|
245
|
+
(Or redefine rules files path via +Authorization::AUTH_RULE_FILES+). E.g.
|
246
|
+
|
247
|
+
authorization do
|
248
|
+
role :admin do
|
249
|
+
has_permission_on :employees, :to => [:create, :read, :update, :delete]
|
250
|
+
end
|
251
|
+
end
|
252
|
+
|
253
|
+
There is a default role :+guest+ that is used if a request is not associated
|
254
|
+
with any user or with a user without any roles. So, if your application has
|
255
|
+
public pages, :+guest+ can be used to allow access for users that are not
|
256
|
+
logged in. All other roles are application defined and need to be associated
|
257
|
+
with users by the application.
|
258
|
+
|
259
|
+
Privileges, such as :create, may be put into hierarchies to simplify
|
260
|
+
maintenance. So the example above has the same meaning as
|
261
|
+
|
262
|
+
authorization do
|
263
|
+
role :admin do
|
264
|
+
has_permission_on :employees, :to => :manage
|
265
|
+
end
|
266
|
+
end
|
267
|
+
|
268
|
+
privileges do
|
269
|
+
privilege :manage do
|
270
|
+
includes :create, :read, :update, :delete
|
271
|
+
end
|
272
|
+
end
|
273
|
+
|
274
|
+
Privilege hierarchies may be context-specific, e.g. applicable to :employees.
|
275
|
+
|
276
|
+
privileges do
|
277
|
+
privilege :manage, :employees, :includes => :increase_salary
|
278
|
+
end
|
279
|
+
|
280
|
+
For more complex use cases, authorizations need to be based on attributes. E.g.
|
281
|
+
if a branch admin should manage only employees of his branch (see
|
282
|
+
Authorization::Reader in the API docs for a full list of available operators):
|
283
|
+
|
284
|
+
authorization do
|
285
|
+
role :branch_admin do
|
286
|
+
has_permission_on :employees do
|
287
|
+
to :manage
|
288
|
+
# user refers to the current_user when evaluating
|
289
|
+
if_attribute :branch => is {user.branch}
|
290
|
+
end
|
291
|
+
end
|
292
|
+
end
|
293
|
+
|
294
|
+
To reduce redundancy in has_permission_on blocks, a rule may depend on
|
295
|
+
permissions on associated objects:
|
296
|
+
|
297
|
+
authorization do
|
298
|
+
role :branch_admin do
|
299
|
+
has_permission_on :branches, :to => :manage do
|
300
|
+
if_attribute :managers => contains {user}
|
301
|
+
end
|
302
|
+
|
303
|
+
has_permission_on :employees, :to => :manage do
|
304
|
+
if_permitted_to :manage, :branch
|
305
|
+
# instead of
|
306
|
+
#if_attribute :branch => {:managers => contains {user}}
|
307
|
+
end
|
308
|
+
end
|
309
|
+
end
|
310
|
+
|
311
|
+
Lastly, not only privileges may be organized in a hierarchy but roles as well.
|
312
|
+
Here, project manager inherit the permissions of employees.
|
313
|
+
|
314
|
+
role :project_manager do
|
315
|
+
includes :employee
|
316
|
+
end
|
317
|
+
|
318
|
+
See also Authorization::Reader.
|
319
|
+
|
320
|
+
== Testing
|
321
|
+
|
322
|
+
declarative_authorization provides a few helpers to ease the testing with
|
323
|
+
authorization in mind.
|
324
|
+
|
325
|
+
In your test_helper.rb, to enable the helpers add
|
326
|
+
|
327
|
+
require 'declarative_authorization/maintenance'
|
328
|
+
|
329
|
+
class Test::Unit::TestCase
|
330
|
+
include Authorization::TestHelper
|
331
|
+
...
|
332
|
+
end
|
333
|
+
|
334
|
+
Now, in unit tests, you may deactivate authorization if needed e.g. for test
|
335
|
+
setup and assume certain identities for tests:
|
336
|
+
|
337
|
+
class EmployeeTest < ActiveSupport::TestCase
|
338
|
+
def test_should_read
|
339
|
+
without_access_control do
|
340
|
+
Employee.create(...)
|
341
|
+
end
|
342
|
+
assert_nothing_raised do
|
343
|
+
with_user(admin) do
|
344
|
+
Employee.find(:first)
|
345
|
+
end
|
346
|
+
end
|
347
|
+
end
|
348
|
+
end
|
349
|
+
|
350
|
+
In functional tests, get, posts, etc. may be tested in the name of certain users:
|
351
|
+
|
352
|
+
get_with admin, :index
|
353
|
+
post_with admin, :update, :employee => {...}
|
354
|
+
|
355
|
+
See Authorization::TestHelper for more information.
|
356
|
+
|
357
|
+
|
358
|
+
= Installation of declarative_authorization
|
359
|
+
|
360
|
+
One of three options to install the plugin:
|
361
|
+
* Install by Gem: Add to your environment.rb in the initializer block:
|
362
|
+
config.gem "declarative_authorization"
|
363
|
+
Note: you need gemcutter support in place, i.e. call
|
364
|
+
gem install gemcutter
|
365
|
+
gem tumble
|
366
|
+
And call from your application's root directory
|
367
|
+
rake gems:install
|
368
|
+
* Alternatively, to install from github, execute in your application's root directory
|
369
|
+
cd vendor/plugins && git clone git://github.com/stffn/declarative_authorization.git
|
370
|
+
* Or, download one of the released versions from Github at
|
371
|
+
http://github.com/stffn/declarative_authorization/downloads
|
372
|
+
|
373
|
+
Then,
|
374
|
+
* provide the requirements as noted below,
|
375
|
+
* create a basic config/authorization_rules.rb--you might want to take the
|
376
|
+
provided example authorization_rules.dist.rb in the plugin root as a starting
|
377
|
+
point,
|
378
|
+
* add +filter_access_to+, +permitted_to+? and model security as needed.
|
379
|
+
|
380
|
+
== Providing the Plugin's Requirements
|
381
|
+
The requirements are
|
382
|
+
* Rails >= 2.2, including 3 and Ruby >= 1.8.6, including 1.9
|
383
|
+
* An authentication mechanism
|
384
|
+
* A user object returned by Controller#current_user
|
385
|
+
* An array of role symbols returned by User#role_symbols
|
386
|
+
* (For model security) Setting Authorization.current_user to the request's user
|
387
|
+
|
388
|
+
Of the various ways to provide these requirements, here is one way employing
|
389
|
+
restful_authentication.
|
390
|
+
|
391
|
+
* Install restful_authentication
|
392
|
+
cd vendor/plugins && git clone git://github.com/technoweenie/restful-authentication.git restful_authentication
|
393
|
+
cd ../.. && ruby script/generate authenticated user sessions
|
394
|
+
* Move "include AuthenticatedSystem" to ApplicationController
|
395
|
+
* Add +filter_access_to+ calls as described above.
|
396
|
+
* If you'd like to use model security, add a before_filter that sets the user
|
397
|
+
globally to your ApplicationController. This is thread-safe.
|
398
|
+
before_filter :set_current_user
|
399
|
+
protected
|
400
|
+
def set_current_user
|
401
|
+
Authorization.current_user = current_user
|
402
|
+
end
|
403
|
+
|
404
|
+
* Add roles field to the User model through a :+has_many+ association
|
405
|
+
(this is just one possible approach; you could just as easily use
|
406
|
+
:+has_many+ :+through+ or a serialized roles array):
|
407
|
+
* create a migration for table roles
|
408
|
+
class CreateRoles < ActiveRecord::Migration
|
409
|
+
def self.up
|
410
|
+
create_table "roles" do |t|
|
411
|
+
t.column :title, :string
|
412
|
+
t.references :user
|
413
|
+
end
|
414
|
+
end
|
415
|
+
|
416
|
+
def self.down
|
417
|
+
drop_table "roles"
|
418
|
+
end
|
419
|
+
end
|
420
|
+
|
421
|
+
* create a model Role,
|
422
|
+
class Role < ActiveRecord::Base
|
423
|
+
belongs_to :user
|
424
|
+
end
|
425
|
+
|
426
|
+
* add +has_many+ :+roles+ to the User model and a roles method that returns the roles
|
427
|
+
as an Array of Symbols, e.g.
|
428
|
+
class User < ActiveRecord::Base
|
429
|
+
has_many :roles
|
430
|
+
def role_symbols
|
431
|
+
(roles || []).map {|r| r.title.to_sym}
|
432
|
+
end
|
433
|
+
end
|
434
|
+
|
435
|
+
* add roles to your User objects using e.g.
|
436
|
+
user.roles.create(:title => "admin")
|
437
|
+
|
438
|
+
Note: If you choose to generate an Account model for restful_authentication
|
439
|
+
instead of a User model as described above, you have to customize the
|
440
|
+
examples and create a ApplicationController#current_user method.
|
441
|
+
|
442
|
+
|
443
|
+
== Debugging Authorization
|
444
|
+
|
445
|
+
Currently, the main means of debugging authorization decisions is logging and
|
446
|
+
exceptions. Denied access to actions is logged to +warn+ or +info+, including
|
447
|
+
some hints about what went wrong.
|
448
|
+
|
449
|
+
All bang methods throw exceptions which may be used to retrieve more
|
450
|
+
information about a denied access than a Boolean value.
|
451
|
+
|
452
|
+
|
453
|
+
== Authorization Development Support
|
454
|
+
|
455
|
+
If your authorization rules become more complex, you might be glad to use
|
456
|
+
the authorization rules browser that comes with declarative_authorization.
|
457
|
+
It has a syntax-highlighted and a graphical view with filtering of the current
|
458
|
+
authorization rules.
|
459
|
+
|
460
|
+
By default, it will only be available in development mode. To use it, add
|
461
|
+
the following lines to your authorization_rules.rb for the appropriate role:
|
462
|
+
|
463
|
+
has_permission_on :authorization_rules, :to => :read
|
464
|
+
|
465
|
+
Then, point your browser to
|
466
|
+
http://localhost/authorization_rules
|
467
|
+
|
468
|
+
The browser needs Rails 2.3 (for Engine support). The graphical view requires
|
469
|
+
Graphviz (which e.g. can be installed through the graphviz package under Debian
|
470
|
+
and Ubuntu) and has only been tested under Linux. Note: for Change Support
|
471
|
+
you'll need to have a User#login method that returns a non-ambiguous user
|
472
|
+
name for identification.
|
473
|
+
|
474
|
+
|
475
|
+
= Help and Contact
|
476
|
+
|
477
|
+
We have an issue tracker[http://github.com/stffn/declarative_authorization/issues]
|
478
|
+
for bugs and feature requests as well as a
|
479
|
+
Google Group[http://groups.google.com/group/declarative_authorization] for
|
480
|
+
discussions on the usage of the plugin. You are very welcome to contribute.
|
481
|
+
Just fork the git repository and create a new issue, send a pull request or
|
482
|
+
contact me personally.
|
483
|
+
|
484
|
+
Maintained by
|
485
|
+
|
486
|
+
Steffen Bartsch
|
487
|
+
TZI, Universität Bremen, Germany
|
488
|
+
sbartsch at tzi.org
|
489
|
+
|
490
|
+
|
491
|
+
= Contributors
|
492
|
+
|
493
|
+
Thanks to John Joseph Bachir, Eike Carls, Kai Chen, Erik Dahlstrand,
|
494
|
+
Jeroen van Dijk, Sebastian Dyck, Jeremy Friesen, Daniel Kristensen, Brian Langenfeld,
|
495
|
+
Georg Ledermann, Geoff Longman, Olly Lylo, Mark Mansour, Thomas Maurer,
|
496
|
+
Mike Vincent
|
497
|
+
|
498
|
+
|
499
|
+
= Licence
|
500
|
+
|
501
|
+
Copyright (c) 2008 Steffen Bartsch, TZI, Universität Bremen, Germany
|
502
|
+
released under the MIT license
|
503
|
+
|