Pocket-ID 项目新增自定义声明对象类型支持

Pocket-ID 作为一款身份认证服务，近期在 v0.29.0 版本中实现了一项重要功能升级：支持自定义声明（Custom Claims）的非字符串对象类型。这项改进解决了用户在使用 Pocket-ID 与第三方应用集成时遇到的数据类型兼容性问题。

背景与需求分析

在身份认证领域，JWT（JSON Web Token）中的声明（Claims）是承载用户信息的重要部分。传统上，许多认证服务仅支持字符串类型的自定义声明，这在实际应用中存在明显局限性。

以 Audiobookshelf 应用为例，该应用期望从认证服务获取结构化的权限数据，包括：

• 下载权限（canDownload）
• 上传权限（canUpload）
• 删除权限（canDelete）
• 访问限制内容权限（canAccessExplicitContent）
• 标签管理权限等

这些权限信息需要以 JSON 对象形式传递，包含布尔值和数组等复杂数据类型。在旧版 Pocket-ID 中，即使用户在管理界面输入了合法的 JSON 结构，系统也会自动将其转换为字符串类型，导致客户端应用解析失败。

技术实现细节

新版 Pocket-ID 通过以下方式实现了这一功能：

1. 声明类型扩展：除了传统的字符串类型，现在支持三种声明数据类型：

   • String（字符串）
   • List（列表）
   • JSON Object（JSON对象）

2. 数据序列化处理：系统会保持原始数据结构，不再强制转换为字符串。例如：

   {
     "abspermissions": {
       "canDownload": true,
       "allowedTags": ["Test"]
     }
   }
   

3. 向后兼容：确保不影响现有仅支持字符串声明的客户端应用

实际应用场景

这项改进特别适合以下场景：

1. 复杂权限系统：如 Audiobookshelf 需要传递结构化权限信息
2. 用户属性扩展：当需要传递嵌套或复杂用户属性时
3. 多应用集成：不同应用间需要共享结构化数据时

开发者注意事项

1. 客户端应用在解析声明时，应做好类型检查
2. 对于需要严格类型约束的场景，建议在文档中明确声明期望的数据类型
3. 在迁移现有系统时，注意检查依赖字符串类型声明的代码

这项功能升级体现了 Pocket-ID 对开发者友好性和灵活性的持续追求，为构建更复杂的认证和授权场景提供了更好的支持。