Access Control Lists

Overview

Access Control Lists (ACLs) are used to control access to the modules, data, and actions available to users in Sugar. By default, Sugar comes with a default ACL Strategy that is configurable by an Admin through the Roles module via Admin > Role Management. Sugar also comes with other ACL strategies that are located in the ./data/acl/ folder, and are used in other parts of the system such as the Administration module, Emails module, Locked Fields functionality, and many others. They can also be leveraged by customizations and custom ACL strategies can be implemented to control your own customizations.

Actions

Actions are the use cases in which a User interacts with a particular module in the system. ACLs control access by using different logic to determine if a user can do an action. Below is a list of actions that are utilized by Sugar and will be requested actions against a custom ACL strategy implementation. You can add your own actions to be checked against in a custom strategy, but the following list should always be considered:

• index, list, listview - for module ListView access
• detail, detailview, view - module DetailView access
• popupeditview, editview - module EditView access
• edit, save - editing module data
• import - import into the module
• export - export from the module
• delete - delete module record
• team_security - should this module have team security enabled?
• field - access field ACLs. The field action is specified via context array, see below
• subpanel - checks if subpanel should be displayed. Should have "subpanel" context option.

Note: Action names are not case sensitive, although the standard practice is to use them in all lowercase

Field Actions

When using the field action, the action for the particular field that is being checked is passed via Context. The field actions that are used in Sugar are:

• access - any access to field data
• read, detail - read access
• write, edit - write access

Context

The context array is used throughout Sugar's ACL architecture as a way to pass extra contextual data that is used by an ACL Strategy to determine the access request. The following context parameters are used in stock contexts, and should be used as a guideline for custom ACL implementations as parameters that should be accommodated or used:

• bean (SugarBean) - the current SugarBean object
• user (User) - the user to check access for, otherwise defaults to the current user.
• user_id (String) - the current user ID (also overrides global current user). If the current user object is available, use the user context, since it has precedent.
• owner_override (Bool) - if set to true, apply ACLs as if the current user were the owner of the object.
• subpanel (aSubPanel) - used in subpanel action to provide aSubPanel object describing the panel.
• field, action (String) - used to specify field name and action name for field ACL requests.
• massupdate (Bool) - true if save operation is a mass update

SugarACL

The SugarACL Class, ./data/SugarACL.php, is the static API for checking access for an action against a module. 

checkAccess()

The checkAccess() method is used to check a users access for a given action against a module. 

    SugarACL::checkAccess('Accounts','edit');

Arguments

Returns

Boolean

checkField()

The checkField() method is used to check a users access for a given field against a module. 

    SugarACL::checkField('Accounts','account_type','view');

Arguments

Returns

Boolean

getFieldAccess()

The getFieldAccess() method is used to get the access level for a specific

    $access = SugarACL::getFieldAccess('Accounts','account_type');

Arguments

Returns

Integer

The integers are represented as constants in the SugarACL class, and correspond as follows:

• SugarACL::ACL_NO_ACCESS = 0 - access denied
• SugarACL::ACL_READ_ONLY = 1 - read only access
• SugarACL::ACL_READ_WRITE = 4 - full access

filterModuleList()

The filterModuleList() method is used to filter the list of modules available for a given action. For example, if you wanted to get all the modules the current user had edit access to, you might call the following in code:

    global $app_list_strings;
$modules = $app_list_strings['module_list'];
$editableModules = SugarACL::filterModuleList($modules,'edit');

Arguments

$modules = array(
   'Accounts',
   'Cases',
   'Administration'
);
$accessModules = SugarACL::filterModuleList($modules,'access',true);

Returns

Array

The filtered list of modules.

disabledModuleList()

Similar to the previous method, the disableModuleList() method filters a list of modules to those that the user does not have access to.

    global $app_list_strings;
$modules = $app_list_strings['module_list'];
$disabledModules = SugarACL::disabledModuleList($modules,'access');

Arguments

$modules = array(
   'Accounts',
   'Cases',
   'Administration'
);
$accessModules = SugarACL::filterModuleList($modules,'access',true);

Returns

Array

The filtered list of modules.

moduleSupportsACL()

The moduleSupportsACL() method is used to check if a module has ACLs defined on the vardefs. A good use case for this method is to not run any ACL checks if module has no ACL definitions.

    SugarACL::moduleSupportsACL('Accounts');

Arguments

Returns

Boolean

listFilter()

The listFilter() method allows for filtering an array of fields for a module to remove those which the user does not have access to. The removal can be done in a couple of different ways, provided by the $options argument. The filtering of the array is done in place, rather than returning the filtered list.

    $Account = BeanFactory::getBean('Accounts','12345');
$fields = array(
  'account_type' => 'foobar',
  'status' => 'New',
  'name' => 'Customer'
);

$context = array(
   'bean' => $Account
);

$options = array(
    'blank_value' => true
);

SugarACL::listFilter('Accounts',$fields,$context,$options);
echo <pre>json_encode($fields)</pre>;

Should the user not have access to the 'status' field, the above might output:

    {
  "account_type": "foobar",
  "status": "",
  "name": "Customer"
}

Arguments

Returns

Void

SugarBean Usage

The SugarBean class also comes with some methods for working with the ACLs in regards to the current SugarBean context. These methods automatically provide the 'bean' context parameter and provide a wrapper that utilizes the SugarACL class

getACLCategory()

The getACLCategory() method is used by all of the ACL helper methods that exist on the SugarBean and is used to determine the module name that should be checked against for the current Bean. By default, it will return the acl_category property set on the Bean, otherwise if that is not set, it will use the module_dir property that is configured on the Bean. This method can be overridden by a custom Bean implementation, but the following code shows which properties on a Bean implementation should be set for usage with ACLs.

    <?php

class testBean extends SugarBean
{
    public $module_dir = 'testBean';
    //all the other SugarBean class logic...
}

class test_SubmoduleBean extends SugarBean
{
    public $module_dir = 'testBean/submodule';
    public $acl_category = 'test_SubmoduleBean';
    //all the other SugarBean class logic...
}

$test = new testBean();
//echoes testBean
echo $test->getACLCategory();

$submodule = new test_SubmoduleBean();
//echoes test_SubmoduleBean
echo $submodule->getACLCategory();

Arguments

None

Returns

String

ACLAccess()

The ACLAccess() method is a wrapper for SugarACL::checkField() method, which provides the Bean context as the current SugarBean.

    $Account = BeanFactory::getBean('Accounts','12345');
if ($Account->ACLAccess('edit')){
   //do something if User has edit access
}

Arguments

Returns

Boolean

ACLFieldAccess()

The ACLFieldAccess() method is a wrapper for SugarACL::checkAccess() method, which provides the Bean context as the current SugarBean.

    $Account = BeanFactory::getBean('Accounts','12345');
if ($Account->ACLFieldAccess('account_type','edit')){
   //do something if User has account_type edit access
}

Arguments

Returns

Boolean

ACLFieldGet()

The ACLFieldGet() method is a wrapper for SugarACL::getFieldAccess() method, which provides the Bean context as the current SugarBean.

    $Account = BeanFactory::getBean('Accounts','12345');
$accountTypeAccess = $Account->ACLFieldGet('account_type');

Arguments

Returns

Boolean

ACLFilterFields()

The ACLFilterFields() method uses the SugarACL::checkField() method to blank out those fields which a user doesn't have access to on the current SugarBean.

    $Account = BeanFactory::getBean('Accounts','12345');
$Account->status = 'Old';
$Account->ACLFilterFields('edit');

echo $Account->status;

Should the user not have 'edit' access to the 'status' field, the above wouldn't output any data since the status field would be blank.

Arguments

Returns

Void

ACLFilterFieldList()

The ACLFilterFieldList() method is a wrapper for SugarACL::listFilter() method, which provides the Bean context as the current SugarBean.

    $Account = BeanFactory::getBean('Accounts','12345');
$fields = array(
  'account_type' => 'foobar',
  'status' => 'New',
  'name' => 'Customer'
);

$options = array(
    'blank_value' => true
);

$Account->ACLFilterFieldList($fields,array(),$options);
echo "<pre>".json_encode($fields)."</pre>";

Should the user not have access to the 'status' field, the above might output:

    {
  "account_type": "foobar",
  "status": "",
  "name": "Customer"
}

Arguments

Returns

Void

Legacy Methods

When working in the Sugar codebase there might be areas that still utilize the following legacy ACLController class. The following gives a brief overview of a few methods that might still be used but should be avoided in future custom development.

ACLController::checkAcess()

The ACLController::checkAccess() method is just a wrapper for SugarACL::checkAccess() method and has been left in place for backward compatibility.

ACLController::moduleSupportsACL()

The ACLController::moduleSupportsACL() method is just a wrapper for SugarACL::moduleSupportsACL() method and has been left in place for backward compatibility.

ACLController::displayNoAccess()

This method does an echo to display a "no access" message for pages.