Latest revision as of 00:16, 17 February 2017

Introduction

Access control within X2CRM is facilitated through the combination of record assignment and visibility. Public visibility allows all users to see the record. A visibility of private will only allow a user to view the record if it is assigned explicitly to their user. Finally, a visibility of "User's groups" will allow visibility if the current user and the assigned user share a group (or the record is assigned to the group). These rules are then further limited by Role permissions. A Role can be assigned permission according to each module, limiting their access to particular operations, such as viewing or updating. Roles can also be granted granular permissions to view or edit individual fields in a module.

Assignment and Visibility

The assignment of a record is controlled by the assignedTo field. This may be a value such as "Anyone", a username, or a group ID. Record visibility is controlled by the visibility field, which at the time of writing can take the following integer values (see X2PermissionsBehavior for more details):

Hidden Records

When a record is assigned to 'Anyone' and given private visibility, the record becomes hidden from the UI, even for the admin user. This function is ordinarily used by the duplicate checker after the duplicates have been resolved. The data for the record is still present in the database, and can still be viewed and updated manually. In X2CRM version 6.5.3, a tool has been added to find records that may have been inadvertently hidden.

Roles and Permissions

Within X2CRM, each user may be assigned one or more Roles. Each of these Roles are associated with different groups of permissions. Each permission represents a different operation, such as viewing a record. This access control model is known as Role-Based Access Control (RBAC). Within X2CRM, authorization is managed by the X2AuthManager class, which extends Yii's CDbAuthManager class. Please see the Yii documentation page Authentication and Authorization for more information.

Configuring Module Access for a Role

To configure module access for a particular role, first navigate to the admin panel, then view the "Edit User Permissions and Access Rules" page under the User Management section.

Each of the roles can be granted permission for the following actions:

• View
• Create
• Update
• Delete
• Admin

The View, Update, and Delete actions can additionally be restricted to only those that are assigned to the user. Currently, only roles with Admin permission for a module can perform record import and export.

Configuring Field Level Permissions for a Role

Configuring Field Level Permissions

Access to data can be further limited by more granular control over the particular fields in each module that a role can access. For example, a role may have view permissions for most of the fields of a Contact, but can only edit a subset of those fields. Fields that cannot be viewed will be hidden from any grids or form layouts.

To configure field level permissions for a role, first navigate to the admin panel, then view the "Manage Roles" page under the User Management section.

It is on this screen that you can configure the view and edit permissions for each field, as well as which users belong to that role. You can also configure a custom session timeout for users who belong to this role. To add permission for a field, you can click the plus icon or drag the field into the left pane. You can also use the text field on the top of the multiselect to filter the available fields.

Custom Permissions

As a developer expands the functionality of their custom modules, they may find it advantageous to customize the restrictions placed upon users trying to access particular actions. By adding custom permissions entries for the actions you add, you can enable the administrator to manage user access to the action within the permissions configuration interface.

Adding a Custom Permission

When adding custom actions to any of the controllers, it is likely that you will want to limit access using the permissions system. For standard controllers, e.g., those under protected/controllers, you can add custom access rules by modifying the accessRules() method of the controller. The 'users' definition describes which users have the ability to access that action. To limit access to a particular user, such as "admin", you would specify their username directly. To allow all users (including guest) to use the action, specify an asterisk ("*"). For example, to allow guest access for a new controller method actionTest(), one would add the following access rule:

array('allow',
    'actions' => array('test'),
    'users' => array('*'),
),

Please see the page on the Customization Framework for more information about safely persisting your customizations through updates.

The access control in modules is handled a bit differently. While in standard Controllers you can use the accessRules() method to define the rules, the custom module system in X2CRM requires authorization rules to be loaded dynamically.

To add a permission for a new custom module action, you'll want to instead add the necessary auth items and their relationships to the auth graph. The auth items themselves are stored in the x2_auth_item table. These are then associated with their appropriate parent permission with the x2_auth_item_child table. For example, in adding guest access to the actionTest() method of a Testmodule controller, one would insert the following database records:

INSERT INTO x2_auth_item (name, type, data) VALUES ('TestmoduleTest', 0, 'N;');
INSERT INTO x2_auth_item_child (parent, child) VALUES ('GuestSiteFunctionsTask', 'TestmoduleTest');

Verifying Permissions with the Auth Graph

The Auth Graph

After modifying or adding custom authorization rules, it may be helpful to visualize the current state of the authorization graph. This can help decide where a new permission belongs or catch inadvertent granting of permissions. As the administrator, navigate to /admin/authGraph. You will be presented with a listing of the various permissions, as well as their relation to their children.

Of particular interest are a few specific permission groups, including GeneralAdminSettingsTask, AuthenticatedSiteFunctionsTask, and GuestSiteFunctionsTask. The GeneralAdminSettingsTask is required for most of the actions in the admin panel. The permissions in GuestSiteFunctionsTask are granted to users who are not logged in, while those in AuthenticatedSiteFunctions are granted to logged in users.

Each of the modules have a few key permission groups, named {module}PrivateReadOnlyAccess, {module}PrivateUpdateAccess, {module}PrivateFullAccess, {module}PrivateBasicAccess, {module}ReadOnlyAccess, {module}BasicAccess, {module}UpdateAccess, {module}FullAccess, {module}AdminAccess. These groups correspond to the various levels of access granted on the Edit User Permissions and Access Rules page. Each auth item within the group represents the permissions for a controller action, as is named in the format {module}{action}. For example, the "create" action of the Accounts controller is associated with the permission "AccountsCreate."