Skip to main content

Permissions

The server makes sure that users have permissions to perform certain actions.

By default, the following rules are set:

Document permissions

  • Any user can create a document
  • Only the author of a document can edit it
  • Only document members (people who were invited) can view a document (unless the document is public)
  • Only the author of a document can delete it
  • Only the author of a document can invite users to it

Annotation permissions

  • Only members of the document can add annotations to it
  • Only the author of the annotation can edit it
  • Only members of the document can view it
  • Only the author of the annotation can delete it

If you are not happy with these defaults, you can customize them as per the guide below.

Customizing permissions#

You can change the default permissions by passing a permissions object to the server constructor.

The permissions object let you set entity level permissions for each action type (add, edit, delete, invite).

The permissions object has two properties, CollabServer.Permissions.Entities.DOCUMENT and CollabServer.Permissions.Entities.ANNOTATION. Both of these are optional.

import CollabServer from '@pdftron/collab-server';
const server = new CollabServer({
...otherOptions,
permissions: {
[CollabServer.Permissions.Entities.DOCUMENT]: {
},
[CollabServer.Permissions.Entities.ANNOTATION]: {
}
}
});

Permissions in the DOCUMENT object apply to documents, and permissions in the ANNOTATION object apply to annotations.

From here you can set permissions based on actions (add, edit, delete, invite). To do this set the key of the object to whatever action permission you want to set, and set the value to the role that the user must be to execute that action.

For example, to make it so that any member of a document can edit it, you would do:

import CollabServer from '@pdftron/collab-server';
const server = new CollabServer({
...otherOptions,
permissions: {
[CollabServer.Permissions.Entities.DOCUMENT]: {
[CollabServer.Permissions.Actions.EDIT]: CollabServer.Permissions.Roles.DOCUMENT_MEMBER
},
}
});

Actions#

The possible actions are listed below (you can also view the API docs here)

NameDescription
CollabServer.Permissions.Actions.ADDadding an entity
CollabServer.Permissions.Actions.EDITediting an entity
CollabServer.Permissions.Actions.READreading/viewing an entity
CollabServer.Permissions.Actions.DELETEdeleting an entity
CollabServer.Permissions.Actions.INVITEinviting someone to an entity

Roles#

The possible roles are listed below (you can also view the API docs here)

NameDescription
CollabServer.Permissions.Roles.ANNOTATION_AUTHORThe user must be the auth of the annotation to perform the action
CollabServer.Permissions.Roles.DOCUMENT_AUTHORThe user must be the document of the author to perform the action
CollabServer.Permissions.Roles.DOCUMENT_MEMBERThe user must be a member of the document to perform the action
CollabServer.Permissions.Roles.ANYAnyone can perform the action

Custom roles#

If you want more fine tuned control over the permissions, you can pass an auth function instead of a role that determines if the user is allowed to perform the action.

The function can be async and must resolve with true if the user is allowed to make the operation, or false otherwise.

authFunction(entity, user): Promise<boolean>#

  • entity (Annotation | Document) the entity being operated on.
  • user (object) information about the user performing the action
    • id (string) the user's id
    • email (string) the user's email
    • type (string) the type of user

You can pass an authFunction to any permission setting.

For example, if you want to make a whitelist of emails who can create documents, you could do this:

import CollabServer from '@pdftron/collab-server';
const whitelist = [
'joe@email.com',
'bob@email.com'
]
const server = new CollabServer({
...otherOptions,
permissions: {
[CollabServer.Permissions.Entities.DOCUMENT]: {
[CollabServer.Permissions.Actions.ADD]: (document, user) => {
const { email } = user;
return whitelist.includes(email);
}
},
}
});