The ActiveAclPlus plugin implements a flexible, fast and easy to use generic access control system.
ActiveAclPlus is released under the LGPL (Gnu Lesser General Public License) - see the included LICENSE file, too.
-
ease of use - uses polymorphic collections for associations.
-
advanced design - uses SQL nested sets for inheritance, thus only needs a single DB query to decide on a permission request.
-
scalable - there are no real benchmarks yet. But the system design is based on phpgacl.sourceforge.net, adding object orientation, polymorphism and two levels of caching. PhpGacl claims “A real-world working version with many added layers of complexity supports over 60,000 Accounts, 200 Groups and 300 ACO’s.” Tests on my dev notebook show 10 - 30 times performance improvements compared to active_rbac.
-
caching - uses instance caching and optionally stores permission results in memcached using timeouts.
-
flexible - grants simple (2D, like
current_user.has_permission?(User::LOGIN)) and object level (3D, likeadmin.has_permission?(Forum::ADMIN, :on => team_forum)) permissions. Can assign and request permissions to and from every ActiveRecord model. No “hardcoded” permissions - all permissions can be assigned at runtime. -
grouping - permissions can be inherited at target and requester side through groups. Every model implementing an SQL nested set tree may be used as a group.
-
ControllerAction model loader: It maps controller actions to the DB so they can be used in permission assignment. The access object is available via calling
current_actionon the controller. -
exchangeable DB interface: ActiveRecord and direct MySQL adapter available
-
supports namespaced models and single table inheritance (STI)
-
At present only one grouping type per model is supported. This could be changed on request but I don’t see a use case for it yet.
-
The DBMS has to support subselects. So PostgreSQL, Sqllite and MySQL 5 work, but MySQL 4 does not.
ActiveAclPlus uses the has_many_polymorphs plugin. Make shure you’ve got a recent version, old versions have bugs affecting active_acl_plus. !!Be sure you have the paches for 2.1, see: rubyforge.org/forum/forum.php?thread_id=26041&forum_id=16450
./script/plugin install git://github.com/popel/active_acl_plus.git
or
sudo gem install activeaclplus
or from a github repository.
If you want to use grouped access objects you should install some kind of nested_set plugin (awesome_nested_set,better_nested_set,…).
The ActiveAclPlus system consists of access objects, which can be organized by access groups, that request privileges on each other. Allowing or denying access to a privilege is controlled by ACL (access control list entry) objects. Access objects and access groups can be instances of arbitrary ActiveRecord model classes enhanced by acts_as_access_object and acts_as_access_group. They are associated to ACL entries via polymorphic associations.
These are basically requesters and targets in the permission system, as for example a User or a Forum model object. In this case a user could act as a requester (“do I have privilege Y?”) or target (“does access object X have privilege Y on me?”). A Forum would most certainly be only used as a target, but all access objects can theoretically be used as both requesters and targets. Access objects use the acts_as_access_object macro inside their definition. This registers the model with the ACL system and enhances it with methods like has_privilege?.
See: ActiveAcl::Acts::AccessObject::ClassMethods, ActiveAcl::Acts::AccessObject::InstanceMethods, ActiveAcl::Acts::AccessObject::SingletonMethods, ActiveAcl::Acts::Grant
Every access object class can specify an association that is used as the “grouping type” to it. So User may declare has_and_belongs_to_many :user_groups and use acts_as_access_object :grouped_by => :user_groups. You can use
a has_and_belongs_to_many or a belongs_to association for this. Common mapping attributes (:join_table, :foreign_key etc.) are supported.
The access group model needs to implement a tree with nested set semantics having a “left” and “right” column, e.g. by using the built-in acts_as_nested_set or the much more recommended acts_as_betted_nested_set plugin. Groups are declared with acts_as_access_group.
Groups may be used to specify inheritance hierarchies for permissions. So you could have a ‘registered users’ group as a subgroup of the ‘users’ group and assign the privilege to log in to this group via an ACL entry. Every user belonging to this group will now be granted the privilege to log in. Then you could add a subgroup to registerd users, ‘banned users’, and deny the log in privilege for this group. Every user added to this group would now be unable to log in, regardless of beeing in ‘registered users’ or not, as ‘banned users’ would override the permission settings of ‘registered users’.
A privilege object is an object for the thing we wish to define a permission for. So User::LOGIN could be a privilege object for checking a users permission to log in, while Forum::ADMIN might define administration rights on a forum.
A privilege object itself is little more than it’s name and id and is usually bound to a constant inside the application, as it is not expected to change at runtime. Privileges are usually created by the developer in the source code and not in the admin frontend, as creating new privilege objects that have no meaning (by code that checks for them) would be pointless.
ACL entries are the glue between all these objects, defining which requesters and requester groups have access to which privileges, optionally defining target objects and target groups as well. ACL entries are organized by ACL sections, for better overview in the admin screens.
“No access defined” for a privilege evaluates to “deny”. This may be overriden by an explicit “allow” or “deny”. Privileges are inherited in requestor and target groups, this means you can override them in subgroups again. Privileges directly assigned to an object always supercede those assigned to groups.
We want all registered users to be able to log in. We create the User model, the UserGroup model and the User::LOGIN privilege object as described above. Then we create a new ACL entry, set ‘allow’ to true, add the “registered users” group as requester group, User::LOGIN as privilege and we are done. Every user assigned to “registered users” or a subgroup of it will now be granted access by calling my_user.has_privilege?(User::LOGIN).
class UserGroup < ActiveRecord::Base acts_as_nested_set acts_as_access_group has_and_belongs_to_many :users end class User < ActiveRecord::Base has_and_belongs_to_many :user_groups acts_as_access_object :grouped_by => :user_groups privilege_const_set('LOGIN') end # assume 'registered_users' exists and users 'john' and 'dr_evil' are members of it but 'anonymous' is not. registered_users = UserGroup.find_by_name('registered_users')
the hard way:
acl = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.create(:description => 'users') acl.allow = true # true is default acl.privileges << User::LOGIN acl.iname="login" acl.save acl.requester_groups << registered_users
or much easier:
registered_users.grant_privilege!(User::LOGIN,:section_name => 'users',:acl_name => 'login') john.has_privilege?(User::LOGIN) #=> true dr_evil.has_privilege?(User::LOGIN) #=> true anonymous.has_privilege?(User::LOGIN) #=> false
We want to ban specific users from our site. We create another ACL entry, assign the User::LOGIN privilege object, set ‘allow’ to false and then assign these users as requesters to the ACL entry. The direct permission assignment on the objects overrides the ‘allow login’ ACL entry from above.
ban_users = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.find_by_description('users') ban_users.allow = false ban_users.privileges << User::LOGIN ban_users.requesters << dr_evil ban_users.save john.has_privilege?(User::LOGIN) #=> true dr_evil.has_privilege?(User::LOGIN) #=> false
We want to assign forum permissions. We have several privileges (Forum::ADMIN, Forum::READ, Forum::POST etc.), the afore mentioned User and UserGroup models as well as a Forum and a Category model for grouping the forums.
If we want to check if a certain user may read in a certain forum, it is not sufficient to check test_user.has_privilege?(Forum::READ) as the target object - in this case a forum - is needed to make a decision. The code to do the check is like test_user.has_privilege?(Forum::READ, :on => teamforum).
To make this work you create a new ACL entry, add Forum::POST and Forum::READ as privileges, set ‘allow’ to true, add the registered users group as a requester group and the public forums category as a target group to the acl. Now every user belonging to the registered users group or a subgroup of it gains post and read privileges on all forums of the public forums category or a subcategory of it.
# Assuming setup as in the above examples class Category < ActiveRecord::Base acts_as_nested_set acts_as_access_group has_many :forums end class Forum < ActiveRecord::Base belongs_to :category acts_as_access_object :grouped_by => :category privilege_const_set 'READ' => 'read postings in forum', 'POST' => 'reply to threads in a forum' end # assume there is a forum 'speakers corner' assigned to the category 'public'. acl = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.create(:description => 'forum') acl.allow = true acl.requester_groups << registered_users acl.target_groups << Category.find_by_name('public') acl.privileges << Forum::READ acl.privileges << Forum::POST acl.save speakers = Forum.find_by_name('speakers corner') john.has_privilege?(Forum::READ, :on => speakers) #=> true john.has_privilege?(Forum::POST, :on => speakers) #=> true anonymous.has_privilege?(Forum::READ, :on => speakers) #=> false
Do not create ACL entries that are on different branches of the inheritance hierarchy and have allow/deny set differently on the same privilege objects. This way it’s impossible to tell which permission should take precedence. At present this is by creation date, later entries superceding older ones, but this is most certainly not what you want.
Defining permissions on controller actions (like “may user x execute AdminController.list ?”) is quite a common case but we are facing a problem here: Controller actions have no corresponding DB models so permissions on them can’t be easily defined.
ActiveAclPlus solves this by adding a ControllerAction and ControllerGroup model. For every public controller method (=action) there is one ControllerAction object in the DB.
On application startup, the plugin loader checks all controller files in app/controllers and loads or creates a ControllerAction object for every action it finds. These objects get cached in a hash in the ActiveAclPlus module. Every controller now has a method current_action that looks up and returns the access object for the current action, so it can be used for access checks like current_user.has_privilege?(ActiveAcl::ControllerAction::EXECUTE, :on => current_action).
This works nicely for before_filters with authorization checks.
A word on the load mechanism: If the action has no corresponding DB entry (it’s looked up on method creation by controller and action name) the loader searches for a controller group with the same name as the controller. If it is found, the action is created and assigned to this group. Else the controller group is created as a subgroup to the “unassigned controller actions” group (this name can be changed in the options) and the unassigned action is added to the controller group.
So you are free on how to organize your controllers. Maybe create an admin group and a public group and move controllers as a subgroup inside them?
The plugin provides two levels of caching. The instance cache is a hash inside the access object. The object first tries to serve a permission request from the instance cache. If it is not found and a simple permission is requested, the query fetches all simple permissions (2D) of the object and puts them in the instance cache. The reason for this is that there is no noticable speed penalty in fetching all 2D permissions at once compared to fetching only one, so this will save time and DB IO later on. Complex 3D queries are fetched independently and also saved to the instance cache. The instance cache lives inside the access object, so it has it’s lifetime, too - which in rails usually is no more than a single request.
The second level cache tries to overcome this limitation by putting the instance cache of an access object in an external cache. It tries to get the instance cache from there if it is not set, and sets it if it was changed. The only real implementation for now is with the memcache daemon. The second level cache uses a timeout (which can be defined in the options) to expire the cached permissions.
Instance and second level cache can be expired explicitly by calling active_acl_clear_cache! on the access object. Calling reload on the object also purges the caches.
See ActiveAcl::Cache::MemcacheAdapter on how to set it up.
The plugin includes a load_files_from filenames function. It can be used to preload source files (and therefore the classes in it) from an application path and should be used from environment.rb.
load_files_from("#{RAILS_ROOT}/app/controllers/**/[^.]*.rb") load_files_from("#{RAILS_ROOT}/app/models/**/[^.]*.rb")
will load all models and controllers inside these folders and their subfolders. This way you can be shure they are registered with the ACL system at rails boot time - else they will be registered when they are called for the first time. This means that new controllers will not show up in the admin screens until they were accessed if not using the preloader.
ActiveAcl::OPTIONS is an array that can be used to override various options for the system by setting the values in environment.rb. ActiveAcl::DEFAULT_OPTIONS is as follows:
DEFAULT_OPTIONS = { :acl_sections_table => 'acl_sections', :acls_privileges_table => 'acls_privileges', :acls_table => 'acls', :privileges_table => 'privileges', :requester_links_table => 'requester_links', :target_links_table => 'target_links', :requester_group_links_table => 'requester_group_links', :target_group_links_table => 'target_group_links', :controller_actions_table => 'controller_actions', :controller_groups_table => 'controller_groups', :controllers_group_name => 'unassigned_controller_actions', # the name of the base group # that newly created controller groups get assigned to :controller_group_name_suffix => '_controller', # name suffix for generated controller groups :cache_permission_timeout => 10, # timeout in seconds for the second level cache :db => ActiveAcl::DB::ActiveRecordAdapter, # the DB Adapter to use :cache => ActiveAcl::Cache::NoCacheAdapter, # the Cache Adapter to use }
Not anymore, sorry. I’m using RSpec for testing. A repository is/will be setup at github.com/popel/active_acl_plus_rspec/tree/master . Check it out and move it to “spec”. Run
rake spec
-
Gregor Melhorn implemented this and maintained it up to Version 0.2.1. Thanks for releasing this!
-
Evan for writing that great polymorph plugin and beeing so kind to add namespace and tablename support on Gregor’s request.
-
ReinH and markmeves for great support and suggestions at the rubyonrails channel on freenode.org.
-
phpgacl.sourceforge.net as a great source of inspiration
-
Obrie for writing plugin_migrations and loaded_plugins and also very nice support when Gregor got stuck with using them.
in no particular order, just a reminder…
-
add materialized_tree support
-
use Moneta as key/value store
-
direct PostgreSQL interface
-
example on how to integrate with authentication
-
example on controller actions
-
error checking for conflicting ACL entries
-
get all permissions for a requester within a section
-
get all permissions of a requester (with one query)
-
get all permissions of a requester on a target (with one query)
-
get all requester with a given privilege on a target (one query)
-
get all targets on which a requester has a certain privilege (one query)