Extremaly fast, flexible and intuitive access control mechanism, powered by fast key value stores like Redis.
You can simple install ACLatraz via rubygems:
sudo gem install aclatraz
Before you'll start play with access controll in your apps you have to correctly configure datastore for permissions (at this moment ACLatraz is only supporting Redis database as storage). Redis datastore configuration looks very simple:
Aclatraz.init :redis, "redis://localhost:6379/0"
Remember that using Redis, you should specify database dedicated only for ACLatraz.
Suspects are objects which we can assign specific permissions. There is only one condition which object have to meet to be suspect - it must have the #id method which returns an unique identifier after which we will be able to reference this object. To enable suspect behaviour you have to include the Aclatraz::Suspect module to specified class, eg:
class Account < ActiveRecord::Base include Aclatraz::Suspect end
Now your suspect have few methods which will helps you manage it permissions.
ACLatraz distinguishes between three types of roles:
global: simple roles, which are most commonly assigned to many users. We can say that they are kind of groups. Global roles are eg. guest, admin, customer.
class-related: roles that affects management of a particular class. Example of this kind of role can be manager of Pages, admin of Products, etc.
object-related: roles that affects management of an object. For example author of specified page, owner of specified product, etc.
Now there is two ways for managing roles. You can use #roles or semanticaly look like #is and #is_not proxies.
To add given role you can use #assign method from #roles proxy or use semantic shortcuts. Semantic shortcut have to ends with “!”, and can have optional suffixes: _on, _of, _at, _for, _in, _by. Take a look at the following examples to get everything to be clear:
@account.roles.assign(:admin) # or ... @account.is.admin!
…will assign global admin role to the account.
@account.roles.assign(:responsible, Foo) # or... @account.is.responsible_for!(Foo)
…will assign to the account responsible role related with Foo class.
@account.roles.assign(:author, Page.find(15)) # or... @account.is.author_of!(Page.find(15))
…will assign to the account author role related with given Page object.
Using #roles proxy you can call <tt>#has?</t> method on it, eg:
@account.roles.has?(:admin) # => true @account.roles.has?(:responsible, Foo) # => true @account.roles.has?(:author, Page.find(15) # => true
With semantic shortcuts your method name have to ends with “?” and can contain any of suffixes listed above, eg:
@account.is.admin? # => true @account.is.responsible_for?(Foo) # => true @account.is.author_of?(Page.find(15)) # => true
Few more examples with semantic negation:
@account.is_not.admin? # => false @account.is_not.responsible_for?(Foo) # => false
You can also check permissions using nice block-style syntax. The code inside the block will be executed only when object has given role. An quick example:
@account.is.admin? do # only admins can se this... end
To unassign given role from object use #delete method from #roles, eg:
@account.roles.delete(:admin) @account.roles.delete(:responsible, Foo)
Another way is to use semantic negation, where method name have to ends with “!” and can contain one of allowed suffixes, eg:
To enable access control in your for your objects you have to include to it the Aclatraz::Guard module. This module provides methods for defining and checking permissions of an suspected object. Take a look for this basic example:
class Foo include Aclatraz::Guard suspects :account do deny all # notice that it's a method, not symbol allow :admin end end
The #suspects block is passing one argument - suspected object. When there is symbol given, like in example above, then will treat #account instance method result as suspected object. When you will use string, eg:
suspects "account" do # or suspects "@account" do ...
… it will treat @account instance variable as suspect. You can also specify suspected object directly, eg:
account = Account.find(1) suspects account do # ...
Setting up permissions
As you probably noticed, there is two methods responsible for access control, namely #allow and #deny. As its argument you can pass simple name of role or permission statement, eg:
allow :admin deny :guest allow :responsible_for => Foo allow :author_of => "@page"
Like you see, you can easy specify access for each kind of role. The object-related permissions behaviour is similar to #suspects method. When given related object is string then applies permissions for an instance variable, when symbol then applies it for instance method, otherwise directly for given object.
In your access control block you can specify separate action with its own permissions, eg:
suspects :account do deny all allow :admin action :manage do allow :responsible_for => Foo end action :delete do allow :author_of => "@page" end end
Obviously all actions inherits all permissions from main block.
The Aclatraz::Guards module provides #guard! method for checking permissions. When suspected object don't have any of allowed permissions or have any of defnied then it will raise the Aclatraz::AccessDenied error. Here's an comprehensive example:
class Foo suspects "@account" do deny all allow :admin action :foo allow :foo end action :bar allow :bar deny :admin end end def initialize(account) @account = account end def simple guard! # only for accounts with :admin role... end def foo guard!(:foo) # only for accounts with :admin or :foo role... end def bar guard!(:bar) # only for accounts with :bar role... end def foobar guard!(:foo, :bar) # only for accounts with :foo or :bar, and mandatory without :admin role... end end
There is also a very nice feature. You can define additional permissions directly in #guard! block, eg:
def foo guard! do allow :foo deny :bar end # ... end
ACLatraz access control supports inheritance. It means that when you define your ACL in parent class it will be applied also for all child classes. Obviously in each child class you can freely modify permissions. Here's an example:
class Foo suspects :account do deny all allow :admin end end class Bar < Foo suspects do # notice, that in child class don't have to again specify suspect... allow :foobar end end class Spam < Foo suspects :egg do # but of course you can specify different suspect than in parent class... end end
If you prefer you can use aliases: #access_control instead of #suspects and #authorize! instead of #guard!.
Note on Patches/Pull Requests
Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.
Copyright © 2010 Kriss 'nu7hatch' Kowalik. See LICENSE for details.