Explore Access Control List (ACL).

Components of ACLs

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

The object is the target to which access needs to be controlled. 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:

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.

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:

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.
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 view operations on the incident table.

ACL on an incident record.

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

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.

ACL evaluation process

An ACL rule only grants a user access to an object if the user meets all of the permissions required by the matching ACL rule.

  • The condition must evaluate to true.
  • The script must evaluate to true or return an answer variable with the value of true.
  • The user must have one of the roles in the required roles list. If the list is empty, this condition evaluates to true.
  • [Record ACL rules only] The matching table-level and field-level ACL rules must both evaluate to true.
Figure 1. ACL evaluate permissions
ACL evaluate permissions

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.

The effects of being denied access to an object depend on the ACL rule that the user failed. For example, failing a read operation ACL rule prevents the user from seeing the object. Depending on the object secured, the ACL rule hides a field on a form, hides rows from a list, or prevents a user from accessing a UI page. The following table contains complete list of results of failing an ACL rule for a given operation and object type.

Pre and post query ACL checks

Your instance checks ACL rules both before and after a user makes a query. Because different information is available before and after a query, results can be different.
Pre-query ACL check

Before your instance runs a database query, it checks ACL rules for each field in the queried table to determine which fields a user may access. This check only looks at the user's roles, and checks to see if these roles allow access to fields. Because this check runs before the query, the ACL doesn't have access to the records on the table, so it cannot take that data into account. Scripts and conditions that rely on knowing contents of a record are not evaluated.

If the user doesn't have read access at this point, the value for the field is not shown to the user.

Post-query ACL check

After the query, your instance checks each record returned by the query. During this check, there is context for the ACL, so the role, condition, and script portions of the ACL are evaluated. If the user doesn't have read access at this point, the value for the field is not shown to the user, however the user will see the field label if their roles allow access to the field.

OperationResults of failing an ACL rule on object
execute User cannot execute scripts on a record or UI page.
create User can’t see the New UI action from forms. The user also cannot insert records into a table using API protocols such as web services.

A create ACL with a condition requiring that a field contain a specific value may evaluate as false. Fields on new records are considered empty until the record is saved.
read User cannot see the object in forms or lists. The user also cannot retrieve records using API protocols such as web services.
write User sees a read-only field in forms and lists, and the user cannot update records using API protocols such as web services.
delete User cannot see the Delete UI action from forms. The user also cannot remove records from a table using API protocols such as web services.
edit_task_relations User cannot define relationships between task tables.
edit_ci_relations User cannot define relationships between Configuration Item [cmdb_ci] tables.
save_as_template Used to control the fields that should be saved when a template is created.
add_to_list User cannot view or personalize specific columns in the list mechanic.
list_edit User cannot update records (rows) from a list.
report_on User cannot create a report on the ACL table. For more information, see Restrict report creation with an ACL rule.
report_view User cannot view the content of a report on the ACL table or on the ACL field. For more information, see Reporting.
personalize_choices User cannot right-click a choice list field and select Configure Choices.

ACL matching requirements for objects

Object Type Matching ACL Rules Required to Access Object Existing Wildcard ACL Rules
Client-callable script includes Users must meet the permissions of two ACL rules:
  1. All wildcard ACL rules for the object (if any ACL rule exists for the operation).
  2. The first ACL rule that matches the object's name (if any ACL rule exists for the operation).
 By default, there are no wildcard (*) rules for these object types. If you create a wildcard ACL rule for one of these objects, then the ACL rule applies to all objects of this type.
Processors
UI pages Users must meet the permissions of two ACL rules:
  1. The first ACL rule that matches the record's field (if any ACL rule exists for the operation).
  2. The first ACL rule that matches the record's table (if any ACL rule exists for the operation).
 By default, there are wildcard table rules (*) for the create, read, write, and delete operations and wildcard field rules (*.*) for the personalize_choices, create, and save_as_template operations. When you create a new table, create new ACL rules for the table unless you want to use the provided wildcard ACL rules.
Record
Note: The Security manager default behavior (glide.sm.default_mode) property determines whether users can access objects that only match against wildcard table ACL rules. When this property is set to Deny access, only administrators can access objects that match the wildcard table ACL rules.
Note: The wildcard field ACL rule (*.*) for the create operation reuses the same permissions as the write operation. This means that the create permissions are the same as the write permissions unless you define an explicit create operation ACL rule.

Multiple ACL rules at the same point in the processing order

If two or more rules match at the same point in the processing order, the user must pass any one of the ACL rules permissions to access the object. For example, if you create two field ACL rules for incident.number, then a user who passes one rule has access to the number field regardless of whether the user failed any other field ACL rule at the same point in the processing order.

Required role

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. See Elevate to a privileged role for instructions.

ACL rules in scoped applications

You can create ACL rules for objects in the same scope as the ACL rule and for tables with at least one field that is in the same scope as the ACL rule.

For tables that are in a different scope than the ACL rule record, the types of rules are limited.
  • You can create an ACL rule for any table, UI page, or other object that is in the same scope as the ACL rule.
  • You can create an ACL for a field that is in the same scope as the ACL rule.
    • If the table is in the same scope, you can use a script to evaluate permissions.
    • If the table is in a different scope, you cannot use a script to evaluate permissions.
  • You cannot create or modify ACL rules for objects that are in a different scope than the application you have selected in the application picker, including adding a role to an ACL in a different scope.
  • You can create wildcard table rules (*) only in the global scope.
  • You can create wildcard field rules (*) only for tables in the same scope as the ACL rule.