Basics of Permissions for Knowledge Components
Understanding the Process of Determining Access
Although seemingly complicated, access control lists in SQI's knowledge components can be easy to use if you understand a few key points about how the knowledge components determine access. The purpose of this article is to explain the basics of permissions and how these permissions work.
What are Access Control Lists?
Access Control Lists are lists of instructions that tell an application how to control access to resources. Look at this example for an example of an access control list for SQI's knowledge components:
In this example, the TrustedGroup can read and write this page. As well, everyone else (All) can read this page. Although this seems simple enough, order is also very important.
How ACLs Are Read
One thing that can make ACLs confusing is that order is very important. Let's expand on our example above, except in reverse order:
Now, contrary to some might think, TrustedGroup no longer has write permissions! Why is this? To understand, lets look at the anatomy of an ACL:
All:read TrustedGroup:read,write --(1)--- --(2)------- --(3)-----
When ACLs are read, they are read "left to right" and stop processing on the first match. Each rule is read and the User Identifier is checked to see if it matches the current user. If it is, then the Rules are checked to see if it contains the Right requested. In our first example, TrustedGroup was mentioned first. This means that a user that was in the TrustedGroup matched the first rule. Since the first rule contained the write Right, the user would be able to write to the page. However, since All matches everyone, including anyone in the TrustedGroup, processing stops at that rule and permissions are checked there. Since the write Right was not specified, the user does not get to write to the page, regardless of their membership in the TrustedGroup.
You may find yourself needing to specify that a person or group of people have a certain right, but without taking away all their other rights. Conversely, you may also need take away a certain right, but not all of them. This is where Rule Modifiers come in.
Let's look at our example above, but allowing everyone to read.
As you can see, we added the + sign in front of All. This tells the ACL processor to read the rule, but continue if there are not any matches. This way, the write permission is not removed.
But what if you wanted to take everyone's ability to write to the page? In the following example, we remove the write permission from everyone.
This time, we added the - sign in front of All. This tells the ACL processor to read the rule. If the rule matches, then deny the request. If the rule does not match, the processor will continue on.
We have been using a group above (TrustedGroup) in our examples. Now we will explain how groups work and how to create your own.
There are many cases where using groups in ACL rules are very effective. For example, the TrustedGroup is a group of users that we allow to make edits to most of our pages. By using a group, we do not have to modify every page that has special permissions whenever a person is added or removed from this group.
Creating and Managing Groups
Creating a group is quite easy. Essentially, a group is a Page that ends with Group. Example groups might be:
Group pages can be subpages, which is quite useful when there is a structured set of documents and there are different editing teams.
Here is an example of the TrustedGroup:
#acl TrustedGroup:read,write,admin All:read * bob * jill * eric
In this example, we have three users: Bob, Jill and Eric. Each username must be prepended by '[space]*[space]' like a normal first level wiki list. There is also a Page ACL Declaration that allows the TrustedGroup to write and admin this page. The write permission allows users to be added and removed from the group by editing the list in the page. The admin permission allows the page permissions to be changed. The last rule allows everyone to see the group, but prevents anyone else from modifying the page. For more information on the Page ACL Declaration, please see Page Permissions for Knowledge Components.