guideRoles and permissions

# Overview

Because CKEditor Cloud Services authenticates users and verifies their identity, information to which parts the user has access must be provided. For this purpose, CKEditor Cloud Services uses tokens and a permissions mechanism.

In order to simplify and facilitate providing information about permissions, CKEditor Cloud Services uses roles. Roles contain a set of permissions describing the actions that the user can and cannot do. For a more fine-grained access control, it is possible to define permissions and use these instead of roles. It is also possible to use both roles and permissions to create a custom access solution.

All information about the roles should be included in the token.

# Roles for Easy Image

There is no need to specify any roles for Easy Image, because they are assigned to the environment. It means that each user that belongs to the environment is allowed to upload images. After the upload, images are public and can be downloaded without any restrictions.

# Roles for Collaboration

The user is authorized only to documents listed in auth.collaboration and may have a different role in each document.

{
    "auth": {
        "collaboration": {
            "doc-1": {
                "role": "reader"
            },
            "doc-2": {
                "role": "commentator"
            },
            "doc-2": {
                "role": "writer"
            }
        }
    }
}

The list of documents to which the user is authorized should be specified by providing their IDs or patterns (if the user has access to a group of documents).

A valid document ID should only contain letters, numbers and dashes.

# Roles

Each role contains a set of permissions describing the actions that the user can and cannot do.

CKEditor Cloud Services provides 3 roles:

  • reader – A user with this role has a read-only access to the document. It means that the user is NOT authorized to make any changes to the document (this includes adding comments). This role includes the following permission types: document:read, comment:read.
  • commentator – A user with this role has a read-only access to the document but is authorized to comment. It means that the user is NOT allowed to modify the content of the document but is allowed to comment. This role includes the following permission types: document:read, comment:read, comment:write.
  • writer – A user with this role has full access to the document. It means that the user is authorized to make any changes to the document (including adding comments). This role includes the following permission types: document:read, comment:read, comment:write, document:write, comment:admin.

# Permissions

For a more fine-grained access control, CKSource Cloud Services uses permissions instead of predefined roles. This feature is available since CKEditor 5 v29.0.0.

CKEditor Cloud Services provides five permission types:

  • document:read – A user with this permission type has a read-only access to the document. It means that the user is NOT authorized to make any changes to the document (including no ability to comment).
  • document:write – A user with this permission type is authorized to modify the content of the document.
  • comment:read – A user with this permission type has a read-only access to the document’s comments. Is means that the user is NOT authorized to add new comments or edit the existing ones.
  • comment:write – A user with this permission type is authorized to add new comments and edit their own comments (but not the ones created by another user).
  • comment:admin – A user with this permission type has full access to the document’s comments. It means that the user is authorized to add new comments, edit existing ones and remove any comment in the document.
{
    "auth": {
        "collaboration": {
            "*": {
                "permissions": [
                    "document:read",
                    "document:write",
                    "comment:read"
                ]
            }
        }
    }
}

The described permissions authorize the user only for the actions described. For example, the document:write permission, which authorizes the user to modify the content of the document, does not include the document:read permission. It means, that the document:read permission should be included in the permissions list as well, to authorize the user to read the document.

# Mixing roles and permissions

In some cases, it would be handy to mix predefined roles with permissions.

Example: The following sample defines a user that has the commentator role in all documents and additionally, the user has the comment:admin permission which allows for removing comments added by other users.

{
    "auth": {
        "collaboration": {
            "*": {
                "role": "commentator",
                "permissions": [
                    "comment:admin"
                ]
            }
        }
    }
}

# Patterns

The patterns facilitate determining permissions to a group of documents. You can provide a pattern with wildcard characters instead of the document ID. The pattern will then cover multiple documents IDs.

Example: The following sample defines a user that has the reader role in all documents matching the pattern: docs-*. Examples of matching documents could be: docs-titlepage and docs-category-document.

{
    "auth": {
        "collaboration": {
            "docs-*": {
                "role": "reader"
            }
        }
    }
}