CKEditor Ecosystem Documentation
Search
Home/Cloud Services/Developer resources

guideRoles and permissions

# Roles 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 Export to PDF and Export to Word

There is no need to specify any roles for the PDF and Word converters. Each user that belongs to the environment with enabled converters is allowed to use them.

# 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 the following 3 roles:

  • reader – A user with this role has 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 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 leave comments. This role includes the following permission types: document:read, comment:read, comment:write, and allows to perform the following actions:
    • creating new comment threads,
    • removing own comment threads,
    • adding comments to all existing comment threads,
    • removing and modifying own comments from all existing comment threads,
    • resolving and reopening any comment threads (in the comments archive).
  • 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, document:write, comment:read, comment:write, comment:admin, and allows to perform the following actions:
    • creating new comment threads,
    • removing all comment threads,
    • adding comments to all existing comment threads,
    • removing and modifying own comments from all existing comment threads,
    • resolving and reopening any comment threads (in the comments archive).

Please note: None of the above roles allows removing or modifying single comments created by other users. To acquire such a privilege, please include the comment:modify_all permission.

# Permissions

For 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 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. This permission also allows the user to implicitly resolve any comment thread in the comments archive by removing content with a comment thread marker. What is more, it allows to implicitly reopen any comment thread by performing the undo operation.
  • comment:read – A user with this permission type has read-only access to the document’s comments. It 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, edit, and remove their own comments and comment threads. Moreover, it allows to resolve and reopen any comment thread in the comment archive.
  • comment:admin – A user with this permission type can remove comment threads added by any user. However, this permission does not allow removing or modifying single replies authored by others. To take advantage of this permission, users must have also the comment:write permission.
  • comment:modify_all – A user with this permission type can remove or modify comments added by other users. However, this permission does not allow removing whole comment threads authored by others.
{
    "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. The comment:admin permission is no exception to this rule.

# 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 comment threads 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"
            }
        }
    }
}