4.9.3 Evaluation of the ACL: how document permissions for someone are determined

4.9.3.1 ACL evaluation algorithm

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.
• If the subject type is owner and the document is new, then the rule will be skipped. New documents are not considered to be owned.
• 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).
• if the users only has partial read permission, he can still have write permission, but the write permission details should be a subset of the read permission details (mainly the accessible fields and parts). If the read access details define that the user only has read access to the live version, write access will be denied.

About the evaluation of the read and write access details:

• The 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 (= merge with) 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.

4.9.3.2 How the ACL is used when saving an existing document

When saving an existing document, the ACL is evaluated twice:

• once on the currently stored document (using the data from its last version)
• once on the document content that is being saved

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.

4.9.3.3 How the ACL is used when saving a new document

In analogy with existing documents, for new documents the ACL is also evaluated twice:

• once on a blank (empty) so-called conceptual document, for which only the document type, branch and language are known
• once on the new document that is being saved

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'".