Authenticate and authorize in Collaboration

After setting up a collaborative editor in the installation guide, it's crucial to address authentication for longer-term use. The temporary JWT provided in your Tiptap account is only suitable for brief testing sessions.

Set up authorization

Setting up the right access controls is important for keeping your documents secure and workflows smooth in Tiptap Collaboration.

This part of the guide walks you through how to use JSON Web Tokens (JWTs) to fine-tune who gets to see and edit what. Whether you need to give someone full access, restrict them to certain documents, or block access entirely, we've got you covered with minimalistic examples.

Allow full access to every document

Omitting the allowedDocumentNames property from the JWT payload grants the user access to all documents. This is useful for users who need unrestricted access.

import jsonwebtoken from 'jsonwebtoken'

const data = { sub: 'your_local_user_identifier' }

const jwt = jsonwebtoken.sign(data, 'your_secret')

Limit access to specific documents

To restrict a user's access to specific documents, include those document names in the allowedDocumentNames array within the JWT payload. This ensures the user can only access the listed documents.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  allowedDocumentNames: ['user-specific-document-1', 'user-specific-document-2'],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

Block access to all documents

To prohibit a user from accessing any documents, provide an empty array for allowedDocumentNames in the JWT payload. This effectively blocks access to all documents.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  allowedDocumentNames: [],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

Set Read-Only access

The readonlyDocumentNames property in your JWT setup plays a crucial role when you need to allow users to view documents without the ability to edit them. This feature is particularly useful in scenarios where you want to share information with team members for review or reference purposes but need to maintain the integrity of the original document.

By specifying document names in the readonlyDocumentNames array, you grant users read-only access to those documents. Users can open and read the documents, but any attempts to modify the content will be restricted. This ensures that sensitive or critical information remains unchanged while still being accessible for necessary personnel.

In this example, we grant read-only access to two documents, annual-report-2024 and policy-document-v3. Users with this JWT can view these documents but cannot make any edits.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  readonlyDocumentNames: ['annual-report-2024', 'policy-document-v3'],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

Incorporating the readonlyDocumentNames property into your JWT strategy improves document security by ensuring that only authorized edits are made, preserving the integrity of your critical documents.

Authorize with Wildcards

Wildcards in JWTs offer a dynamic way to manage document access, allowing for broader permissions within specific criteria without listing each document individually. This method is particularly useful in scenarios where documents are grouped by certain attributes, such as projects, teams, or roles.

Manage project-specific documents

For teams working on multiple projects, it's essential to ensure that members have access only to the documents relevant to their current projects. By using project identifiers with wildcards, you can streamline access management.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  allowedDocumentNames: ['project-alpha/*', 'project-beta/*'],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

In this example, users will have access to all documents under 'project-alpha' and 'project-beta', making it easier to manage permissions as new documents are added to these projects.

Facilitate role-based access control

Role-based access control (RBAC) is a common requirement in many systems, where access needs to be granted based on the user's role within the organization. Wildcards allow for easy mapping of roles to document access patterns.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  allowedDocumentNames: ['editors/*', 'contributors/*'],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

Here, users assigned as 'editors' or 'contributors' can access documents prefixed with their respective roles. This setup simplifies the process of updating access rights as roles change or new roles are added.

Integrate JWT server side

JWT, or JSON Web Token, is a compact, URL-safe means of representing claims to be transferred between two parties. The information in a JWT is digitally signed using a cryptographic algorithm to ensure that the claims cannot be altered after the token is issued. This digital signature makes the JWT a reliable vehicle for secure information exchange in web applications, providing a method to authenticate and exchange information.

Create a static JWT for testing

For testing purposes, you might not want to set up a complete backend system to generate JWTs. In such cases, using online tools like http://jwtbuilder.jamiekurtz.com/ can be a quick workaround. These tools allow you to create a JWT by inputting the necessary payload and signing it with a secret key.

When using these tools, ensure that the "Key" field is replaced with the secret key from your Collaboration settings page. You don’t need to change any other information.

Remember, this approach is only recommended for testing due to security risks associated with exposing your secret key.

Generate JWTs server side

For production-level applications, generating JWTs on the server side is a necessity to maintain security. Exposing your secret key in client-side code would compromise the security of your application. Here’s an example using NodeJS for creating JWTs server-side:

npm install jsonwebtoken

import jsonwebtoken from 'jsonwebtoken'

const payload = {
  // The payload contains claims like the user ID, which can be used to identify the user and their permissions.
  sub: 'your_local_user_identifier',
}

// The 'sign' method creates the JWT, with the payload and your secret key as inputs.
const jwt = jsonwebtoken.sign(payload, 'your_secret_key_here')
// The resulting JWT is used for authentication in API requests, ensuring secure access.
// Important: Never expose your secret key in client-side code!

This JWT should be incorporated into API requests within the token field of your authentication provider, safeguarding user sessions and data access.

To fully integrate JWT into your application, consider setting up a dedicated server or API endpoint, such as GET /getCollabToken. This endpoint would dynamically generate JWTs based on a secret stored securely on the server and user-specific information, like document access permissions.

This setup not only increases security but also provides a scalable solution for managing user sessions and permissions in your collaborative application.

Ensure the secret key is stored as an environment variable on the server, or define it directly in the server code. Avoid sending it from the client side.

A full server / API example is available here.