Keycloak 26.8.0发布：数字钱包凭证与令牌交换委托新特性

技术要点

Keycloak 26.8.0版本的核心更新围绕用户与管理员的新能力展开，主要特性如下：

1. 可验证凭证（Verifiable Credential）相关功能：
   • OID4VCI（OpenID for Verifiable Credential Issuance）：此功能已从实验性提升至预览状态。可通过 --features=preview 或 --features=oid4vc-vci 启用。它支持凭证生命周期管理，包括在刷新令牌被撤销时进行凭证撤销，并新增Application Initiated Action (AIA) 允许用户在已认证会话内请求凭证颁发。密钥证明（key attestation）可在管理控制台中配置，并遵循HAIP profile进行强化的x5c证书验证。
   • OID4VP（OpenID for Verifiable Presentation）：此功能为实验性支持。Keycloak可作为OID4VP验证器，支持用户从数字钱包呈现可验证凭证进行登录的流程。验证器支持跨设备呈现流程和 direct_post.jwt 加密响应模式。凭证验证的信任材料可通过别名委托给外部身份提供者，并提供SD-JWT用户属性映射器和会话映射器以从呈现的凭证中提取声明。
   • mdoc格式支持：新增实验性特性 oid4vc-mdoc 以支持mdoc格式。
2. 用户供应与集群部署：
   • SCIM API：新增通过SCIM API自动化跨身份系统的用户供应功能。
   • 无状态模式（Stateless Mode）：支持在无外部缓存的情况下运行多集群部署，此功能现已支持。
3. 管理优化：
   • 自动索引创建、内存使用减少以及HTTP性能增强，使管理更简单。
4. 令牌交换委托：
   • 为AI代理和自动化工具提供带有同意和细粒度管理权限（FGAP）授权的令牌交换委托功能，此状态为预览。用户可通过OAuth同意将访问权委托给客户端应用，使用 delegation:client 参数化作用域。生成的令牌包含 act 声明标识客户端为行为者。委托授权完全通过FGAP V2的 delegate 和 delegate-members 作用域控制。委托审计事件现在包含客户端身份。
5. 其他安全与管理特性：
   • 共享信号框架（SSF）：实验性支持，现在在用户启用或禁用时发出RISC account-disabled 和 account-enabled 事件类型。
   • 参数化作用域（Parameterized Scopes）：从实验性提升至预览状态，允许客户端在OAuth 2.0授权请求中随作用域名传递参数值。
   • 冒充审计增强：当管理员冒充用户时，令牌生命周期事件（如 CODE_TO_TOKEN）现在 enriched 与冒充者及冒充者ID详情，且冒充会话签发的令牌在访问令牌和ID令牌中始终包含 act 声明。
   • 安全客户端集群节点注册：新增 secure-client-node-hostname 客户端策略执行器，用于保护 legacy adapter 集群节点注册端点免受SSRF攻击，通过正则表达式模式验证主机名。

原理与背景

本次发布的功能主要解决了身份管理中的几个关键问题：

• 数字钱包与可验证凭证的集成：随着数字身份和可验证凭证的普及，组织需要安全、标准化的方式颁发和验证这些凭证。OID4VCI和OID4VP标准的引入，使得Keycloak能够作为凭证颁发者和验证者，与数字钱包交互，从而支持无密码登录和可信身份呈现，提升用户体验和安全性。
• 跨系统用户供应自动化：在复杂的企业环境中，用户身份需要在多个系统间同步。SCIM API的提供，使得Keycloak能够与其他身份管理系统自动化地同步用户信息，减少手动操作和错误。
• 简化集群部署架构：传统多集群部署往往依赖外部缓存来共享会话状态，增加了架构复杂性和运维成本。无状态模式的支持，允许Keycloak集群在不依赖外部缓存的情况下运行，简化了部署和扩展。
• 安全且受控的自动化访问：AI代理和自动化工具需要代表用户执行操作，但直接授予管理员权限或暴露敏感凭证风险很高。令牌交换委托功能通过OAuth同意流程和细粒度授权，允许用户有限度、可审计地委托访问权，确保自动化操作在用户控制和安全边界内进行。
• 增强审计与合规性：冒充操作是管理中的敏感行为。通过丰富令牌生命周期事件和强制添加 act 声明，提供了完整的冒充审计轨迹，帮助下游服务识别和追踪冒充行为，满足合规性要求。
• 防御特定攻击：legacy adapter 的节点注册端点存在SSRF风险。secure-client-node-hostname 执行器通过验证主机名，防止攻击者注册恶意主机名，从而保护管理回调的安全性。

落地建议

对于考虑升级或采用Keycloak 26.8.0新功能的团队，以下是一些通用建议：

1. 评估预览与实验性功能：OID4VCI、参数化作用域、令牌交换委托等功能处于预览状态，SCIM API、OID4VP、SSF等处于实验性状态。在生产环境使用前，应充分测试其稳定性、性能和对现有系统的影响。可通过相应的特性标志（如 --features=preview）启用。
2. 规划数字钱包集成：如果计划集成数字钱包凭证，需参考Keycloak提供的集成指南（如Lissi、Valera钱包）和示例应用，理解OID4VCI/VP协议流程，并配置好凭证管理、撤销和密钥证明等安全选项。
3. 实施SCIM API同步：在启用SCIM API前，需明确需要与Keycloak同步的用户数据模型和流程，确保目标系统也支持SCIM标准，并处理好数据冲突和同步频率问题。
4. 评估无状态集群部署：无状态模式支持多集群部署无需外部缓存，但需确保应用本身适合无状态会话管理。评估现有会话存储和集群配置，进行必要的调整以利用此特性。
5. 配置令牌交换委托安全策略：启用令牌交换委托后，应利用FGAP V2精细控制哪些客户端可以代表用户进行委托，并审查委托审计事件。对于AI代理等自动化场景，明确委托范围和权限边界。
6. 加强冒充操作审计：利用增强的冒充审计功能，在下游资源服务器和审计系统中解析 act 声明，实现对冒充行为的全面监控和追溯。
7. 防护legacy适配器风险：如果使用了legacy adapter的集群节点注册功能，务必配置 secure-client-node-hostname 客户端策略执行器，并定义允许的主机名正则模式，以防范SSRF攻击。
8. 遵循升级指南：从旧版本升级时，务必仔细阅读官方升级指南，了解所有变更、潜在破坏性变化以及配置迁移步骤，确保平滑升级。