CC/ruoyi-java

Fork 0

Files

Leo 2b74f77419 WPS365

2026-01-15 20:48:39 +08:00

8.9 KiB

Raw Permalink Blame History

WPS365 授权错误排查指南

常见错误类型

1. invalid_request (40000001) - redirect_uri不匹配

{
  "code": 40000001,
  "msg": "invalid_request",
  "debug": {
    "desc": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. The 'redirect_uri' parameter does not match any of the OAuth 2.0 Client's pre-registered redirect urls."
  }
}

错误含义：redirect_uri参数值与WPS365平台配置的回调地址不一致

2. invalid_scope (40000005) - scope权限无效 ⚠️

{
  "code": 40000005,
  "msg": "invalid_scope",
  "debug": {
    "desc": "The requested scope is invalid, unknown, or malformed. The OAuth 2.0 Client is not allowed to request scope 'file.read,ksheet.read,user.info'."
  }
}

错误含义：请求的scope权限格式不正确，或者应用未申请这些权限

错误含义总览

授权错误可能由以下原因导致：

缺少必需参数 - 授权请求中缺少某个必需的参数
参数值无效 - 某个参数的值格式不正确
参数重复 - 某个参数在请求中出现了多次
redirect_uri不匹配 - redirect_uri参数值与WPS365平台配置的回调地址不一致
scope无效 - scope权限格式不正确或未申请

排查步骤

1. 查看后端日志

查看后端日志中的授权URL和参数清单，例如：

生成授权URL: https://openapi.wps.cn/oauth2/auth?client_id=xxx&redirect_uri=...
📋 授权请求参数清单:
   - client_id: AK20260114NNQJKV
   - redirect_uri: https://jarvis.van333.cn/wps365-callback
   - response_type: code
   - scope: file.read,ksheet.read,user.info
   - state: xxxxx

2. 检查参数名是否正确

问题：WPS365可能使用 app_id 而不是标准的 client_id

解决方案：

如果使用 client_id 报错，尝试改为 app_id
查看WPS365官方文档确认正确的参数名

当前代码使用：client_id（标准OAuth2参数名）

3. 检查必需参数是否齐全

授权请求必须包含以下参数：

参数名	是否必需	说明	当前值
`client_id` 或 `app_id`	✅ 必需	应用ID	从配置读取
`redirect_uri`	✅ 必需	回调地址	从配置读取
`response_type`	✅ 必需	固定值 `code`	`code`
`scope`	✅ 必需	权限范围	`file.read,ksheet.read,user.info`
`state`	⚠️ 推荐	防CSRF攻击	自动生成

4. 检查redirect_uri是否匹配

这是最常见的错误原因。必须确保：

协议一致：必须是 https://（不能是 http://）
域名一致：必须是 jarvis.van333.cn（不能有 www 前缀）
路径一致：必须是 /wps365-callback（不能有末尾斜杠）
端口一致：使用默认443端口，不需要写端口号

在WPS365平台配置的回调地址必须与日志中的redirect_uri完全一致

5. 检查scope权限是否已申请（重要！）

如果遇到 invalid_scope 错误，请按以下步骤排查：

5.1 检查WPS365平台后台的scope格式

登录WPS365开放平台
进入"开发配置" > "权限管理"
查看已申请的权限列表，注意权限的格式：
- 必须以 kso. 开头，如：kso.file.read、kso.file.readwrite
- 不是 file.read 或 ksheet.read（这些格式不存在）
- 根据官方文档：https://open.wps.cn/documents/app-integration-dev/wps365/server/

5.2 检查scope分隔符

根据WPS365官方文档，必须使用英文逗号分隔（不是空格）：

分隔符	示例	说明
逗号（正确）	`kso.file.readwrite,kso.doclib.readwrite`	✅ WPS365官方要求
空格（错误）	`kso.file.readwrite kso.doclib.readwrite`	❌ 会导致invalid_scope
逗号+空格	`kso.file.readwrite, kso.doclib.readwrite`	⚠️ 可能支持，但不推荐

重要：WPS365官方文档明确要求使用英文逗号 , 分隔，不能使用空格。

5.3 在配置文件中指定scope

在 application.yml 中添加 scope 配置，必须使用英文逗号分隔：

wps365:
  # 根据WPS365平台后台"权限管理"中显示的实际权限名称配置
  # 使用英文逗号分隔（WPS365官方要求）
  # 权限名称必须以 kso. 开头
  scope: kso.file.readwrite

多个权限示例：

wps365:
  # 多个权限用英文逗号分隔，不能有空格
  # 权限名称必须以 kso. 开头
  scope: kso.file.read,kso.file.readwrite

5.4 确认权限已申请且名称正确

关键步骤：

登录WPS365开放平台
- 访问：https://open.wps.cn/
- 进入你的应用管理页面
查看已申请的权限
- 进入"开发配置" > "权限管理"
- 查看已申请权限的准确名称（注意大小写、分隔符、命名空间）
对比权限名称
- 权限名称必须与后台显示的完全一致
- 例如：如果后台显示的是 kso.doclib.readwrite，不能写成 kso.doclib.readWrite 或 kso_doclib_readwrite
常见权限名称示例（仅供参考，以平台后台实际显示为准）：
- kso.doclib.readwrite - 文档库读写权限
- kso.doclib.read - 文档库读取权限
- ksheet.read - 在线表格读取权限（如果支持）

重要提示：

⚠️ file.read、ksheet.read、user.info 这些权限名称可能不存在
✅ 必须查看WPS365平台后台实际显示的权限名称
✅ 权限名称必须完全匹配（包括大小写、分隔符、命名空间）
✅ 必须使用英文逗号分隔多个权限

6. 尝试修改参数名

如果确认所有参数都正确，但仍然报错，可能是参数名问题：

测试方案1：将 client_id 改为 app_id

修改 WPS365OAuthServiceImpl.java 中的代码：

// 原代码
authUrl.append("?client_id=").append(appId);

// 改为
authUrl.append("?app_id=").append(appId);

测试方案2：同时提供两个参数（如果WPS365支持）

authUrl.append("?app_id=").append(appId);
authUrl.append("&client_id=").append(appId);

7. 检查URL编码

确保 redirect_uri 参数正确进行了URL编码：

空格应该编码为 %20
斜杠 / 应该编码为 %2F
冒号 : 应该编码为 %3A

查看日志中的"编码后"值，确认编码是否正确。

8. 验证WPS365平台配置

登录WPS365开放平台，检查：

应用ID（AppId） 是否与配置文件中的 app-id 一致
回调地址配置 是否与日志中的 redirect_uri 完全一致
权限配置 是否已申请所需的scope权限
应用状态 是否为"已上线"或"测试中"

常见问题

Q1: 参数名应该用 `client_id` 还是 `app_id`？

A: 根据WPS365官方文档确认。标准OAuth2使用 client_id，但某些平台可能使用 app_id。如果 client_id 不工作，尝试 app_id。

Q2: 为什么redirect_uri明明配置了还是报错？

A: 最常见的原因是：

平台配置的回调地址与代码中的不完全一致（多了/少了斜杠、协议不同等）
平台配置未保存或未生效
使用了错误的配置环境（开发/生产）

Q3: scope权限在哪里申请？

A: 在WPS365开放平台的"开发配置" > "权限管理"中申请。

Q4: 如何确认参数是否正确？

A: 查看后端日志，会打印完整的授权URL和参数清单。对比WPS365平台配置，确保完全一致。

Q5: 遇到 `invalid_scope` 错误怎么办？ ⚠️

A: 这是scope格式或权限问题，按以下步骤排查：

查看WPS365平台后台的权限格式
- 进入"开发配置" > "权限管理"
- 查看已申请权限的确切格式（包括分隔符、大小写）
尝试不同的scope格式
- 空格分隔：file.read ksheet.read user.info（当前默认）
- 逗号分隔：file.read,ksheet.read,user.info
- 在 application.yml 中配置 scope 参数进行测试
确认权限已申请且已审核通过
- 权限必须处于"已通过"或"可用"状态
- 如果权限未申请，需要先申请并等待审核
查看后端日志中的scope值
- 日志会显示实际使用的scope格式
- 对比WPS365平台显示的格式，确保完全一致

调试建议

启用DEBUG日志：在 application.yml 中设置日志级别为DEBUG
查看完整授权URL：复制日志中的授权URL，在浏览器中访问，查看具体错误
对比官方文档：查看WPS365官方OAuth文档，确认参数名和格式
联系WPS365技术支持：如果所有参数都正确但仍报错，可能是平台问题

下一步

如果按照以上步骤排查后仍然报错，请提供：

后端日志中的完整授权URL和参数清单
WPS365平台配置的回调地址截图
WPS365平台的应用配置截图（隐藏敏感信息）

8.9 KiB Raw Permalink Blame History Unescape Escape