Initial Situation
Do you know that scenario? Your ServiceNow instance has been running for a while, and the situation has become much more complex since the initial go-live:
- Many new requirements have been raised and several of them have not created any real added value, but only serve to fulfil the many regulations and specifications.
- Another ServiceNow module was added to support more use cases and processes for another department which also wants to benefit from the great platform.
- The original development team was closed down. Instead, the operations team has taken on smaller development tasks and, over time, several external resources have been engaged to develop larger work packages.
- There is no comprehensive documentation of the requirements for security and access to individual tables.
The result is a zoo of several hundred ACL fleas and nobody is there to tame them. And then disaster strikes. A new developer, who was unaware of the history, makes a small change to an existing ACL and suddenly many users no longer have access to certain data. However, this only becomes apparent after deployment to the PROD, as tests are only carried out manually and in isolated cases. A huge wave of escalation rolls through the company and workarounds are implemented on PROD in a cloak and dagger operation to make the blocked data accessible again.
The management is now asking itself what needs to be done to avoid such a situation in the future. I think most people have experienced this or something similar, and I too have always wondered how the very complex issue of ACLs can be better controlled.
This article and the following one will provide a possible solution to that question, however I'm not saying it's perfect. Instead, it is the result of many hours of trial and error in order to create something that is as easy to understand as possible and can be continued by other users.
Start regaining controls by documenting all ACLs
One of my most important superpowers is bringing order to chaos and I'm going to let you in on a secret: it's not actually a superpower at all, it's just following a strict series of simple steps. If you stick to it, you too can soon go on tour with your own flea circus:
- Record the ACTUAL state.
- Determine the TARGET state.
- Define all steps required to transition from ACTUAL state to the TARGET state.
- Put the plan into action.
- Ensure that the TARGET state will remain stable in the future.
Main aspects to consider when starting a documentation
Whichever documentation medium you use, it should fulfil the following conditions:
- It must be web-based:
If you want to spread chaos quickly and safely, write documentation using some offline text tool and then send the resulting file as an email attachment to a large number of recipients with a request for additions. Leveraging web-based tools that use unique URLs to address content is therefore mandatory. This alone represents the only source of truth. - It must have WYSIWYG capabilities:
Writing extensive documentation using Markdown or similar is something for absolute nerds, and quickly reaches its technical limits. The design of complex tables in particular only makes sense with a WYSIWYG editor. - It should allow for collaboration on a single document or page:
In today's predominantly remote working world, editing in parallel and together the same document or page is extremely practical and can speed up collaboration processes enormously. - It should be versioned:
If many users make repeated changes to a page over a longer period of time, it is very helpful to have a version history available that allows you to compare multiple versions or even restore a previous version.
My Solution
I'm a huge fan of the web-based Wiki product Confluence from Atlassian, and I've been working with that enterprise documentation & collaboration tool since over 15 years. It started as a business pendant to the well-known Wikipedia, but today there is hardly anything left to remind us of its early days. I cannot imagine any more doing a project without Confluence (and Jira for ticketing) and many of my customers also use it. That's why it made sense to rely on Confluence, but without the relevant experience, you will very quickly give up frustrated when trying to document ACLs.
For a better understanding, I will start with the result and then go into more detail later on. The following table represents all ACLs on the sys_table in our customer instance:
Formal aspects
One table to rule them all
The first thing you probably will notice: the table is gigantic, and if your monitor doesn't have the respective resolution you have to scroll in any case, both horizontally and vertically.
Of course there are approaches of breaking down that table into several smaller chunks (for example one table for each field or each persona) however, the transparency and clear relationships between the individual dimensions are lost in this way. On the other hand, a table has natural limitations, and you need a lot of creativity to map more than two dimensions.
Support understanding with coloring
Even without zooming in, you can recognize different colors - either background colors for table cells (one of the rare options for background colors in Confluence) or text colors (only red in my case). Colors are important to provide the eye with support, especially in multidimensional data structures. However, you shouldn't overdo it, because too many colors overload the brain. Apart from the dark gray background color for table headline rows/columns, you should not use more than 3 different background colors. I'm even more economical when it comes to text colors, and I usually don't use any other text color other than red to highlight an exception or error.
Support understanding with icons
In Confluence you have a restricted palette of icons available, and I use them as often as possible and carefully. Icons are a strong eye-catcher and can help to grasp core statements of complex data structures quickly and at a glance. And here too, consistency in their use and economy are the top priority.
Support understanding with legends
Whatever kind of presentation and formatting sophistication you come up with, you have to explain it. You can't expect everyone to have the same understanding as you. It may even be the case that, depending on their background, training or experience, the readers of your documentation have completely different expectations or ideas about a graphic element or a special text formatting. That's why a legend is always mandatory for documentation or visualizations of all kinds. And where you offer the legend to your readers is also important. Don't see it as an unpleasant stepchild that needs to be relegated to the bottom right corner. Instead, always place a legend at the beginning. In this way you give the reader the dictionary that they need to understand the following documentation.
Content-related aspects
Consider different personas
User personas are fictional but realistic characters that represent an entire group or audience with a set of traits and characteristics that unite them. User personas are role based and focused on responsibilities. These personas identify who your users are, what behavior patterns they currently exhibit, their needs and goals, and the issues or pain points they currently face within a given context.
Access to any data should always be designed based on defined personas, which is why these represent the next dimension level after the tenant dimension.
Consider different & unique scenarios per persona
If necessary, different scenarios can be distinguished for each persona. This is particularly necessary for the sys_user table, because it makes a difference whether I call up my own record or that of another user.
As you can see in the following screenshot, each scenario has its individual ID (for example "T01-P01-S01"). This way it can be referenced on other pages or in any tests.
Document completely and independently in each cell
Now let's get to the most important part: the actual content:
You will probably notice two things straight away:
- the use of Sys IDs as a reference and
- the high level of redundancy.
The Sys IDs belong to the underlying ACL records and are offered as links to them. Admittedly, setting up the links is quite time-consuming, but it certainly justifies the effort. And the massive use of Sys IDs spreads out a table enormously, but ACLs have no better unique identifier. The ACL sys_user.* can occur any number of times and is therefore not very helpful. The use of Sys IDs has another advantage: If you come across a Sys ID in a completely different context, you can easily use the text search built into the browser to check on a web page whether and where the underlying ACL is used.
And regarding redundancy: What would be the alternative? Connect several cells together to document the ACLs only once? This has two major disadvantages. When scrolling around on the page, you would permanently lose sight of the ACL definitions and would have to make them visible again by further scrolling. And if the ACLs are rebuilt later, the merged cells would have to be split up again, which causes unnecessary work.
But how to identify the required information?
You may now be wondering how you can find out the information you need with as little effort as possible. Unfortunately, there is no good answer. In the end, it's a hell of a lot of work to go through field by field, persona by persona, and check whether a certain ACL grants or denies certain rights.
The most important prerequisite is a deep understanding of the ACL concept and its rules.
The best but also the most demanding tool for vizualizing the appliance of ACLs is the ACL debugger. It provides detailed insights in all involved ACLs when accessing a record. The problem with this overwhelming view is the lack of Sys IDs in the hyperlink texts to the ACLs. This makes it very time-consuming to compare and complete the documentation. For this reason I developed a small script which adds the Sys IDs inside the ACL hyperlinks:
To get the same open the developer tools of your browser (Ctrl+Shift+I or F12) and
- Open the "Console" tab
- Select "gsft_main" to perform the script in the main area of the UI
- Paste the following script into the main console window and hit ENTER
jQuery('#debug_messages a[href^="/sys_security_acl.do"]').each(function() { var _arrParts = jQuery(this).attr('href').split('sys_id='); if (Array.isArray(_arrParts) && _arrParts.length === 2) { jQuery(this).append(' ' + _arrParts[1]); } });Now in all hyperlinks to ACL records the respective Sys IDs should be visible.
Since the Vancouver Release ServiceNow provides the so-called Access Analyzer which generates a more user-friendly and comprehensible presentation. However, this tool also has its limitations. In particular, if ACL scripts are involved, a clear assignment to the ACLs involved cannot be guaranteed.
But you can also look at it from the other end. The GlideRecord and the GlideElement APIs offer methods that reflect the result of all ACL calculations. For example, you can call methods such as canRead() or canWrite() not only at row level but also at field level. Combined with script-based impersonation, you can generate quick and easy reports.
In the following script example an impersonation with a test user is performed. And that impersonated user then tries to access its own sys_user record (aka Profile).
That approach will play an important role in the third part of that article series which is about regression testing to make sure, existing ACLs are not broken.
Conclusion
Analysing and documenting the existing ACL fleas is an admittedly time-consuming activity, but an essential prerequisite for defining the transition to the target state. Once this documentation exists, you have a good basis for discussions about the security of your application and the capabilities that the personas involved may have.
In the second part of that series I'm going to demonstrate how to document and perform all required changes on the road to the target state.
