Module access policy debugger

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 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 Module access policy debugger

    The Module Access Policy (MAP) debugger in ServiceNow helps you understand why users or scripts are granted or denied access to cryptographic modules used for encryption and decryption. MAPs enforce instance-level access controls to cryptographic modules, requiring explicit permissions for callers. The debugger provides detailed logs showing which policies are evaluated during an access request and the reasons behind the access decision.

    Show full answer Show less

    Key Features

    • Access Control for Debug Logs: Debug log access is restricted by roles. Users assigned snkmf.admin and snkmf.cryptographicmanager roles always have access. Additional roles can be granted access via the glide.kmf.moduleaccesspolicies.debugger.authorized.roles system property, which lists authorized roles in a comma-separated format.
    • Enable/Disable Debugger: Debug logging for module access policies can be enabled or disabled through the Session Debug interface under Diagnostics:
      • Enable via: All > Diagnostics > Session Debug > Debug Module Access Policies
      • Disable via: All > Diagnostics > Session Debug > Disable All
    • Viewing Logs: After enabling debugging, perform an action that triggers MAP evaluation. Logs appear at the bottom of the page showing detailed information about the cryptographic module, evaluated policies, and final access decisions.
    • Impersonation Support: You can troubleshoot access as other users by impersonating them. For this, ensure the MAPs associated with roles have the Impersonation field set to true to see logs from that user's perspective.
    • Log Structure and Icons: Debug logs list the cryptographic module being accessed, the MAPs evaluated (with name, type, target, operation, and result), and the final policy decision. Icons indicate message types such as informational messages, access granted or denied by policies, and overall caller access result.

    Practical Use and Benefits

    ServiceNow customers can use the MAP debugger to quickly identify and resolve access issues related to cryptographic modules, ensuring proper security controls are enforced while troubleshooting access denials. The tool clarifies which policies impact access decisions and supports role-based access to debugging logs, enhancing security and compliance.

    By understanding the log entries and enabling impersonation, administrators can simulate and diagnose access from multiple user perspectives, improving troubleshooting efficiency for encryption-related permissions.

    Use the module access policy debugger to review logging information and understand why your users are or aren’t granted access to an encryption context.

    Module access policies (MAPs) define instance-level controls for access to cryptographic modules. Callers (for example, a user or script) require explicit access in order to use a cryptographic module for encryption and decryption. It's not always clear which MAPs are evaluated when callers attempt to access a cryptographic module. Use the debugger to see which policies are evaluated when a caller attempts to access a cryptographic module, and learn why access is or isn’t being granted.

    This flowchart shows how your instance evaluates requests for access to a cryptographic module.

    Flowchart showing the how access to cryptographic modules are evaluated

    Control access to the debug logs

    Access to the module access debug logs is determined by role. Users with the sn_kmf.admin and sn_kmf.cryptographic_manager roles always have access to the debugger. Grant access to other roles using the glide.kmf.module_access_policies.debugger.authorized.roles system property. The value of this property is a comma-separated list of roles that access the debug logs.

    Enable or disable the debugger

    To enable debug logging messages for module access policies, navigate to All > Diagnostics > Session Debug > Debug Module Access Policies > .

    When you’re finished debugging, you can disable the logging messages by navigating to All > Diagnostics > Session Debug > Disable All > .

    Access the logs

    After enabling debugging, navigate to a page that triggers a MAP evaluation to view the MAP debug logs. Debug messages appear the bottom of the page.
    Tip:
    You can use impersonation to troubleshoot access for other users. For details on impersonation, see Impersonating users. To view the debug logs from the perspective of another user, make sure that your module access policies with the role type have the Impersonation field set as true.
    Example debug output

    In this example, a caller invokes two access requests to the global.fuji cryptographic module. A symmetric encryption, which is granted, and a symmetric decryption, which was denied.

    Understanding log entries

    Debugging information is structured using this format.

    1. This first line displays the cryptographic module receiving the access request.
    2. The lines between the first and last line displays the evaluated MAPs in the order that they were evaluated, and includes their name, type, target, granular operation, and result.
    3. The last line displays the Policy Decision (if applicable) and the net access result for the caller (whether the caller is granted access).

    Each line starts with an icon that indicates its message type.

    Table 1. Message icons
    Icon Message type
    Informational icon Informational message
    MAP grant access icon Module access policy grants access
    MAP deny access icon Module access policy denies access
    Caller grant access icon Caller is granted access
    Caller deny access icon Caller is denied access
    No MAP icon No module access policy to evaluate

    Debug log examples

    Access granted message
    Debugging output for granted access
    Access denied message
    Debugging output for denied access
    Access denied (No module access policies to evaluate
    Debugging output for denied access due to no MAP policies
    Access denied (insufficient privileges)
    Debugging output for denied access due to insufficient privileges