X2Engine - New pages [en]

Permissions System

2017-02-09T01:27:06Z

Raymond Colebaugh:

[[Category:Development]]
= 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 [[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 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 [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 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.

[[File:EditRoleAccess.png]]

== Configuring Field Level Permissions for a Role ==
[[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.

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:

<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|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."

X2 Hub Integration

2017-02-07T00:44:03Z

Raymond Colebaugh:

[[Category:Support]]
X2 Hub Services is an external connectivity provider to various third-party services, including Google Maps, Google Calendar sync, and two factor auth through Twilio. By configuring X2 Hub Services for your X2CRM instance, you will greatly reduce the amount of time and effort required in configuring and managing credentials for each of the supported providers. This allows you to quickly and easily extend the functionality of your CRM with a wide variety of integrations. Please visit the [https://www.x2crm.com/products/ Products page] for purchasing information.

== Initial Activation ==
[[File:HubActivation.png|200px|thumb|left]]

Once you have purchased a subscription to X2 Hub Services, please allow up to 24 hours for review and activation. Once your account has been activated, you will receive an email containing your X2 Hub product key. As admin, navigate to the admin panel and visit the "Configure X2 Hub Integration" page under the X2 Hub Services section.

Paste the product key you received in your activation email into the text field and ensure that "Enabled" is selected. Once you've entered a valid product key and enabled Hub, the status indicator on the Hub integration page should read "Enabled."

On this screen, you will also be presented with checkboxes for the various external services. If for any reason you wish to disable Hub for a particular service and use your existing integration configuration, please deselect the appropriate service before saving. For example, if you wish to enable X2 Hub for Google Maps integration, but would like to restrict Google Calendar usage to occur through your existing Google configuration, you can deselect the Google Calendar checkbox on the Hub configuration page.

== Additional Setup ==
Various components of X2CRM require additional setup after enabling Hub. Please see the following sections for additional steps in configuring your X2 Hub Services integration.

=== Google Calendar Sync ===
After the administrator has configured X2 Hub, users will be able to link their Google Calendars as they would ordinarily. Each user will first want to ensure that their Google ID is configured in their profile settings. Once the user's Google ID is registered, they will be able to link a Google Calendar to any of their calendars in X2CRM.

First, either create your new calendar, or update an existing calendar. Then, select "Link to Google Calendar." You will be presented with the Google authorization screen and the required permissions. After accepting, you'll be redirected back to the calendar. Next, revisit the calendar configuration, select your desired Google Calendar from the dropdown of available remote calendars, and hit "Save."

=== Two Factor Authentication ===
[[File:ActivateTwoFactor.png|200px|thumb|right]]

Once the administrator has activated X2 Hub Services, there is an additional step which must be performed before users can enable two factor authentication. From the admin panel, navigate to the 'Advanced Security Settings' page under the Security Settings section. Under "Two Factor Authentication," select "X2 Hub Services" as the active two factor auth credentials, before hitting "Save." Once the two factor auth credentials have been selected, each user will be able to enable two factor authentication for their user login.

To activate two factor authentication for a particular user, first navigate to the Preferences page. Next, select the checkbox to enable two factor auth. A verification code will be sent to the user's cell phone, which must be entered into the verification text field. If the verification succeeds, next time you login you will be presented with an additional text field to enter your confirmation code. Note: verification codes will be sent to the cell phone number set in the user's profile settings.

In the event that a user is unable to login to the system after enabling two factor auth, such as if their phone is lost or stolen, please notify the administrator. The administrator has privilege to remove the two factor auth requirement for that user by visiting the user's page in the Users module, allowing the user to login again and reconfigure two factor auth.

== Troubleshooting Connectivity ==
If there are any issues when connecting or the status indicator still reads "Disabled," please verify that your server already meets the requirements for running X2CRM. In particular, you'll want to ensure that you have either installed the PHP curl extension, or that your have enabled allow_url_fopen in your php.ini configuration. Furthermore, connectivity to X2 Hub Services requires that outbound network traffic on port 443 is allowed from the server. To verify network connectivity by command line, on your server execute <tt>curl https://hub.x2crm.com/index.php/site/ping\?unique_id=KEY</tt>, substituting your product key as appropriate.