This section explains Daisy's document access control functionality. Access control concerns the authorization of document operations such as read and write.
While we usually talk about documents, technically the access control happens on the document variant level: a user is granted or denied access to a certain document variant.
In many systems, access to a document is configured by an access control list (ACL) associated with that document. An ACL consists of rules which define who (a user or role/group) can perform or not perform some operation.
For Daisy, it was considered to be too laborious to manage ACLs for each individual document. Therefore, there is one global ACL, where you can select sets of documents based on an expression and define the access control rules that apply to these documents.
The structure of the ACL is illustrated by the diagram below.
Thus, the ACL consists of number of "document selections", for each of which a number of access rules (the Access Control Entries) can be defined. In case of the read and write permissions, Access Details can contain finer-grained permissions to allow partial read access and partial write access to the document.
In the Daisy API, the "document selection" is called the ACL object. This is the general term for a protected resource. The subject is an entity wanting to perform an operation on the object. The objects in our case are documents, selected using an expression. The subjects are users (persons or programs acting on their behalf).
The Daisy ACL is evaluated entirely from top to bottom, later rules overwriting the result of earlier rules. The order of the entries is hence important. The evaluation of the ACL is described in detail below.
A document selection is defined by a Boolean expression, an expression evaluating to either true or false. During ACL evaluation, the document being evaluated will be checked against each of the expressions to see if it matches.
The expression uses the same syntax as in the where clause of the Daisy Query Language. However, the number of identifiers that are available is severely limited. More specifically, you can test on the following things:
Some examples of expressions:
InCollection('mycollection')
documentType = 'Navigation' and InCollection('mycollection')
$myfield = 'x' or $myotherfield = 'y'
For the evaluation of these expressions, the data of the fields in the last version is used, not the data from the live version.
An access control entry specifies that for a certain subject (a specific user or role, or everyone), what permissions the subject has on the document variant. The available permissions are:
In the access control entry, for each of these permissions you can specify that the user:
The read permission obviously gives users the ability to read a document.
When the read permission is granted, it can be further refined with a number of detail permissions:
The write permission gives users the ability to:
When the write permission is granted, it can be further refined with a number of detail permissions:
The publish permission gives users the ability to change the publish/draft state of versions of documents.
The delete permission gives users the ability to delete documents or document variants. This permission only applies to real deletes, not retirement (archival) of documents. In general, it is good practice to disable the delete permission, to avoid users deleting documents by accident.
In Daisy, there are two ACLs: a staging ACL and a live ACL. Only the staging ACL is directly editable. The only way to update the ACL is to first edit the staging ACL, and then put it live (= copy the staging ACL over the live ACL).
Before putting it live, it is possible to first test the staging ACL: you can give a document id, a role id and a user id and get the result of ACL evaluation in return, including an explanation of which ACL rules made the final decision.
In the Daisy Wiki front end, all these operations are available from the administration console. It is recommended that after editing the ACL, you first test it before putting it live, so that you are sure there are no syntax errors in the document selection expressions.
The determination of the authorization of the various operations for a certain document happens as follows:
If the user is acting in the role of Administrator, the user has full access permissions. The ACL is not checked.
If the user is owner of the document, the user always has read, write and delete permissions. Publish permission is still determined by the ACL.
If the document is marked as private and the user is not the owner of the document, all permissions are denied. The ACL is not checked.
The ACL evaluation result is initialized to deny all permissions (read, write, publish and delete), and the ACL is evaluated from top to bottom:
At the end of the ACL evaluation some further checks are performed:
About the evaluation of the read and write access details:
When saving an existing document, the ACL is evaluated twice:
In both cases, the ACL evaluation result should indicate that the user has write access.
The purpose of the first check is that, since the ACL evaluation result can depend on the content of the document (e.g. ACL-enabled fields and collection membership), a user could change those fields such that he gains write access to the document. Therefore we always require write access for both the old and new content.
For determining the write access details (= what properties of the document can be updated), we only look at the ACL evaluation result of the currently stored document. If we would also use the ACL evaluation result of the content that is being saved, then the updateable properties could actually depend on that content, which would make it hard to implement an editor frontend for such a document: as the user changes the content of the document, the properties that become editable might change.
In analogy with existing documents, for new documents the ACL is also evaluated twice:
In both cases, the ACL evaluation result should indicate that the user has write access.
As for existing documents, the write access details are determined by the result of the ACL evaluation on the conceptual document. The conceptual document here replaces the "previous document state" which does not exist in case of new documents.
In order to be able to write ACL rules which apply specifically to the conceptual document, a 'conceptual' property is available for use in ACL expressions which is true only for this special conceptual document. You can test on it using an expression like "conceptual = 'true'".
For basic usage, where you don't need fine-grained write access, you can just have a rule at the end of your ACL which defines that for all conceptual documents (expression "conceptual = 'true'"), you give everyone read and write access. You can define more specific rules by testing on the information available for the conceptual document: document type (this will be the most useful), branch and language. So a typical expression might look like "conceptual = 'true' and documentType = 'MyDocType'".
Up to Daisy version 2.2, there was a hardcoded rule that the document owner always has read/write/delete permissions. Starting from Daisy 2.3, you can use the 'owner' subject in the ACL to define yourself what permissions the owner gets, if needed.
The ACL is only concerned with authorization of permissions on documents. Other permissions, like who can manage users, change the ACL, create document types, etc... is simply managed via the predefined Administrator role: users acting in the Administrator role can perform all those operations, others can't.
This document only discussed authorization of operations on documents for legitimate users. Other aspects of security include: