Casdoor项目中OIDC标准的email_verified字段兼容性问题解析

在OAuth 2.0和OpenID Connect(OIDC)协议的实现过程中，字段命名规范是一个容易被忽视但十分关键的技术细节。本文将深入分析Casdoor开源身份认证系统中关于用户邮箱验证状态字段的标准化问题及其解决方案。

问题背景

Casdoor作为一个开源的身份和访问管理(IAM)系统，需要严格遵循OIDC协议标准。在标准协议中，明确规定了表示用户邮箱验证状态的字段应为"email_verified"（小写下划线格式）。然而在实际实现中，Casdoor使用了"emailVerified"（驼峰式命名）的字段名。

这种命名差异会导致与严格遵循OIDC标准的第三方应用（如Penpot设计协作平台）的集成问题。因为这些应用会严格按照协议规范检查"email_verified"字段，而无法识别Casdoor返回的"emailVerified"字段。

技术原理分析

OIDC核心规范第5.1节明确定义了标准声明(Standard Claims)，其中关于邮箱验证的字段定义为"email_verified"。这是一个布尔值字段，用于指示用户是否已完成邮箱验证。

在Casdoor的代码实现中，这个问题主要体现在两个关键位置：

1. JWT令牌生成逻辑中使用了驼峰式命名
2. 用户对象结构定义中也采用了非标准命名

解决方案

经过社区讨论和验证，发现Casdoor实际上已经通过用户信息端点(userinfo endpoint)正确返回了标准字段名"email_verified"。要解决集成问题，需要进行以下配置调整：

1. 将Token格式设置为"JWT-STANDARD"
2. 确保客户端应用从用户信息端点获取用户信息，而非直接从访问令牌(access token)中解析

这种设计实际上体现了Casdoor的灵活性 - 既支持直接解析JWT中的声明，也支持通过标准用户信息端点获取规范化数据。对于严格要求符合OIDC标准的应用，应优先使用后者。

最佳实践建议

对于Casdoor管理员和开发者，在处理OIDC集成时应注意：

1. 对于兼容性要求高的场景，始终使用"JWT-STANDARD"格式
2. 在客户端实现中，优先通过用户信息端点获取用户属性
3. 开发自定义应用时，对字段命名保持灵活性，考虑同时支持标准和自定义命名
4. 在系统文档中明确标注各字段的命名规范和使用场景

通过遵循这些实践，可以确保Casdoor既保持自身的开发灵活性，又能完美兼容各类遵循OIDC标准的第三方应用。