Access Control

Introduction

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 what 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.

Structure of the ACL

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. For the special case of the read permission, Access Details can contain finer-grained permissions to allow partial read access to the document. Partial write access is currently not supported.

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.

Document selection

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:

• the document type
• collection membership (using the InCollection function)
• document ID (to have rules specific to one document)
• fields for which the ACL-allowed flag of the field type is set to true
• the branch and language

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.

Access Control Entry

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:

• read (+ detail permissions)
• write
• publish
• delete

In the access control entry, for each of these permissions you can specify that the user:

• should be granted the permission
• should be denied the permission
• or that the permission should be left to its current state

read permission

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:

• can versions other than the live one be read (= can non-live versions be read). If not, this also implies the following limitations:
• the list of versions cannot be retrieved
• access to retired documents is denied (regardless of whether they have a live version)
• can all fields be read. If not, a list of accessible fields can be specified.
• can all parts be read. If not, a list of accessible parts can be specified.
• can the fulltext index be read. If not, this document will not be returned in queries containing a FullText condition.
• can fulltext index context fragments be retrieved. If one is allowed to perform fulltext searches (= if the fulltext index can be read), this option can be used to prohibit that the user can see context fragments. Context fragments are small parts of content around matching words.
• can the document summary be read.

write permission

The write permission gives users the ability to:

• create documents
• update (save) documents
• take a lock on the documents

publish permission

The publish permission gives users the ability to change the publish/draft state of versions of documents.

delete permission

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.

Staging and Live ACL

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.

Evaluation of the ACL: how is determined if someone gets access to a document

The determination of the authorization of the various operations for a certain document happens as follows:

1. If the user is acting in the role of Administrator, the user has full access permissions. The ACL is not checked.

2. 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.

3. 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.

4. The ACL evaluation result is initialized to deny all permissions (read, write, publish and delete), and the ACL is evaluated from top to bottom:

• If a document selection expression evaluates to true for the document, each of the child access control entries are evaluated, as follows:
• If the subject type and subject value of an access control entry apply to the current user, the permissions defined in that entry override the previous ACL evaluation results.
• The evaluation of the ACL does not stop at the first matching expression or subject, but goes further till the bottom. Thus later rules overwrite the result of earlier rules.

5. At the end of the ACL evaluation some further checks are performed:

• if the user does not have read permission, the write, delete and publish permissions are denied too
• if the user does not have write permission, the delete permission is denied too (but not the publish permission).

About the evaluation of the read access details:

• The read detail permissions behave pretty much like the normal permissions: they can have three states (grant, deny, leave) which overwrite the existing result. If there is no earlier existing result, grant is taken as the initial state for the detail permissions (in contrast to the normal permissions, where it is deny).
• If there is a grant with access details, and later another grant with some other details, the later details overwrite the earlier details.
• If there is grant with access details, followed later on by a deny, the deny will cause the existing access details to be reset. If the deny is later followed again by a grant, the default will be again that all detail permissions are granted.

Further notes:

• when saving a document, the ACL is always checked on the document currently stored, not on the newly edited document (unless it is a new document). This is because the ACL evaluation result can depend on the value of fields, and the user might have edited those fields to try to gain access to the document.

• A user cannot change a document in such a way that the user itself has no write permission anymore to the document, e.g. by changing collection membership or field values.

Common pitfalls

If you change the ACL so that a certain user or role is denied some permission, and you notice that you still have those permissions when logged in with that user or role, than this is likely because the user is the owner of the document. Document owners always have access to the document, regardless of the ACL (see also the description of the ACL evaluation process).

Controlling who can manage users, ACL, document types, ...

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.

Other security aspects

This document only discussed authorization of operations on documents for legitimate users. Other aspects of security include:

• authentication: see User Management
• audit logging: since Daisy generates JMS events for all (write) operations happening on the repository, you could get a full audit log by logging all these events. The content of these events are XML descriptions of the changes (usually an XML dump of the entity before and after modification)
• physical protection of the data: if someone can access the filesystem on which the parts are stored, or the relational database, they can see and/or modify anything
• integrity: hasn't anyone been altering the data before delivery to the user. Here the use of https can help.