This is an old revision of the document!


Main Author: Ravindra de Silva Contributors: …

Introduction

This is the authorization library, therefore you should use this API to add and check permissions.

There are two includes:

  1. acl_api.inc This includes all the API functions you need at the moment
  2. acl.inc This file contains functions that interact with phpgacl library and rarely you need to use these functions.

In this tutorial only functions in acl_api.inc are explained. For each function a brief explanation of how they correspond to phpgacl is included for phpgacl users.

note : “shn” stands for “Sahana”

ACL Design ACL Example

ACl API

shn_acl_add_module($module,$desc)

adds a module ,e.g “OR” this is an AXO group under the “shn” AXO group

shn_acl_add_action_group($module,$action_group,$desc)

adds an action group under the module, e.g “create” this is an AXO group under the module AXO group. e.g it will be added under “shn”→“modules”→“or

shn_acl_add_action($module,$action_group=NULL,$action,$desc)

adds an action under the “shn”→“module”→“action_group” e.g “shn_or_register” this is an AXO this will be added to the group “shn”→“or”→“create”

shn_acl_add_action_case($module,$action_group=NULL,$action,$case,$desc)

add a case under “shn”→ “module”→“action_group”→“action” e.g “shn_or_org_view” case “all” ,”one“ this is an AXO this will be added to the group “shn”→“or”→“create” →“shn_or_org_view” as “shn_or_org_view_all”

shn_acl_add_role($role,$desc)

adds a role, e.g “admin” this is a ARO group

shn_acl_add_user($user,$desc)

adds a User this is a ARO

shn_acl_add_to_role($user,$role)

adds a role to user

shn_acl_add_perm_type($perm_type,$desc)

adds permission type,e.g “execute”,this is an ACO we could have gone without AXO's. but in the future we may provide ACL for database table rows. therefore AXO's are required. To specify permissions users to actions no need for AXO's. but since we are having AXO's as actions ,and an ACO named “execute” is specified for all those.

shn_acl_add_perms_module_role($role,$module)

add an ACL for a role to a module therefore the module is permitted for the role permissions for the module are inherited by “action groups” and “actions” under the module, unless overridden.

shn_acl_add_perms_action_group_role($role,$module,$action_group)

add an ACL for a role to an action group with in the module therefore the action group is permitted for the role permissions for the action group are inherited by actions under the module, unless overridden.

shn_acl_add_perms_action_role($role,$action)

add an ACL for a role to an action in the action group with in the module therefore the action is permitted for the role e.g : Allow admin to execute “shn_or_register”

shn_acl_add_perms_action_case_role($role,$action,$case)

add an ACL for a role to an action case in the action group with in the module. Therefore the action case is permitted for the role e.g : Allow admin to execute “shn_or_org_view_all”

shn_acl_add_perms_module_user($user,$module)

add an ACL for a user to a module Therefore the module is permitted for the user permissions for the module are inherited by “action groups” and “actions” under the module, unless overridden.

shn_acl_add_perms_action_group_user($user,$module,$action_group)

add an ACL for a user to an action group with in the module therefore the action group is permitted for the user permissions for the action group are inherited by actions under the module, unless overridden.

shn_acl_add_perms_action_user($user,$action)

add an ACL for a user to an action in the action group with in the module therefore the action is permitted for the user e.g : Allow admin to execute “shn_or_register”

shn_acl_add_perms_action_case_user($user,$action,$case)

add an ACL for a user to an action case in the action group with in the module, therefore the action case is permitted for the user e.g : Allow user to execute “shn_or_org_view_all”

shn_acl_check_perms_action($user,$action)

checks whether the user can execute a particular action there is no point in asking whether a role has permissions. as user A with a particular role may be denied a certain resource. so its not a boolean answer for the role.

shn_check_perms_action_case($user,$action,$case)

checks whether the user can execute a particular action case this is a special case of action. e.g action may be “shn_or_org” and two cases under that would be “view_all” and “view_one” , and they need two different permissions

example:

  global $global;
    include_once $global['approot']. 'inc/lib_security/acl_api.inc';
    include_once $global['approot'].'inc/lib_security/acl.inc';
    $acl=new SahanaACL(NULL);
    /**
    add a section to categorize sahana users in ARO table.
    used is a function in acl.inc which you need not call
    as module writers. "users" section needs to be added only
    once per sahana and will be done at the installation
    */
    $acl->_shn_add_section("users","users of sahana","ARO");
    /**
    add a section to categorize sahana acions in AXO table.
    used is a function in acl.inc which you need not call
    as module writers. "actions" section needs to be added only
    once per sahana and will be done at the installation
    */
    $acl->_shn_add_section("actions","actions avaliable in sahana","ARO");
    //add a group to contain Sahana AROs(root group)
    $acl->_shn_add_aro_group("sahana","Sahana ARO root",0);
 
    // add a role named guest
    $res=shn_acl_add_role("guest","guest role");
    //add a user named "ravids"
    $res=shn_acl_add_user("ravids","ravindra");
    // add "ravids" to the "guest" role
    $res=shn_acl_add_to_role("ravids","guest");
 
    //add a group to contain Sahana AXOs(root group)
    $acl->_shn_add_axo_group("sahana","Sahana AXO root",0);
    // add a module named "or"
    $res=shn_acl_add_module("or","organization reg");
    // add an action group named "create" under the module "or"
    $res=shn_acl_add_action_group("or","create","testing");
    //add an action name 'shn_or_test2"  under the above action group
    $res=shn_acl_add_action("or","create","shn_or_test2","test function");
    // add an action case name "view_all"  under the above case
    $res=shn_acl_add_action_case("or","create","shn_or_test2","view_all","test cse");
    /** add a ACO , not neccesary to protect actions, but when  we go to
    table and field level protection need to seperate "read","write"
    permissions , hence requires ACO
    */
   //$res=shn_acl_add_perm_type("execute","execute permission");
   // add permission for the user. now 'ravids' can execute "shn_or_test2" 
    $res=shn_acl_add_perms_action_user("ravids","shn_or_test2");
    //check whether permission was added as expected. should return true
    $res=shn_acl_check_perms_action('ravids','shn_or_test2');
    // now recheck with a different action or user ,should return false
    /** you can give permission to the whole module , so everything in 'or'
    is allowed to 'ravids' unless overidden by another ACL
    */
    $res=shn_acl_add_perms_module_user('ravids','or');
    //give permission to 'guest' role to execute everything within 'or'
    $res=shn_acl_add_perms_module_role('guest','or');
    //give permission for 'create' action group with in 'or' to 'ravids'
    $res=shn_acl_add_perms_action_group_user('ravids','or','create');
    // give permission to 'guest' to the action 'shn_or_test2'
    $res=shn_acl_add_perms_action_role('guest','shn_or_test2');
    //give permission for 'create' action group with in 'or' to 'guest' role
    $res=shn_acl_add_perms_action_group_role('guest','or','create');
    //give permission to 'ravids' to execute 'view_all' case of 'shn_or_test2'
    $res=shn_acl_add_perms_action_case_user('ravids','shn_or_test2','view_all');
    //give permission to 'guest' to execute 'view_all' case of 'shn_or_test2'
    $res=shn_acl_add_perms_action_case_role('guest','shn_or_test2','view_all');

Navigation
QR Code
QR Code dev:authorization (generated for current page)