1. 为什么你的ONLYOFFICE集成总感觉“不踏实”?
我见过不少Java开发者在集成ONLYOFFICE文档编辑器时,一开始都挺顺利的。把文档服务器跑起来,前端页面嵌入编辑器,用户点开文档就能编辑,看起来一切完美。但过不了多久,问题就来了:怎么保证只有我们系统的用户才能打开文档?怎么防止有人拿到文档链接就直接访问?用户A编辑的文档,用户B能不能偷偷修改?这些问题,说白了就是认证和授权没做好,整个集成就像房子没装门锁,谁都能进,心里自然不踏实。
你可能听说过JWT(JSON Web Token),觉得它就是个“令牌”,用来做登录的。但在ONLYOFFICE的集成场景里,JWT扮演的角色远比一个简单的登录令牌要关键得多。它实际上是连接你的Java Web应用和ONLYOFFICE文档服务器之间的唯一且加密的信任桥梁。文档服务器本身不负责管理你的用户体系,它只认一样东西:你应用发过来的、用约定好的密钥签过名的JWT。这个令牌里,封装了“谁”(用户信息)在“什么时间”(防重放)对“哪个文档”(文档ID)拥有“哪些权限”(编辑、评论、只读等)。如果这个环节有漏洞,那么之前所有关于文档协作、在线编辑的便利性,都可能变成安全灾难。
所以,今天我想和你深入聊聊,怎么用JWT这把“安全锁”,把ONLYOFFICE文档服务器牢牢地锁在你的Java应用生态里。这不是一个简单的配置教程,我会结合我踩过的坑和实战经验,把原理掰开揉碎了讲,让你不仅知道怎么配,更明白为什么要这么配,以及每种配置背后可能的风险。我们从最核心的JWT配置开始,一步步构建一个完整、健壮的安全集成方案。
2. 核心基石:深入理解并配置JWT
JWT是整个安全体系的基石。很多人配置失败,或者觉得不安全,第一步就卡在了对JWT机制的理解上。
2.1 ONLYOFFICE文档服务器的JWT配置:不只是打开开关
ONLYOFFICE文档服务器(v7.2及以上)默认是启用JWT的,并且会自己生成一个密钥。但在生产环境中,绝对不要使用这个自动生成的密钥。你必须手动配置,并且确保密钥足够复杂。配置文件通常是/etc/onlyoffice/documentserver/local.json(Linux)或对应安装目录下的local.json。
原始文章里给了一个配置片段,我这里给你一个更完整、也更容易理解的版本,并加上关键注释:
{
"services": {
"CoAuthoring": {
"token": {
"enable": {
"request": {
"inbox": true, // 对进入文档服务器的请求启用JWT验证
"outbox": true // 对文档服务器发出的请求(如回调)启用JWT签名
},
"browser": true // 对前端直接与文档服务器的通信启用JWT
},
"secret": {
"inbox": {
"string": "YourSuperStrongSecretKeyForInbox2024!" // 用于验证请求的密钥
},
"outbox": {
"string": "YourSuperStrongSecretKeyForOutbox2024!" // 用于签名回调请求的密钥
},
"session": {
"string": "YourSuperStrongSecretKeyForSession2024!" // 用于用户会话的密钥
}
},
"inbox": {
"header": "Authorization" // 请求头中携带JWT的字段名,默认就是Authorization
},
"outbox": {
"header": "Authorization" // 回调请求头中携带JWT的字段名
}
}
}
}
}
这里有几个至关重要的点:
- 三个密钥分开:
inbox,outbox,session最好使用不同的密钥。这样即使一个密钥泄露,影响范围也有限。inbox密钥是你的Java应用用来签名发给文档服务器请求的;outbox密钥是文档服务器用来签名回调(Callback)请求给你的;session用于维持前端编辑会话。 - 密钥强度:密钥必须是足够长且随机的字符串,建议使用密码生成器生成,长度至少32位,包含大小写字母、数字和特殊符号。
- 修改后重启:改完
local.json,必须重启ONLYOFFICE文档服务器服务才能生效。命令通常是supervisorctl restart all或systemctl restart ds-docservice等,具体看你的安装方式。
2.2 在Java应用中生成“对的”JWT
服务器端配好了,接下来就是在你的Java Web应用里生成能被文档服务器认可的JWT。这里的关键在于,你生成的JWT的载荷(Payload) 必须符合ONLYOFFICE的预期结构。
很多开发者直接用通用的JWT库生成一个包含userId的令牌就传过去了,结果文档服务器报错“无效令牌”,就是因为载荷格式不对。ONLYOFFICE期望的载荷是一个包含特定字段的JSON对象。
下面是一个我项目中常用的工具类,使用了流行的jjwt库。首先确保引入依赖(Maven示例):
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-api</artifactId>
<version>0.11.5</version>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-impl</artifactId>
<version>0.11.5</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-jackson</artifactId>
<version>0.11.5</version>
<scope>runtime</scope>
</dependency>
然后是生成JWT的核心代码:
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.security.Keys;
import javax.crypto.SecretKey;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
public class OnlyOfficeJwtUtil {
// 这个密钥必须和文档服务器local.json中inbox.secret.string配置的完全一致!
private static final String JWT_SECRET = "YourSuperStrongSecretKeyForInbox2024!";
private static final SecretKey KEY = Keys.hmacShaKeyFor(JWT_SECRET.getBytes(StandardCharsets.UTF_8));
/**
* 为文档编辑请求生成JWT
* @param documentId 文档唯一标识
* @param userId 用户ID
* @param userName 用户显示名
* @param permissions 用户权限对象(后续会讲)
* @return 签名的JWT字符串
*/
public static String generateEditorToken(String documentId, String userId, String userName, Map<String, Object> permissions) {
// 1. 构建ONLYOFFICE期望的Payload(载荷)
Map<String, Object> payload = new HashMap<>();
payload.put("documentId", documentId);
payload.put("userId", userId);
payload.put("userName", userName);
payload.put("permissions", permissions); // 将权限对象放入
payload.put("iat", new Date().getTime() / 1000); // 签发时间(秒级时间戳)
// 2. 可以设置一个较短的过期时间,比如10分钟,增强安全性
Date expiration = new Date(System.currentTimeMillis() + 10 * 60 * 1000);
payload.put("exp", expiration.getTime() / 1000);
// 3. 使用HS256算法和密钥生成JWT
return Jwts.builder()
.setClaims(payload) // 设置自定义载荷
.signWith(KEY, SignatureAlgorithm.HS256) // 签名
.compact();
}
}
注意:生成的JWT字符串,需要在你前端初始化ONLYOFFICE编辑器配置时,放到config.token字段里。同时,在向后端请求document.config.json(这是ONLYOFFICE要求的一个配置接口)时,也需要在HTTP请求头Authorization中携带这个令牌,格式为 Bearer <你的JWT令牌>。文档服务器的inbox模块会用它来验证请求。
3. 从粗放到精细:基于角色的动态权限控制
光有认证(知道你是谁)还不够,更重要的是授权(你能做什么)。ONLYOFFICE提供了非常细致的权限控制能力,我们需要在Java后端根据当前用户的角色,动态生成这些权限配置。
3.1 定义你的业务角色与权限映射
首先,在你的业务系统中,明确用户的角色。例如:管理员、编辑者、评论者、查看者。然后,为每个角色定义其在ONLYOFFICE编辑器中的具体能力。
我们可以创建一个枚举或配置类来管理这种映射关系:
public enum UserRole {
ADMIN("admin"),
EDITOR("editor"),
REVIEWER("reviewer"),
VIEWER("viewer");
private final String code;
UserRole(String code) { this.code = code; }
public String getCode() { return code; }
/**
* 根据角色返回对应的ONLYOFFICE权限配置
*/
public Map<String, Object> getOnlyOfficePermissions() {
Map<String, Object> perms = new HashMap<>();
switch (this) {
case ADMIN:
perms.put("edit", true);
perms.put("download", true);
perms.put("print", true);
perms.put("review", true);
perms.put("comment", true);
perms.put("fillForms", true);
perms.put("modifyFilter", true);
perms.put("modifyContentControl", true);
break;
case EDITOR:
perms.put("edit", true);
perms.put("download", true);
perms.put("print", true);
perms.put("review", true);
perms.put("comment", true);
perms.put("fillForms", true);
perms.put("modifyFilter", false); // 不能修改筛选器
perms.put("modifyContentControl", false);
break;
case REVIEWER:
perms.put("edit", false);
perms.put("download", true);
perms.put("print", true);
perms.put("review", true); // 可以接受/拒绝更改
perms.put("comment", true);
perms.put("fillForms", false);
perms.put("modifyFilter", false);
perms.put("modifyContentControl", false);
break;
case VIEWER:
perms.put("edit", false);
perms.put("download", false); // 连下载都不允许
perms.put("print", false);
perms.put("review", false);
perms.put("comment", false);
perms.put("fillForms", false);
perms.put("modifyFilter", false);
perms.put("modifyContentControl", false);
break;
}
return perms;
}
}
3.2 动态生成编辑器配置
当用户请求打开一个文档时,你的Java后端需要提供一个接口(比如/onlyoffice/config),根据文档ID和当前登录用户,动态生成ONLYOFFICE编辑器所需的完整配置。这个配置会包含文档的URL、编辑权限、用户信息以及我们上面生成的JWT令牌。
@RestController
@RequestMapping("/api/onlyoffice")
public class OnlyOfficeController {
@Autowired
private DocumentService documentService;
@Autowired
private UserService userService;
@GetMapping("/config")
public Map<String, Object> getEditorConfig(@RequestParam String fileId,
HttpServletRequest request) {
// 1. 获取当前登录用户信息(从Session或Token)
User currentUser = userService.getCurrentUser(request);
// 2. 根据用户和文档,确定其在此文档上的角色
UserRole role = documentService.getUserRoleForDocument(currentUser.getId(), fileId);
// 3. 获取该角色的详细权限
Map<String, Object> permissions = role.getOnlyOfficePermissions();
// 4. 构建用户对象(用于编辑器内显示)
Map<String, Object> editorUser = new HashMap<>();
editorUser.put("id", currentUser.getId());
editorUser.put("name", currentUser.getDisplayName());
editorUser.put("group", currentUser.getDepartment()); // 可以按部门分组
// 5. 生成JWT令牌,将权限信息放入Payload
String jwtToken = OnlyOfficeJwtUtil.generateEditorToken(
fileId,
currentUser.getId(),
currentUser.getDisplayName(),
permissions // 权限作为Payload的一部分
);
// 6. 组装ONLYOFFICE前端所需的完整配置
Map<String, Object> config = new HashMap<>();
config.put("documentType", "word"); // 根据文件后缀判断
config.put("document", Map.of(
"title", documentService.getFileName(fileId),
"url", documentService.getFileDownloadUrl(fileId), // 文档下载地址
"fileType", "docx",
"key", fileId + "_" + System.currentTimeMillis(), // 关键:key变化会强制重新加载文档
"permissions", permissions // 这里也直接传入权限,编辑器会据此禁用对应功能
));
config.put("editorConfig", Map.of(
"callbackUrl", "https://your-app.com/api/onlyoffice/callback",
"user", editorUser,
"customization", Map.of(
"forcesave", true // 是否启用强制保存
)
));
config.put("token", jwtToken); // 前端需要将这个token设置给编辑器
return config;
}
}
关键点:document.key 这个字段非常重要。ONLYOFFICE用它来标识文档的唯一版本。如果你希望用户每次打开都看到最新版本,或者在不同权限间切换时编辑器能刷新,就需要改变这个key(比如加上时间戳)。如果key不变,浏览器可能会缓存旧的编辑界面。
4. 守好最后一道门:安全的回调(Callback)处理
文档在ONLYOFFICE中编辑、保存后,文档服务器需要通知你的应用“文档改完了,这是新内容”。这个通知就是通过回调(Callback) URL发起的。这里是安全链条上另一个关键节点,你必须验证这个回调请求确实来自你信任的文档服务器,而不是伪造的。
4.1 验证回调请求的JWT签名
还记得我们在local.json里配置的outbox.secret.string吗?文档服务器在发起回调请求时,会用这个密钥对请求内容(或请求头)进行JWT签名。你的Java应用在收到回调时,必须用相同的outbox密钥去验证这个签名。
首先,在回调接口中提取并验证JWT:
@PostMapping("/callback")
public String handleCallback(@RequestBody String body,
@RequestHeader(value = "Authorization", required = false) String authHeader) {
// 1. 检查是否有Authorization头
if (authHeader == null || !authHeader.startsWith("Bearer ")) {
throw new SecurityException("Missing or invalid Authorization header in callback.");
}
String callbackToken = authHeader.substring(7); // 去掉"Bearer "前缀
// 2. 验证JWT签名(使用outbox密钥)
String outboxSecret = "YourSuperStrongSecretKeyForOutbox2024!";
try {
Jwts.parserBuilder()
.setSigningKey(Keys.hmacShaKeyFor(outboxSecret.getBytes(StandardCharsets.UTF_8)))
.build()
.parseClaimsJws(callbackToken);
// 验证通过,说明请求确实来自我们的文档服务器
} catch (Exception e) {
// 签名无效、令牌过期等
throw new SecurityException("Invalid callback token: " + e.getMessage());
}
// 3. 解析回调请求体
Map<String, Object> callbackData = parseCallbackBody(body);
Integer status = (Integer) callbackData.get("status");
String key = (String) callbackData.get("key");
// 4. 根据状态处理业务逻辑
if (status == 2) { // 文档已编辑并准备保存
String downloadUrl = (String) callbackData.get("url");
// 从downloadUrl下载新的文档版本,替换存储中的旧版本
documentService.saveNewVersion(key, downloadUrl);
return "{\"error\":0}"; // 必须返回特定JSON响应
} else if (status == 6) { // 用户正在编辑(定期心跳)
// 可以更新文档的“正在编辑”状态
} else if (status == 1) { // 文档编辑结束,无变化
// 清理资源等
}
return "{\"error\":0}";
}
4.2 处理回调的常见“坑”与最佳实践
- 超时与重试:文档服务器发起回调后,会等待你的应用返回
{"error":0}。如果你的处理逻辑很慢(比如下载大文件),可能会导致文档服务器超时。ONLYOFFICE有重试机制,但你的回调接口需要设计成幂等的,即同一key的多次保存请求,最终结果应该一致。 - 状态码处理:回调中的
status字段有很多值,你需要重点处理status=2(保存)和status=6(正在编辑)。对于status=2,务必尽快从提供的url下载文件并存储,因为这个URL可能有时效性。 - 错误响应:如果你的处理出错,可以返回
{"error": 1}或{"error": <自定义错误码>}。文档服务器可能会根据错误码采取不同行动(如提示用户)。 - 网络隔离考虑:如果你的文档服务器和应用服务器在内网,确保回调URL是内网可访问的地址,避免不必要的公网暴露。
5. 超越配置:架构与运维层面的安全加固
做到以上几点,基本的安全集成已经完成。但要想更上一层楼,让系统更健壮,还需要从架构和运维角度考虑更多。
5.1 密钥管理:别把密码写在代码里
把JWT密钥硬编码在Java代码或配置文件中是极不安全的。一旦代码泄露,全线崩溃。推荐的做法是:
- 环境变量:在服务器启动时通过环境变量注入密钥。
JWT_INBOX_SECRET=xxx java -jar yourapp.jar。 - 配置中心:使用Spring Cloud Config、Apollo、Nacos等配置中心动态管理密钥,并支持加密存储和动态刷新。
- 密钥管理服务:对于大型或合规要求严格的项目,使用专业的密钥管理服务(KMS),如阿里云KMS、AWS KMS等,在运行时动态获取密钥。
5.2 网络层隔离与访问控制
- 最小化暴露:ONLYOFFICE文档服务器不应该直接暴露在公网。应该将其部署在内网,仅允许你的Java应用服务器(或反向代理)访问其端口(通常是80/443, 9980)。公网用户只访问你的Web应用。
- 防火墙规则:在应用服务器和文档服务器之间配置严格的防火墙规则,只开放必要的端口。
- 反向代理:通过Nginx或Apache等反向代理访问文档服务器,可以在代理层添加额外的安全措施,如IP白名单、速率限制、更严格的HTTPS配置等。
5.3 日志、监控与审计
安全是一个持续的过程,需要可观测性。
- 详细日志:记录所有JWT生成、验证、回调处理的日志,包括成功和失败。特别是验证失败的情况,要记录来源IP、令牌片段等信息,用于分析潜在攻击。
- 监控告警:监控文档服务器的健康状态、回调接口的响应时间和错误率。如果短时间内出现大量JWT验证失败或回调错误,应立即触发告警。
- 操作审计:记录谁在什么时间打开了哪个文档,进行了什么操作(通过回调状态分析)。这对于满足合规性要求(如等保)至关重要。
5.4 定期轮换密钥
就像定期改密码一样,JWT密钥也应该定期轮换。这需要你协调好Java应用和ONLYOFFICE文档服务器的配置更新。
- 生成一套新的密钥对(inbox, outbox, session)。
- 先在Java应用中配置支持新旧两套密钥(验证时尝试新旧,签名用新密钥)。
- 更新文档服务器的
local.json,使用新密钥。 - 重启文档服务器。
- 观察一段时间,确认所有功能正常后,从Java应用中移除旧密钥的支持。
这个过程需要在一个维护窗口内完成,并做好回滚预案。
6. 实战:一个完整的权限控制与编辑状态同步案例
让我们通过一个更复杂的场景把上面的知识串起来:一个合同评审系统。合同起草人(编辑者)创建合同,法务(评论者)和部门领导(查看者)参与。我们需要实现:法务只能评论不能修改正文,部门领导只能查看,并且所有人要实时看到谁正在编辑。
后端实现思路:
- 权限判断:当用户点击合同时,后端根据用户角色(从数据库或缓存中读取)生成对应的
permissionsMap。 - 生成带状态的JWT:在JWT的Payload中,不仅包含
userId和permissions,还可以加入一个sessionId或action字段,标识此次打开动作。 - 前端初始化:前端拿到配置后,初始化ONLYOFFICE编辑器。编辑器会根据
config.document.permissions自动禁用/启用相关按钮(如保存、评论、打印)。 - 实时状态同步(利用回调):当用户打开文档(
status=1)或开始编辑(status=6心跳)时,回调接口被触发。后端可以将document.key和user.id存入Redis,并设置一个短的过期时间(如30秒)。其他用户打开同一文档时,后端可以从Redis中查询到“当前谁正在编辑”,并将这个信息通过其他通道(如WebSocket)推送给前端,前端可以在编辑器外显示“XXX正在编辑...”。 - 保存与版本管理:当起草人保存(
status=2)时,回调接口处理文件下载和存储。同时,可以触发一个工作流,通知法务和部门领导“合同已更新”。
这个案例体现了JWT用于认证和基础授权,结合业务逻辑和回调机制,实现了复杂的协作流程和安全控制。它不再是简单的“能开”或“不能开”,而是精细化的“能做什么”和“过程可知”。
1442



被折叠的 条评论
为什么被折叠?



