Using Access Control Rules
| Note: This article applies to Fuji and earlier releases. For more current information, see Access Control List Rules at http://docs.servicenow.com
The ServiceNow Wiki is no longer being updated. Visit http://docs.servicenow.com for the latest product documentation.
- 1 Overview
- 2 Creating ACL Rules
- 3 Granting or Denying Access
- 4 Record ACL Rules
- 5 UI Page ACL Rules
- 6 Processor ACL Rules
- 7 Client-Callable Script Include ACL Rules
- 8 Debugging
- 9 Troubleshooting
- 10 Enhancements
An instance uses access control list (ACL) rules, also called access control rules, to control what data users can access and how they can access it. ACL rules require users to pass a set of requirements in order to gain access to particular data. Each ACL rule specifies:
- The object and operation being secured
- The permissions required to access the object
The system searches for ACL rules that match both the object and operation the user wants to access. If there are no matching ACL rules for the object and operation combination, then the object does not require any additional security checks and the instance grants the user access to them. By default, the system provides ACL rules to restrict access to all database and configuration operations.
After finding a matching ACL rule, the system evaluates if the user has the permissions required to access the object and operation. If a user meets the ACL rule permissions, the instance grants the user access to the listed operation on the object. If a user does not meet the ACL rule permissions of the first matching rule, the system evaluates the next matching ACL rule. If the user fails to meet the ACL rule permissions of any matching ACL rule, the system denies the user access to the operation on the object.
Users with access to the security_admin role can:
- Create ACL rules to secure new objects
- Update existing ACL rules to grant or deny users access to objects based on their business requirements
- Debug ACL rules to determine why users cannot access certain objects
2 Creating ACL Rules
Create custom ACL rules to secure access to new objects or to change the default security behavior. To create new ACL rules, you must elevate privileges to the security_admin role. You can create ACL rules only for objects that are in the same scope as the ACL rule and for other tables that have at least one field in the same scope as the ACL rule (starting with the Fuji release). For tables that are in a different scope than the ACL rule record, the types of rules are limited.
To create an ACL rule:
- Elevate privileges to the security_admin role.
- Navigate to System Security > Access Control (ACL).
- Click New.
- Define the object the ACL rule secures and the permissions required to access the object. See Access Control Fields.
- Right-click the form header and select Save.
2.1 Access Control Fields
Access control records use the following fields.
|Type||Select what kind of object this ACL rule secures. The type of object determines how the object is named and what operations are available.|
|Operation||Select the operation this ACL rule secures. Each object type has its own list of operations. An ACL rule can only secure one operation. To secure multiple operations, create a separate ACL rule for each.|
|Admin Overrides|| Select this check box to have users with the admin role automatically pass the permissions check for this ACL rule, regardless of what script or role restrictions would apply. However, the nobody role takes precedence over the admin override option, so even admins cannot have access if they are assigned the nobody role.
Clear this check box if administrators must meet the permissions defined in this ACL rule to gain access to the secured object. Since administrators will always pass role checks (see the description of the Requires role field), use the condition builder or Script field to create a permissions check that administrators must pass.
|Active||Select this check box to enforce this ACL rule.|
|Advanced||Select this check box to display the Script field.|
|Name||Enter the name of the object being secured, either the record name or the table and field names. The more specific the name is, the more specific the ACL rule is. You can use the wildcard character asterisk (*) in place of a record name, table name, or field name to select all objects that match a particular record type, all tables, or all fields. You cannot combine a wildcard character and a text search. For example, inc* is not a valid ACL rule name, but incident.* and *.number are valid ACL rule names.|
|Description||[Optional] Enter a description of the object or permissions this ACL rule secures.|
|Requires role||Use this list to specify the roles a user must have in order to access the object. If you list multiple roles, a user with any one of the listed roles can access the object. Note: Users with the admin role will always pass this permissions check because the admin role automatically grants users all other roles. The Requires role list appears as an embedded list starting with the Fuji release. In previous releases, it is a related list.|
|Condition||Use this condition builder to select the fields and values that must be true for users to access the object.|
|Script|| Enter a custom script describing the permissions required to access the object. The script can use the values of the current and previous global variables as well as system properties. The script must generate a true or false response in one of two ways:
In either case, users only gain access to the object when the script evaluates to true and the user meets any conditions the ACL rule has. Both the conditions and the script must evaluate to true for a user to access the object.
2.2 ACL Rules in Scoped Applications
Every ACL rule is assigned to either a unique scope or to the global scope (starting with the Fuji release). 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.
3 Granting or Denying Access
When a user attempts to access a particular object, the system searches for ACL rules that match the requested object's type, operation, and name. If an ACL rule matches these elements, then the user must meet the permissions described in this rule to access the secured object.
If the user fails to meet the permissions required by the first rule, the system searches for the next matching ACL rule. For each matching ACL rule, the user has a chance to meet the required permissions in order to access the object. The system stops searching for matching ACL rules if the user ever meets a matching ACL rule's permissions. If the user cannot meet the permissions of any matching ACL rules, the system denies the user access to the object.
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 could hide a field on a form, hide rows from a list, or prevent a user from accessing a particular UI page. See the table for a complete list of results of failing an ACL rule for a given operation and object type.
|Operation||Results of Failing an ACL Rule on Object|
|execute||User cannot execute scripts on record or UI page.|
|create||User cannot see the New UI action from forms. The user also cannot insert records into a table using API protocols such as web services. Note that a create ACL with a condition that a field contain a specific value always evaluates as false, as fields on new records are considered empty until 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 reports on the object.|
|personalize_choices||User cannot right-click a choice list field and select Configure Choices (Personalize Choices in versions prior to Fuji).|
3.1 Matching ACL Rules to Objects
Each object type has its own matching requirements.
|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:
||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.|
|Record|| Users must meet the permissions of two ACL rules:
||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.|
|Note: The high security property Security manager default behavior (glide.sm.default_mode) 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.|
3.2 Evaluating ACL Rule Permission Requirements
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.
4 Record ACL Rules
Record ACL rules consist of two parts:
- Table name: the table being secured. If other tables extend from this table, then the table is considered a parent table. ACL rules for parent tables apply to any table that extends the parent table.
- Field name: the field being secured. Some fields are part of multiple tables because of table extension. ACL rules for fields in a parent table apply to any table that extends the parent table.
ACL rules can secure the following record operations:
|execute||Allows users to run an application or script.|
|create||Allows users to insert new records (rows) into a table.|
|read||Allows users to display records from a table.|
|write||Allows users to update records in a table.|
|delete||Allows users to remove records from a table or drop a table.|
|edit_task_relations||Allows users to extend the Task table.|
|edit_ci_relations||Allows users to extend the Configuration Item [cmdb_ci] table.|
|save_as_template||Allows users to save a record as a template.|
|add_to_list||Allows users to insert records (rows) into a table from a list.|
|list_edit||Allows users to update records (rows) from a list.|
|report_on||Allows users to create reports on tables. This operation is not valid for field ACL rules.|
|personalize_choices||Allows users to configure the table or field.|
4.1 Processing Order for Record ACL Rules
Record ACL rules are processed in the following order:
This processing order ensures that users gain access to more specific objects before gaining access to less specific ones.
A user must pass both field and table ACL rules in order to access a record object.
- If a user fails a field ACL rule but passes a table ACL rule, the user is denied access to the field described by the field ACL rule.
- If a user fails a table ACL rule, the user is denied access to all fields in the table even if the user previously passed a field ACL rule.
4.1.1 Field ACL Rules
Field ACL rules are processed in the following order:
- Match the table and field name. For example, incident.number.
- Match the parent table and field name. For example, task.number.
- Match any table (wildcard) and field name. For example, *.number.
- Match the table and any field (wildcard). For example, incident.*.
- Match the parent table and any field (wildcard). For example, task.*.
- Match any table (wildcard) and any field (wildcard). For example, *.*.
The first matching evaluation stops ACL rule processing at that field level. This means that when a user passes or fails a field ACL rule, the system stops searching for matching field ACL rules below that level. For example, if there is a matching rule for the incident.number field, the system stops searching for matching field ACL rules such as task.number or incident.* because the user has already been granted or denied access to the field.
|Note: The user must also pass the table ACL rules to be granted access to the record object. For example, if a user passes the field ACL rule for incident.number, the system stops searching for field ACL rules, but the user must also pass any table ACL rules that match to the incident table.|
4.1.2 Table ACL Rules
In most cases there is not an individual field ACL rule for every field in the table the users is trying to access. If no field ACL rule matches the record object, the user must pass the table ACL rule. Since the base system includes wildcard table ACL rules that match every table, the user must always pass at least one table ACL rule. The base system provides additional table ACL rules to control access to specific tables.
Table ACL rules are processed in the following order:
- Match the table name. For example, incident.
- Match the parent table name. For example, task.
- Match any table name (wildcard). For example, *.
Just like with field ACL rules, the system grants the user access to the record object secured by the ACL rule and stops searching for matching ACL rules the first time a user passes a table ACL rule's permissions. A user who passes the table ACL rule for incident has access to all fields in the Incident table. A user who passes the table ACL rule for task has access to all fields in the Task table as well as the fields in extended tables. A user who passes the table ACL rule for any table has access to all fields in all tables.
4.2 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.
5 UI Page ACL Rules
UI page ACL rules specify the UI page to be secured. For a list of available UI pages, navigate to System UI > UI Pages.
|Note: You cannot use the wildcard * character in the Name field on ui_page type ACLs to match any UI pages. You must enter the exact name of the UI pages in the Name field on the Access Control form.|
ACL rules can secure the following UI page operations:
|execute||Allows users to run an application or script.|
|create||Allows users to insert new UI page records.|
|read||Allows users to display the UI page.|
|write||Allows users to update UI page records.|
|delete||Allows users to remove UI page records.|
|edit_task_relations||Allows users to extend the Task table.|
|edit_ci_relations||Allows users to extend the Configuration Item [cmdb_ci] table.|
|save_as_template||Allows users to save a UI page record as a template.|
|add_to_list||Allows users to insert UI page records from a list.|
|list_edit||Allows users to update UI page records from a list.|
|report_on||Allows users to create reports on UI page records.|
|personalize_choices||Allows users to configure UI page records.|
Because UI pages typically only display read-only information, the most common UI page ACL rule is for the "read" operation. For an example of limiting access to live feed with this type of rule, see Limiting Live Feed Access by Role.
6 Processor ACL Rules
ACL rules can secure access to the execute operation of all or specific processors. Processor ACL rules specify the processor you want to secure. Use the asterisk character as a wildcard to search for any processor. For a list of available processors, navigate to System Definition > Processors.
By default, an ACL rule for the EmailClientProcessor is included to restrict the email client to users with the itil role. See Enabling the Email Client for more information.
7 Client-Callable Script Include ACL Rules
ACL rules can secure access to the execute operation of all or specific client-callable scripts. Script include ACL rules specify the client-callable script include to be secured. Use the asterisk character as a wildcard to search for any client-callable script include. For a list of available script includes, navigate to System Definition > Script Includes. You can personalize the list to show the Client callable column.
The base system does not include any ACL rules for client-callable script includes.
The following ACL rule debugging tools are available:
To enable ACL rule debugging, navigate to System Security > Debug Security Rules.
|Note: Impersonation can simplify debugging ACL rules. First enable ACL debugging, then impersonate another user to see what ACL rules the user passes and fails.|
8.1 Field Level Debugging
8.2 ACL Rule Output Messages
ACL debugging displays ACL rule output messages at the bottom of each list and form. The output message was redesigned in the Eureka release to:
- Improve readability
- Include context information
- Show the results of each type of ACL test
- To provide hyperlinks to the ACLs that run on the list or form.
Each message displays the following information:
|TIME||The total time used to process this ACL rule.|
|PATH||Information that uniquely identifies each ACL rule in the format: <ACL rule type>/<ACL rule name>/<Operation>.|
|CONTEXT||The object being evaluated by the ACL rule. This element is available starting with the Eureka release.|
|RC||The return code of the ACL rule. A true value passes the ACL rule. A false value fails the ACL rule.|
|RULE|| A brief summary of processors and scripts, followed by ACL results for each table-level and field-level ACL evaluation. Most ACL evaluations show an overall pass or fail result followed by a breakdown of the results for each type of ACL criteria:
The icons that appear show how the ACL was evaluated:
Click the name of the ACL next to any of the output messages to open that ACL record.
Here is a list of common ACL rule errors and their solutions. Enable debugging to help troubleshoot an issue.
|Error or Symptom||Solution|
|You cannot access records from a custom table.||Create a table ACL rule for the custom table granting users access to the table. Without an explicit table ACL rule, users must pass the permissions in the table wildcard (*) ACL rule, which by default restricts access to administrators only. Enable debugging and determine what ACL rules are evaluated for the custom table.|
|You create a custom ACL rule that does not work properly.||The most likely problems are that another rule takes precedence over your custom rule in the processing order or that the user does not meet all the permission requirements for the object type. Enable debugging and verify that the ACL rule is being evaluated.|
|Your field ACL rule does not work properly.||There is likely a table ACL rule that the user has not met. Enable debugging and determine what ACL rules are evaluated for the field. Verify that there is not a conflicting table ACL rule or duplicate field ACL rule.|
|Your table ACL rule does not work properly.||There is either an ACL rule higher in the processing order or a duplicate table ACL rule interfering with the table ACL rule. Enable debugging and determine what ACL rules are evaluated for the table.|
|You can see a field in a list but not in form.||It is possible that the ACL rule conditions or script are being triggered in the list but not in the form. Enable debugging and determine when the ACL rules evaluate to true. Update the conditions or script to have the same behavior on the list and form.|
|You receive an error message when trying to execute a processor or client-callable script include||There is an ACL rule for the processor or client-callable script include that the user has not met. If the user should have access to the object, enable debugging and determine what ACL rules are evaluated for the processor or script include. Update the ACL rule or the user roles as needed to access the object.|
9.1 Controlling Whether Script Conditions Apply to Reference Fields
By default, ACL rules ignore the script conditions of a table's reference fields. The default behavior is intended to improve instance performance. If you want to enable script conditions for reference fields, add the following system property.
|glide.sys_reference_row_check|| Controls whether the script conditions of Access Control Rules apply to a table's reference fields.
- Security restraints are on database views. You need to create a read ACL for your users on the tables in a view to generate reports on database views. Non-admin users do not have access to database view records unless a read ACL on the database view record allows access.
- These changes support developing scoped applications:
- The Name field shows only objects that meet the scope protections for ACL rules.
- For tables that are in a different scope than the ACL rule, the types of rules are limited.
- The Application field is added on the form view.
- The list of required roles appears as an embedded list on the Access Control form, rather than as a related list.
- The ACL rule output message was redesigned to improve readability and show additional information.
- Administrators can click the name of triggered ACLs to access the Access Control record.