Update authenticate.md

docs/collaboration/authenticate.md

@@ -1,4 +1,10 @@
-# Authentication in Collaboration
+---
+tableOfContents: true
+---
+
+# Authentication and authorization in Collaboration
+
+## Authentication 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 by Collaboration is only suitable for brief testing sessions.
 
@@ -14,7 +20,7 @@ When using these tools, ensure that the "Key" field is replaced with the secret
 
 Remember, this approach is only recommended for testing due to security risks associated with exposing your secret key.
 
-## **Generating JWTs for production environments**
+### **Generating JWTs for production environments**
 
 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 enhanced example using NodeJS for creating JWTs server-side:
 
@@ -45,3 +51,106 @@ This setup not only enhances security but also provides a scalable solution for
 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](https://github.com/ueberdosis/tiptap-collab-replit/tree/main/src).
+
+## **Authorization in Collaboration**
+
+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.
+
+### Allowing 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+### **Limiting 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: ['user-specific-document-1', 'user-specific-document-2'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+
+```
+
+### Blocking 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  allowedDocumentNames: [],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+## Setting 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  readonlyDocumentNames: ['annual-report-2024', 'policy-document-v3'],
+};
+
+const jwt = jsonwebtoken.sign(data, 'your_secret');
+```
+
+Incorporating the `readonlyDocumentNames` property into your JWT strategy enhances document security by ensuring that only authorized edits are made, preserving the integrity of your critical documents.
+
+## Utilizing Wildcards for Flexible Document Access
+
+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.
+
+### Managing 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  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.
+
+### Facilitating 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.
+
+```typescript
+import jsonwebtoken from 'jsonwebtoken';
+
+const data = {
+  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.