<h2>Access control list rules</h2><br/><div style="overflow-x:auto"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta content="text/html; charset=UTF-8" /><meta name="copyright" content="(C) Copyright 2024" /><meta name="DC.rights.owner" content="(C) Copyright 2024" /><meta name="generator" content="DITA-OT" /><meta name="DC.type" content="concept" /><meta name="DC.title" content="Access control list rules" /><meta name="abstract" content="Rules for access control lists (ACLs) restrict access to data by requiring users to pass a set of requirements before they can interact with it." /><meta name="description" content="Rules for access control lists (ACLs) restrict access to data by requiring users to pass a set of requirements before they can interact with it." /><meta name="DC.subject" content="access control, access controls, ACL, ACLs, contextual security" /><meta name="keywords" content="access control, access controls, ACL, ACLs, contextual security" /><meta name="DC.relation" scheme="URI" content="../../../administer/reference-pages/concept/platform-security-landing-page.html" /><meta name="DC.relation" scheme="URI" content="../../../administer/contextual-security/concept/acl-rule-types.html" /><meta name="DC.relation" scheme="URI" content="../../../administer/contextual-security/concept/acl-function-fields.html" /><meta name="DC.relation" scheme="URI" content="../../../administer/contextual-security/task/t_CreateAnACLRule.html" /><meta name="DC.relation" scheme="URI" content="../../../administer/roles/reference/r_ContextualSecurity.html" /><meta name="DC.relation" scheme="URI" content="../../../administer/contextual-security/concept/acl-advanced-config.html" /><meta name="DC.creator" content="ServiceNow" /><meta name="DC.date.created" content="2023-02-02" /><meta name="DC.date.modified" content="2023-02-02" /><meta name="DC.format" content="XHTML" /><meta name="DC.identifier" content="access-control-rules" /><link rel="stylesheet" type="text/css" href="../../../CSS/commonltr.css" /><title>Access control list rules</title></head><body id="access-control-rules"> <h1 class="title topictitle1" id="ariaid-title1">Access control list rules</h1> <div class="body conbody"><p class="shortdesc"><span class="ph">Rules for access control lists (ACLs) restrict access to data by requiring users to pass a set of requirements before they can interact with it.</span></p> <div class="section"><h2 class="title sectiontitle">Components of ACLs</h2> <div class="p">All access control list rules specify:<ul class="ul" id="access-control-rules__ul_llr_5q3_yv"><li class="li">The object and operation being secured</li><li class="li">The permissions required to access the object</li></ul> </div> </div> <div class="section"> <p class="p">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.</p> <p class="p">For example, all these entries specify an object:</p> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="access-control-rules__table_mlr_5q3_yv" class="table" frame="border" border="1" rules="all"><colgroup><col /><col /><col /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e115">Type</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e118">Name</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e121">Object secured</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e115 ">record</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e118 ">[incident].[-- None --]</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e121 ">The Incident table.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e115 ">record</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e118 ">[incident].[active]</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e121 ">The Active field in the Incident table.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e115 ">REST_Endpoint</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e118 ">user_role_inheritance</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e121 ">The record for the user_role_inheritance Scripted REST API.</td></tr></tbody></table> </div> </div> <div class="section" id="access-control-rules__section_t52_w4x_ktb"> <p class="p">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.</p> <p class="p">For example, all these entries specify an operation:</p> </div> <div class="section" id="access-control-rules__section_u52_w4x_ktb"> <div class="p"> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="access-control-rules__table_zqf_2qx_ktb" class="table" frame="border" border="1" rules="all"><colgroup><col /><col /><col /><col /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e202">Type</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e205">Name</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e208">Operation</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e211">Operation secured</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e202 ">record</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e205 ">[incident].[-- None --]</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e208 ">create</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e211 ">Creating records in the Incident table.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e202 ">record</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e205 ">[incident].[active]</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e208 ">write</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e211 ">Updating the Active field in the Incident table.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e202 ">REST_Endpoint</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e205 ">user_role_inheritance</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e208 ">execute</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e211 ">Running the user_role_inheritance scripted REST API.</td></tr></tbody></table> </div> </div> </div> <div class="section"> <div class="p">The permissions specify when someone can access the named object and operation. Security administrators can specify permission requirements by adding:<ul class="ul" id="access-control-rules__ul_olr_5q3_yv"><li class="li">One or more user roles to the <span class="ph uicontrol">Requires role</span> list.</li><li class="li">One or more conditions.</li><li class="li">A script that evaluates to true or false or sets the <code class="ph codeph">answer</code> variable to true or false.</li></ul> </div> <p class="p">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.</p> <p class="p"><img class="image" id="access-control-rules__image_hbb_hm4_vw" src="../image/access-control-record-write-incident2.png" alt="ACL on an incident record." /></p> <p class="p">To update a record in the incident table, a user must have the listed roles and the record must meet the condition.</p> <div class="p"> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="access-control-rules__table_n55_qsx_ktb" class="table" frame="border" border="1" rules="all"><colgroup><col /><col /><col /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e321">Permission type</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e324">Requirement</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e327">Description</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e321 ">Requires role</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e324 "><span class="ph uicontrol">Requires role</span>:itil</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e327 ">Only allow users with the itil role to update incidents.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e321 ">Condition</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e324 ">[Incident state] [is not] [Closed]</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e327 ">Only allow updates to active incident records.</td></tr></tbody></table> </div> </div> </div> <div class="section" id="access-control-rules__section_eng_4nn_x5b"><h2 class="title sectiontitle">ACL evaluation process</h2> <p class="p">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.</p> <ul class="ul" id="access-control-rules__ul_cjg_b22_2r"><li class="li">The condition must evaluate to <span class="keyword option">true</span>.</li><li class="li">The script must evaluate to <span class="keyword option">true</span> or return an answer variable with the value of <span class="keyword option">true</span>.</li><li class="li">The user must have one of the roles in the required roles list. If the list is empty, this condition evaluates to <span class="keyword option">true</span>.</li><li class="li">[Record ACL rules only] The matching table-level and field-level ACL rules must both evaluate to <span class="keyword option">true</span>.</li></ul> <div class="p"><div class="fig fignone" id="access-control-rules__fig_jqy_f22_2r"><span class="figcap"><span class="fig--title-label">Figure 1. </span>ACL evaluate permissions</span> <img class="image" id="access-control-rules__image_a41_322_2r" width="400" src="../image/AclEvaluatePermissions2.png" alt="ACL evaluate permissions" /> </div> </div> <p class="p">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.</p> <div class="p">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.<div class="note"><span class="notetitle">Note:</span> 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.</div> </div> <p class="p">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.</p> </div> <div class="section" id="access-control-rules__section_fng_4nn_x5b"><h2 class="title sectiontitle">Pre and post query ACL checks</h2> <div class="p">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.<dl class="dl"><dt class="dt dlterm">Pre-query ACL check</dt><dd class="dd"><p class="p">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.</p> <p class="p">If the user doesn't have read access at this point, the value for the field is not shown to the user.</p> </dd><dt class="dt dlterm">Post-query ACL check</dt><dd class="dd"><p class="p">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.</p> </dd></dl> </div> </div> <div class="section" id="access-control-rules__section_sps_pnn_x5b"> <div class="p"> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="access-control-rules__table_evh_h12_2r" class="table" frame="border" border="1" rules="all"><colgroup><col /><col /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e478">Operation</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e481">Results of failing an ACL rule on object</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">execute</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot execute scripts on a record or UI page.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">create</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot see the <span class="ph uicontrol">New</span> UI action from forms. The user also cannot insert records into a table using API protocols such as web services.<p class="p">A <span class="ph uicontrol">create</span> ACL with a condition requiring that a field contain a specific value always evaluates as false. Fields on new records are considered empty until the record is saved.</p> </td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">read</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot see the object in forms or lists. The user also cannot retrieve records using API protocols such as web services.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">write</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User sees a read-only field in forms and lists, and the user cannot update records using API protocols such as web services.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">delete</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot see the <span class="ph uicontrol">Delete</span> UI action from forms. The user also cannot remove records from a table using API protocols such as web services.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">edit_task_relations</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot define relationships between task tables.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">edit_ci_relations</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot define relationships between Configuration Item [cmdb_ci] tables.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">save_as_template</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">Used to control the fields that should be saved when a template is created.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">add_to_list</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot view or personalize specific columns in the list mechanic.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">list_edit</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot update records (rows) from a list.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">report_on</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot create a report on the ACL table. For more information, see <a class="xref" href="../use/reporting/task/t_RestrictRepCreationWAnACLRule.dita/t_RestrictRepCreationWAnACLRule.html" target="_blank" rel="noopener noreferrer">Restrict report creation with an ACL rule</a>.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">report_view</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot view the content of a report on the ACL table or on the ACL field. For more information, see <a class="xref" href="../use/reporting/task/t_RestrictRepCreationWAnACLRule.dita/t_RestrictRepCreationWAnACLRule.html" target="_blank" rel="noopener noreferrer">Restrict report creation with an ACL rule</a>.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e478 ">personalize_choices</td><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e481 ">User cannot right-click a choice list field and select <span class="ph uicontrol">Configure Choices</span>.</td></tr></tbody></table> </div> </div> </div> <div class="section" id="access-control-rules__section_uyl_4g4_l1b"><h2 class="title sectiontitle">ACL matching requirements for objects</h2> <div class="p"> <div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="access-control-rules__table_bcz_vb2_2r" class="table" frame="border" border="1" rules="all"><colgroup><col style="width:33.33333333333333%" /><col style="width:33.33333333333333%" /><col style="width:33.33333333333333%" /></colgroup><thead class="thead" style="text-align:left;"><tr class="row"><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e653">Object Type</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e656">Matching ACL Rules Required to Access Object</th><th class="entry cellrowborder" style="vertical-align:top;" id="d296843e659">Existing Wildcard ACL Rules</th></tr></thead><tbody class="tbody"><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e653 ">Client-callable script includes</td><td class="entry cellrowborder" rowspan="2" style="vertical-align:top;" headers="d296843e656 ">Users must meet the permissions of two ACL rules:<ol class="ol" id="access-control-rules__ol_jrf_lc2_2r"><li class="li">All wildcard ACL rules for the object (if any ACL rule exists for the operation).</li><li class="li">The first ACL rule that matches the object's name (if any ACL rule exists for the operation).</li></ol> </td><td class="entry cellrowborder" rowspan="2" style="vertical-align:top;" headers="d296843e659 ">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.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e653 ">Processors</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e653 ">UI pages</td><td class="entry cellrowborder" rowspan="2" style="vertical-align:top;" headers="d296843e656 ">Users must meet the permissions of two ACL rules:<ol class="ol" id="access-control-rules__ol_jfb_pc2_2r"><li class="li">The first ACL rule that matches the record's field (if any ACL rule exists for the operation).</li><li class="li">The first ACL rule that matches the record's table (if any ACL rule exists for the operation).</li></ol> </td><td class="entry cellrowborder" rowspan="2" style="vertical-align:top;" headers="d296843e659 ">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.</td></tr><tr class="row"><td class="entry cellrowborder" style="vertical-align:top;" headers="d296843e653 ">Record</td></tr></tbody></table> </div> </div> <div class="p"><div class="note"><span class="notetitle">Note:</span> The Security manager default behavior (<span class="keyword apiname">glide.sm.default_mode</span>) property determines whether users can access objects that only match against wildcard table ACL rules. When this property is set to <span class="keyword option">Deny access</span>, only administrators can access objects that match the wildcard table ACL rules.</div> </div> <div class="p"><div class="note"><span class="notetitle">Note:</span> 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.</div> </div> </div> <div class="section" id="access-control-rules__section_b3r_dtk_t1b"><h2 class="title sectiontitle">Multiple ACL rules at the same point in the processing order</h2> <p class="p">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 <span class="keyword parmname">incident.number</span>, 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.</p> </div> <div class="section"><h2 class="title sectiontitle">Required role</h2> <p class="p">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 <a class="xref" href="../../security/task/t_ElevateToAPrivilegedRole.html" title="The base system admin can elevate to a privileged role to have access to the features of High Security Settings.">Elevate to a privileged role</a> for instructions.</p> </div> <div class="section" id="access-control-rules__section_sfv_mgn_l1b"><h2 class="title sectiontitle">ACL rules in scoped applications</h2> <p class="p">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.</p> <div class="p">For tables that are in a different scope than the ACL rule record, the types of rules are limited.<ul class="ul" id="access-control-rules__ul_msq_zyd_2r"><li class="li">You can create an ACL rule for any table, UI page, or other object that is in the same scope as the ACL rule.</li><li class="li">You can create an ACL for a field that is in the same scope as the ACL rule.<ul class="ul" id="access-control-rules__ul_fxr_1zd_2r"><li class="li">If the table is in the same scope, you can use a script to evaluate permissions.</li><li class="li">If the table is in a different scope, you cannot use a script to evaluate permissions.</li></ul> </li><li class="li">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.</li><li class="li">You can create wildcard table rules (*) only in the global scope.</li><li class="li">You can create wildcard field rules (*) only for tables in the same scope as the ACL rule.</li></ul> </div> </div> </div> <div class="related-links"> <ul class="ullinks"><li class="link ulchildlink"><strong><a href="../../../administer/contextual-security/concept/acl-rule-types.html">ACL rule types</a></strong><br /> Create ACL rules on different components of the system.</li><li class="link ulchildlink"><strong><a href="../../../administer/contextual-security/concept/acl-function-fields.html">ACL control of function fields</a></strong><br /> When evaluating access to a function field, in addition to checking access to the function field itself, the system also checks access to the function's contributing fields. Contributing fields are those used as the arguments in a given function definition.</li><li class="link ulchildlink"><strong><a href="../../../administer/contextual-security/task/t_CreateAnACLRule.html">Create an ACL rule</a></strong><br /> Create a custom ACL rule to secure access to new objects or to change the default security behavior.</li><li class="link ulchildlink"><strong><a href="../../../administer/roles/reference/r_ContextualSecurity.html">Contextual Security Manager</a></strong><br /> Contextual Security Manager protects your data by controlling read, write, create, and delete authorization.</li><li class="link ulchildlink"><strong><a href="../../../administer/contextual-security/concept/acl-advanced-config.html">Advanced ACL configuration</a></strong><br /> In addition to creating new ACLs or modifying existing ones, you can configure other aspects of ACL functionality.</li></ul> <div class="familylinks"> <div class="parentlink"><strong>Parent Topic:</strong> <a class="link" href="../../../administer/reference-pages/concept/platform-security-landing-page.html" title="Secure your instance, encrypt your data, authenticate users, and view your current compliance levels based on application security standards.">Secure your instance</a></div> </div> </div></body></html></div>