---
title: "在协作中进行身份验证和授权"
description: "使用 Tiptap 认证对协作编辑进行授权。将令牌限定到 Documents 服务，并授予按文档划分的读取、写入和评论访问权限。"
canonical_url: "https://tiptap.zhcndoc.com/collaboration/getting-started/authenticate"
---

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

使用 Tiptap 认证对协作编辑进行授权。将令牌限定到 Documents 服务，并授予按文档划分的读取、写入和评论访问权限。

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

> **刚接触 Tiptap 身份验证？:**
>
> 本页面涵盖 Documents 特定的声明。要创建密钥对并签名令牌，请参见 [身份验证](https://tiptap.zhcndoc.com/authentication.md)。关于之前的 `allowedDocumentNames` 模型，请参见 [旧版身份验证](https://tiptap.zhcndoc.com/authentication/legacy.md)。

## 受众和操作

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

| 操作                  | 授予                                                                                                                                |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Documents:Read`    | 打开并读取文档                                                                                                                           |
| `Documents:Write`   | 编辑文档。隐含 `Documents:Read` 和 `Documents:Comment`                                                                                    |
| `Documents:Comment` | 无需编辑即可添加评论                                                                                                                        |
| `Documents:Api:All` | 对所有 Document Server API 端点的完全访问权限，包括设置。请将此令牌保留在服务器端。参见 [REST API](https://tiptap.zhcndoc.com/collaboration/documents/rest-api.md) |

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

## 按文档授权

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

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

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

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

### 特定文档

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

### 只读访问

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

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

### 无编辑权限的评论

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

### 一组文档

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

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

这会授予对名称以 `project-alpha/` 开头的每个文档的访问权限。有关完整的约束参考，包括 `suffix` 和 `in`，请参见 [权限](https://tiptap.zhcndoc.com/authentication.md#permissions)。

## 连接提供方

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

```ts
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。用户可能会长时间保持标签页打开，因此应在重新连接时处理过期，以避免丢失 [未同步的更改](https://tiptap.zhcndoc.com/collaboration/provider/integration.md#unsynced-changes)。

要在 token 过期前使其失效，Collaboration 提供了 [Revoke JWT API](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/request/33042171-63ed5bbe-f54d-4a85-b2d0-5c1bc215d2fc)。由于提供了撤销机制，你不需要让 token 的有效期极短。