在协作中进行身份验证和授权

Collaboration 使用 Documents 服务进行身份验证。你在服务器上签名一个 JWT，并在客户端连接时将其传递给提供商。该令牌会指定用户可以访问哪些文档，以及他们可以对这些文档执行什么操作。

刚接触 Tiptap 身份验证？

本页面涵盖 Documents 特定的声明。要创建密钥对并签名令牌，请参见身份验证。关于之前的 allowedDocumentNames 模型，请参见旧版身份验证。

受众和操作

将 aud 声明设置为 "Documents"。协作识别以下操作：

操作	授予
`Documents:Read`	打开并读取文档
`Documents:Write`	编辑文档。隐含 `Documents:Read` 和 `Documents:Comment`
`Documents:Comment`	无需编辑即可添加评论
`Documents:Api:All`	对所有 Document Server API 端点的完全访问权限，包括设置。请将此令牌保留在服务器端。参见 REST API

因为 Documents:Write 隐含读取和评论权限，所以仅授予写入权限就足以获得完整的编辑访问权限。

按文档授权

resource 字段用于指定权限适用的文档。对每个文档使用 "*"，对单个文档使用准确的文档名称，或使用带约束的 "*" 来匹配一组文档。

对每个文档的完全访问权限

{
  "aud": "Documents",
  "permissions": [{ "action": "Documents:Write", "resource": "*" }]
}

注意

具有 "resource": "*" 且没有任何约束的权限会匹配你环境中的每个文档。当用户只应访问特定文档时，请为资源设置范围。

特定文档

{
  "permissions": [
    { "action": "Documents:Write", "resource": "user-specific-document-1" },
    { "action": "Documents:Write", "resource": "user-specific-document-2" }
  ]
}

只读访问

授予 Documents:Read，但不授予 Documents:Write：

{
  "permissions": [{ "action": "Documents:Read", "resource": "annual-report-2024" }]
}

无编辑权限的评论

{
  "permissions": [
    { "action": "Documents:Read", "resource": "policy-document-v3" },
    { "action": "Documents:Comment", "resource": "policy-document-v3" }
  ]
}

一组文档

使用 prefix 约束，而不是按名称逐个列出每个文档：

{
  "permissions": [
    {
      "action": "Documents:Write",
      "resource": "*",
      "constraints": { "prefix": "project-alpha/" }
    }
  ]
}

这会授予对名称以 project-alpha/ 开头的每个文档的访问权限。有关完整的约束参考，包括 suffix 和 in，请参见权限。

连接提供方

将签名后的 token 作为 token 传递给 TiptapCollabProvider，并同时传入你的 appId。请在服务器上生成该 token，并将其发送到客户端。切勿在客户端代码中暴露你的签名密钥。

const doc = new Y.Doc()

const provider = new TiptapCollabProvider({
  name: note.id, // 文档标识符
  appId: 'YOUR_APP_ID', // 来自 Cloud 仪表盘的文档服务器 ID
  token: 'YOUR_JWT', // 签名后的 Documents token
  document: doc,
  user: userId,
})

处理 token 过期

通过设置 exp 来保持 token 的短生命周期。Token 会每隔几秒进行一次验证，因此过期的 token 会在过期后不久被拒绝，并且无法重新连接。

如果 token 在连接或重新连接时无效，onAuthenticationFailed 回调会以 permission-denied 作为原因触发。
如果 token 在已建立的连接期间过期，onClose 回调会以 JWT verification failed 作为原因触发。

在这两种情况下，都需要创建一个新的 token 并重新创建 provider。用户可能会长时间保持标签页打开，因此应在重新连接时处理过期，以避免丢失未同步的更改。

要在 token 过期前使其失效，Collaboration 提供了 Revoke JWT API。由于提供了撤销机制，你不需要让 token 的有效期极短。

Previously安装

Next up集成