Permissions System - Revision history

Raymond Colebaugh at 00:16, 17 February 2017

2017-02-17T00:16:02Z

Raymond Colebaugh at 21:29, 9 February 2017

2017-02-09T21:29:16Z

Raymond Colebaugh at 19:45, 9 February 2017

2017-02-09T19:45:01Z

Raymond Colebaugh: Created page with "Category:Development = Introduction = Warning: This article is under construction. = Assignment and Visibility = The assignment of a record is controlled by the as..."

2017-02-09T01:27:06Z

Created page with "Category:Development = Introduction = <b>Warning:</b> This article is under construction. = Assignment and Visibility = The assignment of a record is controlled by the as..."

New page

[[Category:Development]]
= Introduction =
<b>Warning:</b> This article is under construction.

= 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 [[x2doc:X2PermissionsBehavior|X2PermissionsBehavior]] for more details):

{|class="wikitable"
|-
! scope="row" |<tt>Value</tt>
| <tt>Visibility</tt>
| <tt>Description</tt>
|-
! scope="row" | 0
| Private
| This visibility value implies "private"; ordinarily visible only to assignee(s)/owner(s) of the record
|-
! scope="row" | 1
| Public
| This visibility setting implies the record is public/shared, and anyone can view.
|-
! scope="row" | 2
| Groups
| This visibility setting implies that the record is visible to the owners and other members of groups to which the owners belong ("groupmates").
|-
|}

== 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 records 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.

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

[[File:EditRoleAccess.png]]

Each of the roles can be granted granular 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.

== 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:

<syntaxhighlight lang="php">
array('allow',
'actions' => array('test'),
'users' => array('*'),
),
</syntaxhighlight>

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 <code>x2_auth_item</code> table. These are then associated with their appropriate parent permission with the <code>x2_auth_item_child</code> table. For example, in adding guest access to the actionTest() method of a Testmodule controller, one would insert the following database records:

<syntaxhighlight lang="sql">
INSERT INTO x2_auth_item (name, type, data) VALUES ('TestmoduleTest', 0, 'N;');
INSERT INTO x2_auth_item_child (parent, child) VALUES ('GuestSiteFunctionsTask', 'TestmoduleTest');
</syntaxhighlight>

== Verifying Permissions with the Auth Graph ==
[[File:AuthGraph.png|200px|thumb|right]]

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.

@@ Line 1: / Line 1: @@
 [[Category:Development]]
 = Introduction =
-<b>Warning:</b> This article is under construction.
+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 =
@@ Line 29: / Line 27: @@
 == 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 records 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.
+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 =
@@ Line 35: / Line 33: @@
 == Configuring Module Access for a Role ==
-To configure module access for a particular role, first navigate to the admin panel, then view the "Edit Role Access" page under the User Management section.
+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:
@@ Line 49: / Line 47: @@
 == Configuring Field Level Permissions for a Role ==
-[[File:ManageRoles.png|200px|thumb|right]]
+[[File:ManageRoles.png|200px|thumb|right|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.
 = 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.
+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 ==
@@ Line 81: / Line 81: @@
 == Verifying Permissions with the Auth Graph ==
-[[File:AuthGraph.png|200px|thumb|right]]
+[[File:AuthGraph.png|200px|thumb|right|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.

@@ Line 2: / Line 2: @@
 = Introduction =
 <b>Warning:</b> This article is under construction.
 = Assignment and Visibility =
@@ Line 30: / Line 32: @@
 = 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.
+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 [https://en.wikipedia.org/wiki/Role-based_access_control Role-Based Access Control (RBAC)]. Within X2CRM, authorization is managed by the [[x2doc:X2AuthManager|X2AuthManager]] class, which extends Yii's [[yii:CDbAuthManager|CDbAuthManager]] class. Please see the Yii documentation page [[yiiguide:topics.auth|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 Role Access" page under the User Management section.
-Each of the roles can be granted granular permission for the following actions:
+Each of the roles can be granted permission for the following actions:
 * View
 * Create
@@ Line 68: / Line 70: @@
 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 <code>x2_auth_item</code> table. These are then associated with their appropriate parent permission with the <code>x2_auth_item_child</code> table. For example, in adding guest access to the actionTest() method of a Testmodule controller, one would insert the following database records:
+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.
 <syntaxhighlight lang="sql">