Access Control

Contendo Server provides a flexible access control mechanism to manage permissions on objects within the repository. Permissions determine what actions users can perform on objects, such as reading, writing, or deleting content. Access control in Contendo Server is based on Access Control Lists (ACLs), which define permissions for specific users or groups.

Access Control Mechanism

Access Control in Contendo Server is configured by setting a Access Control List (ACL) on the object that needs to have limited access. If not ACL is set, there are no limitations - any user can read or write to the object.

An ACL is a set of ACE (Access Control Entries).
Each ACE consists of:
- A principal (a user ID or a group).
- A set of permissions granted or denied to that principal.

Group-Based Access Management

Contendo Server supports groups, allowing users to be assigned to one or more groups. Instead of assigning permissions directly to users, ACLs should reference groups whenever possible. Managing groups (creating, deleting, adding users) is covered in Groups Management.

Permission Model

Contendo Server supports three permissions:

Permission	Description
`cmis:read`	Allows reading an object's properties and content.
`cmis:write`	Allows modifying an object's properties and content.
`cmis:all`	Grants full control over the object.

Inheritance

ACLs must be explicitly defined on an object; permissions are not inherited from its parent.

JSON Format

ACLs in Contendo Server are represented by a structured JSON format. An object's ACL consists of an aces array, where each ACE defines a principal and permissions array.

JSON representation example:

{
  "aces": [
    {
      "principal": "viewer",
      "permissions": [
        "cmis:read"
      ]
    },
    {
      "principal": "maintainer",
      "permissions": [
        "cmis:write",
        "cmis:write"
      ]
    }
  ]
}

Managing Access Control

Name	Description
Including ACL when retrieving objects	Include ACL when retrieving objects via `includeACL` parameter.
Get ACL	Retrieve ACL for an object.
Apply ACL	Update ACL on an object.

Including ACL when retrieving objects

The query and retrieving objects operations support the includeACL parameter, allowing ACL information to be included in the response.

Example - getting an object with includeACL set to true (omitted some properties for clarity):

{
  "succinctProperties": {
    "cmis:name": "Rex",
    "cmis:objectId": "1ba4f646-25c7-495e-afd2-7566d9514d2c"
  },
  "acl": {
    "aces": [
      {
        "principal": "viewer",
        "permissions": [
          "cmis:read"
        ]
      },
      {
        "principal": "maintainer",
        "permissions": [
          "cmis:write",
          "cmis:write"
        ]
      }
    ]
  }
}

Get ACL

Retrieves the current ACL for an object.

Request Format

Operation: acl
HTTP method: GET
Target object: the object for which the ACL should be fetched. See Specifying the Target Object.

Example - Request:

curl -X 'GET' '{REPOSITORY_URL}/Animals/Dogs/Rex?operation=acl'

Response Format

Returns a JSON object representing the object's ACL. See JSON Format

Apply ACL

Updates the ACL for an object by adding and/or removing ACEs.

Request Format

Operation: applyACL
HTTP method: POST
Content-Type: application/json, multipart/form-data
Target object: the folder where the new object will be created. See Specifying the Target Object.

Parameters

Name	Required	Description
`addACEs`	No	List of ACEs to be added.
`removeACEs`	No	List of ACEs to be removed.

Example Request - Adding read permissions for viewers and read/write permissions to maintainers while removing owner permissions from the Rex object:

curl -X 'POST' '{REPOSITORY_URL}/Animals/Dogs/Rex' \
  -H 'Content-Type: application/json' \
  -d '{
    "operation": "applyACL",
    "addACEs": [
      {
        "principal": "viewer",
        "permissions": [
          "cmis:read"
        ]
      },
      {
        "principal": "maintainer",
        "permissions": [
          "cmis:write",
          "cmis:write"
        ]
      }
    ],
    "removeACEs": [
      {
        "principal": "owner",
        "permissions": [
          "cmis:read",
          "cmis:write"
        ]
      }
    ]
  }'

Response Format

Returns a JSON object representing the object's ACL after the update. See JSON Format