ACL debugging tools

  • Release version: Yokohama
  • Updated January 30, 2025
  • 3 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of ACL debugging tools

    ServiceNow provides ACL debugging tools to help you troubleshoot and debug access control lists (ACLs) effectively. These tools include field-level debugging indicators, detailed ACL rule output messages, and an ACL configuration watcher that identifies related ACLs when modifying one. This functionality enables you to understand why access is granted or denied and supports secure, precise configuration of ACLs.

    Show full answer Show less

    Field level debugging

    When enabled, a bug icon appears beside fields with ACL rules. Clicking this icon reveals which ACLs apply to the field and their evaluation results. To enable debugging, navigate to System Security > Debugging > Debug Security Rules.

    You can impersonate another user to view ACL evaluations from their perspective, seeing only what the user is permitted to access. By default, read-only access to ACL-related tables is granted even when impersonating users without such permissions, controlled by the system property glide.security.accessaclasimpersonator. Setting this property to false restricts this behavior, potentially requiring an admin session to debug ACLs.

    ACL rule output messages

    ACL debugging displays detailed output messages at the bottom of lists and forms, showing:

    • TIME: Duration to process the ACL rule.
    • PATH: Unique identifier of the ACL rule (type/name/operation).
    • CONTEXT: The object evaluated by the ACL.
    • RC (Return Code): True if ACL passes, false if it fails.
    • RULE: Summary of processors and scripts involved, including detailed results for each ACL evaluation step.

    ACL evaluations consider criteria such as internal system checks (IAccessHandler), roles, conditions, and scripts. The IAccessHandler represents non-modifiable, platform-level security checks that can override ACL evaluations.

    Icons and interactions

    Icons indicate ACL evaluation status:

    • Green checkmark (✔️): Passed criteria.
    • Red X (❌): Failed criteria.
    • Gray circle (⚪): Evaluation not performed.
    • Blue icons: Result retrieved from cache with the same meaning as above.

    From the ACL debug output, you can:

    • Toggle visibility of security rules or other warnings/messages using checkboxes.
    • Click ACL names in output messages to open and edit ACL records directly.
    • Hover over icons to view detailed information about each ACL check.

    Practical benefits for ServiceNow customers

    These ACL debugging tools provide transparency into how ACLs are evaluated, enabling you to quickly identify and resolve access issues. By understanding which ACLs affect specific fields or records and seeing detailed evaluation steps, you can fine-tune security configurations, ensure proper access controls, and maintain compliance with organizational policies.

    Field level debugging and access ACL rule output messages are available to help you troubleshoot and debug ACLs. The ACL configuration watcher lets you know what related ACLs exist when you modify one.

    Field level debugging

    When debugging is enabled, a small bug icon (Debug icon‎) appears beside each field with an ACL rule. Clicking the icon lists the ACL rules that apply for the field and the evaluation results. Enable debugging by navigating to System Security > Debugging > Debug Security Rules.

    Figure 1. Field level security on an incident
    Field level security on an incident

    After enabling ACL debugging, you can impersonate another user to see what ACL rules the user passes and fails. When you impersonate a user, you can only see what that user is allowed to see. For example, you cannot view a record that an ACL prevents the user from seeing. To make debugging easier, read-only access to certain ACL-related tables is enabled by default, even when impersonating a user that does not have read access to the tables. To change this functionality, set the following property to false.

    To enable ACL rule debugging, navigate to System Security > Debug Security Rules.

    System property Description Default setting
    glide.security.access_acl_as_impersonator Allows read access to the following tables while impersonating a user: sys_security_acl, sys_security_operation, sys_security_type, and sys_user_role. As a result, the impersonating user can read data that the impersonated user cannot read. true
    Note:
    When the property is set to false, the impersonated user might be prevented from reading ACL-related data. In this case, a second session logged in as admin or security_admin might be required to debug ACLs.

    ACL rule output messages

    ACL debugging displays ACL rule output messages at the bottom of each list and form. The output message displays the following:

    Message element Description
    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.
    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:
    • iAccessHandler: An internal system check using hidden source code on the platform. This is a system security check that you cannot modify. IAccessHandler can grant or deny access to a resource without evaluating ACLs. If IAccessHandler is ignored, then the ACLs are evaluated. You cannot modify the IAccessHandler checks in any way. For example, an IAccessHandler implementation is used for access checks on application resources and this cannot be changed.

      This is available starting with the Istanbul release.

    • Roles: Verification that the user has the correct role.
    • Condition: Verification that the user passed the condition specified on the ACL rule (if any).
    • Script: Verification that the user passed the script specified on the ACL rule (if any).

    The icons that appear show how the ACL was evaluated:

    Icon Description
    A green checkmark (Green checkmark‎) Indicates the table or field passed the criteria.
    A red x icon (Red x icon) Indicates the table or field did not pass.
    An empty gray circle icon (Grey circle icon‎) Indicates the ACL evaluation did not need to be performed.
    A blue checkmark, x, or empty circle Indicates that the ACL was taken from a cached result of a previous ACL check. The icons mean the same as the above.
    You can perform these actions on the ACL debug output:
    • Select or clear these check boxes at the top of the debug output:
      • Security rules: Show or hide the results of the ACL checks.
      • Others: Show or hide other warnings or messages.
    • Click the name of the ACL next to any of the output messages to open that ACL record.

      Click the ACL link

    • Hover the cursor over any of the icons for the four ACL checks to see more information.

      Hover over an ACL check mark