Access control rules

Access control rules, also known as access control lists (ACL) or access controls, restrict access to data by requiring users to pass a set of requirements before they can interact with it.

All access control rules specify:
  • The object and operation being secured
  • The permissions required to access the object

Objects

Each object consists of a type and name that uniquely identifies a particular table, field, or record. For example, all these entries specify an object.

Table 1. Sample access control objects
Type Name Object secured
record [incident].[-- None --] The Incident table.
record [incident].[active] The Active field in the Incident table.
REST_Endpoint user_role_inheritance The record for the user_role_inheritance Scripted REST API.

Operations

Each operation describes a valid action the system can take on the specified object. Some objects such as records support multiple operations, while other objects such as a REST_Endpoint only support one operation. For example, all these entries specify an operation.

Table 2. Sample access control operations
Type Name Operation Operation secured
record [incident].[-- None --] create Creating records in the Incident table.
record [incident].[active] write Updating the Active field in the Incident table.
REST_Endpoint user_role_inheritance execute Running the user_role_inheritance Scripted REST API.

Permissions

The permissions specify when someone can access the named object and operation. Security administrators can specify permission requirements by adding:
  • One or more user roles to the Requires role list.
  • One or more conditions.
  • A script that evaluates to true or false or sets the answer variable to true or false.

To gain access to an object and operation, a user must pass all permissions listed in an access control. For example, this access control restricts access to write operations on the incident table.

Figure 1. Sample access control record

To update a record in the incident table, a user must have the listed role and the record must meet the condition.

Table 3. Permissions required to write to the incident table
Permission type Requirement Description
Requires role

Requires role: itil

Only allow users with the itil role to update incidents.
Condition [Incident state] [is not] [Closed] Only allow updates to active incident records.

Granting or denying access

The system evaluates access controls using this process.

Figure 2. Process to grant or deny access
Process to grant or deny access to an object.

Whenever a session requests data, the system searches for access control rules that match the requested object and operation. If there is a matching access control rule, then the system evaluates if the user has the permissions required to access the object and operation. If an access control rule specifies more than one permission, then the user must meet all permissions to gain access to the object and operation. Failing any one permission check prevents the user from accessing the matching object and operation.

If a user does not meet the permissions of the first matching rule, the system evaluates the permissions of the next matching access control rule as specified by the access control processing order. If the user fails to meet the permissions of any matching access control rule, the system denies access to the requested object and operation.
Note: If there are no matching access control rules for the requested object and operation, then the system grants the user access to it. In practice, it is rare for the system to find no matching rules because the system has a set of default access control rules that protect all record operations.

Roles

Normal admin users can view and debug access control rules. However, to create or update existing access control rules, administrators must elevate privileges to the security_admin role.