ya_acl¶ ↑

<img src=“https://secure.travis-ci.org/kaize/ya_acl.png” alt=“Build Status” /> <img src=“https://coveralls.io/repos/kaize/ya_acl/badge.png?branch=master” alt=“Coverage” />

Ya_Acl - access control list (ACL) implementation for your Ruby application.

Ya_Acl provides a standalone object through which all checks are made. This means it is not tied to any framework. Note that this guide will show you only one possible way to use this component.

Installation¶ ↑

gem install ya_acl

Keywords¶ ↑

Resource - object to restrict access to. Privilege - action on the resource. Role - object, which can request for an access to a resource.

Role(s) request for an access to the resource privileges. For example, resource “user” can have a privilege “create”.

Initial conditions¶ ↑

• By default, everything is forbidden. Further you will only be able to grant access to a particular resource, not restrict it.

• All resources must be added to the acl (otherwise you will get an exception).

Key features¶ ↑

Asserts - runtime checks, e.g. “whether logged in user is the owner of this object”. Checks can be assigned to specific roles of the current privilege, not just “on the privilege”. Owning multiple roles. If at least one of the user roles has access to the resource privilege, access granted. Role with global access to all resources. Passed as an argument to the ‘Builder::resources` method. Roles inheritance. That is, we could define a role that will automatically get all resource privileges.

Access check algorithm¶ ↑

1. If none of the passed roles have access to resource privilege - access denied.

2. If any, for each role we run asserts. If at least one role passed these checks - access granted.

Workflow¶ ↑

First, initialize acl object by creating the config file (you could use the structure sample below). It should be loaded while your application starts. Although, in development environment, you may want it to be loaded before each request.

YaAcl::Builder.build do
  roles do # Roles
    role :admin
    role :editor
    role :operator
  end

  asserts do # Checks
    assert :assert_name, [:current_user_id, :another_user_id] do
      current_user_id == another_user_id
    end

    assert :another_assert_name, [:current_user_id, :another_user_id] do
      current_user_id != another_user_id
    end
  end

  resources :admin do # Resources and role with admin privileges
    resource 'UserController', [:editor] do # Resource and roles, which have access to the all privileges of a given resource
      privilege :index, [:operator] # allowed for :admin, :editor, :operator
      privilege :edit # allowed for :admin, :editor
      privilege :new do
        assert :assert_name, [:editor] # This check will be called for role :editor
        assert :another_assert_name # This check will be called for :admin and :editor roles
      end
    end
  end
end

After that, acl object becomes accessible via YaAcl::Acl.instance.

acl = YaAcl::Acl.instance

acl.allow?('UserController', :index, [:editor, :opeartor]) # true
acl.allow?('UserController', :edit, [:editor, :opeartor]) # true
acl.allow?('UserController', :edit, [:opeartor]) # false
acl.allow?('UserController', :new, [:admin], :current_user_id => 1, :another_user_id => 1) # true
acl.allow?('UserController', :new, [:editor], :current_user_id => 1, :another_user_id => 2) # false

acl#check - returns YaAcl::Result object
acl#check! - returns true or throws an exception