Keycloak中Hybrid流程下离线访问令牌导致UserInfo请求失败问题分析

问题背景

在Keycloak 26.2.0版本中，当使用OpenID Connect的Hybrid流程(响应类型为code token或code token id_token)并请求offline_access范围时，系统会返回一个访问令牌。然而，当客户端尝试使用这个访问令牌请求UserInfo端点时，服务器会返回401未授权错误，错误信息为"user_session_not_found"。

这个问题导致Keycloak 26.2.0无法通过OpenID Foundation的OIDC一致性测试，而之前的版本则能够顺利通过测试。这是一个明显的回归问题，需要深入分析其根本原因。

技术细节分析

Hybrid流程与离线访问令牌

OpenID Connect的Hybrid流程是一种结合授权码流程和隐式流程的混合模式。在这种流程中，当客户端请求offline_access范围时，系统会生成一个特殊的离线访问令牌。这种令牌的设计初衷是允许客户端在用户不活跃时仍能访问受保护的资源。

问题表现

在Keycloak 26.2.0中，当同时满足以下条件时会出现问题：

1. 使用Hybrid流程(响应类型包含code和token)
2. 请求范围中包含offline_access
3. 尝试使用返回的访问令牌访问UserInfo端点

服务器日志显示，此时访问令牌的上下文信息为：

• 会话类型：OFFLINE
• 授权类型：未指定
• 令牌类型：REGULAR

根本原因

经过分析，这个问题与Keycloak内部对离线访问令牌的处理逻辑有关。在Hybrid流程中生成的访问令牌被错误地标记为离线令牌，而实际上它应该是一个常规的在线访问令牌。当UserInfo端点尝试验证这个令牌时，系统无法找到对应的用户会话，因为令牌被错误地归类为离线类型。

解决方案

Keycloak开发团队已经提交了修复这个问题的代码变更。主要修改点包括：

1. 修正Hybrid流程中访问令牌的类型判断逻辑
2. 确保在Hybrid流程中生成的访问令牌不被错误地标记为离线类型
3. 保持与OpenID Connect规范的兼容性

影响范围

这个问题主要影响以下使用场景：

• 使用Keycloak 26.2.0版本
• 采用OpenID Connect Hybrid流程
• 需要请求offline_access范围
• 需要访问UserInfo端点获取用户信息

最佳实践建议

对于需要使用Hybrid流程和离线访问功能的开发者，建议：

1. 升级到包含修复的Keycloak版本
2. 如果暂时无法升级，可以考虑使用标准授权码流程替代Hybrid流程
3. 在测试环境中充分验证UserInfo端点的访问情况
4. 关注Keycloak的版本更新日志，了解相关修复的详细信息

总结

这个问题的发现和修复过程展示了开源社区协作的力量。通过OpenID Foundation的一致性测试发现了这个回归问题，Keycloak团队迅速响应并提供了修复方案。这也提醒我们在升级身份认证系统时需要充分测试各种使用场景，确保核心功能的稳定性。