ACLatraz
Extremaly fast, flexible and intuitive access control mechanism, powered by fast key value stores like Redis.
Installation
You can simple install ACLatraz via rubygems:
sudo gem install aclatraz
Configuration
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
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.
Managing roles
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 ofProducts
, 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.
Assigning
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.(Page.find(15))
…will assign to the account author role related with given Page
object.
Checking
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.(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
Deleting
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:
@account.is_not.admin!
@account.is_not.(Page.find(15))
Guards
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.
Actions
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.
Authorizing
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
Inheritance
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
Aliases
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
Copyright © 2010 Kriss ‘nu7hatch’ Kowalik. See LICENSE for details.