Release Notes

此发行版本默认添加了对 LDAP 引用的过滤。这个变化增强了安全性，并与 LDAP 配置的最佳实践一致。如果此更改不可接受，您可以在所有域中的所有 LDAP 提供程序中禁用 LDAP 引用。

选项 spi-storage-​ldap-​secure-referral 用于禁用过滤引用已弃用。当这个功能在以后的发行版本中被删除时，将强制执行过滤。

为提高安全性，只有具有 master realm （服务器管理员）中的 admin 角色的用户才能分配 admin 角色。这样可确保关键权限不能被 realm-level 管理员委派。

此发行版本引进了对 Fine-Grained Admin 权限的新版本的支持。版本 2 (V2)提供对域中管理访问权限的增强灵活性和控制。借助此功能，管理员可以定义管理用户、组、客户端和角色的权限，而无需依赖广泛的管理角色。V2 提供与之前版本相同的域资源访问控制级别，并计划在未来版本中扩展其功能。以下是一些关键点：

如需了解更多详细信息，请参阅 Fine-Grained Admin Permissions。有关迁移的更多信息，请参阅 升级指南。

此发行版本引入了对标准令牌交换的基本支持。此功能当前仅限于将内部令牌交换到符合 令牌交换规格 的内部令牌。计划覆盖与身份代理或主题模拟相关的其他用例。

如需了解更多详细信息，请参阅 标准令牌交换。

有关如何从以前的红帽构建的 Keycloak 版本中使用的旧令牌交换 升级的详情，请参考升级指南。

最新版本的 OpenID Connect Core 规范 在 JWT 客户端断言中对客户端验证方法 private_key_jwt 和 client_secret_jwt 进行了严格验证。Red Hat build of Keycloak 现在默认强制使用单个 audience 用于客户端身份验证。

有关 Red Hat build of Keycloak 版本中的 JWT Client authentication 中更改的 audience 验证的详情，请参阅 升级指南。

这些更新与 Operator 指南中的主题相关。

这些更新与 Observability Guide 中涵盖的主题相关，这是本发行版本的一个新指南。

Red Hat build of Keycloak 现在使用其数据库发现同一集群的其他节点，这无需额外的网络相关配置，特别是云供应商。这也是在云环境中无需修改工作的默认操作。以前版本的 Keycloak 使用 UDP 多播作为默认情况来发现其他节点来组成集群，并同步红帽构建的 Keycloak 的复制缓存。这要求提供多播并正确配置，这通常不适用于云环境。

从此版本开始，jdbc-ping 配置的默认更改使用红帽构建的 Keycloak 数据库发现其他节点。这个变化消除了对多播网络功能和 UDP 的需求，不再对基于 TCP 的故障检测使用动态端口。这简化了使用之前默认设置的环境替换。要启用之前的行为，请选择传输堆栈 udp， 它现已弃用。

Red Hat build of Keycloak Operator 将继续将 kubernetes 配置为传输堆栈。

如需更多信息 ，请参阅配置分布式缓存。

从这个版本开始，红帽构建的 Keycloak 会在带有至少 2 个 CPU 内核的环境中运行时，在嵌入的 Infinispan 和 JGroups 中启用虚拟线程池支持。此更改消除了配置 JGroups 线程池的需求，并且需要使 JGroups 线程池与 HTTP 工作线程池保持一致；它还可减少整体内存占用。

如果没有提供--cache- config-file 选项，则之前的版本会忽略对 conf/cache- ispn.xml 的任何更改。

从这个版本开始，如果没有设置 when-cache-config-file，默认的 Infinispan XML 配置文件为 conf/cache-ispn.xml，因为这是预期的行为，以及给出当前和之前版本文档所暗示的行为。

现在，可以将特定于类别的日志级别设置为单独的 log-level-category 选项。

如需了解更多详细信息，请参阅将 级别配置为单独的选项。

所有可用的日志处理程序现在支持 ECS (Elastic Common Schema) JSON 格式。它有助于改进红帽构建的 Keycloak 可观察性故事和集中式日志记录。

如需了解更多详细信息，请参阅 日志记录。

选项 Minimum ACR 值作为 realm OIDC 客户端的配置选项添加。这个添加是与步骤身份验证相关的增强，因此可以在登录到特定客户端时强制实施最小 ACR 级别。

现在，初始用户 注册标准 支持，它允许 OIDC 客户端使用参数 prompt=create 启动登录请求，通知红帽构建的 Keycloak，它应该注册了新用户，而不是现有的用户通过身份验证。红帽构建的 Keycloak 支持启动用户注册，且使用了专用端点 /realms/<realm>/protocol/openid-connect/registrations。但是，这个端点现已弃用，因为它是特定于红帽构建的 Keycloak 的存储解决方案。

适用于 EC-DSA 和 Ed-DSA 密钥提供程序的新选项 generate 证书。当生成的密钥由域管理员创建时，可能会为此密钥生成一个证书。证书信息可在 Admin Console 和此密钥的 JWK 表示中找到，该密钥可通过带有 realm 密钥的 JWKS 端点获得。

现在，对 授权代码绑定的支持存在 DPoP 密钥，包括对带有推送授权请求的 DPoP 的支持。

OIDC 身份验证请求支持有限数量的附加自定义参数，最大长度。其他参数可用于自定义目的（例如，使用协议映射程序将声明添加到令牌中）。在以前的版本中，参数的最大计数被硬编码为 5，参数的最大长度被硬编码为 2000。现在，这两个值都可以被配置。另外，如果附加参数导致请求失败，或者参数被忽略，则可以配置。

如果您使用 Microsoft AD 并通过管理界面创建用户，则用户将默认创建为启用。

在以前的版本中，只能在将（非临时）密码设置为用户后更新用户状态。这个行为与其他内置用户存储以及 LDAP 供应商支持的其他 LDAP 供应商不一致。

可以设置 https-management-certificates-reload-period 选项来定义管理界面的 https-management- certificates 选项引用的密钥存储、信任存储和证书文件的重新载入周期。使用 -1 禁用重新加载，默认为 https-certificates-reload-period，即 1h （一小时）。

如需更多信息 ，请参阅配置管理界面。

对于集群多个节点，红帽构建的 Keycloak 使用分布式缓存。从此发行版本对所有基于 TCP 的传输堆栈开始，节点之间的通信与 TLS 加密，并使用自动生成的临时密钥和证书进行保护。

这增强了一个安全的默认设置，并尽可能减少新设置的配置步骤。

如果您不使用基于 TCP 的传输堆栈，建议迁移到 jdbc-ping 传输堆栈，以便从简化的配置和增强的安全性中受益。

如果您提供自己的密钥存储和信任存储来保护之前版本中 TCP 传输堆栈通信，则现在建议迁移到自动生成的临时密钥和证书，以便从简化的设置中获益。

如果您使用自定义传输堆栈，可以通过将 option cache-embedded-mtls-enabled 选项设置为 false 来禁用此默认行为。

如需更多信息，请参阅 保护传输堆栈。

用于验证 X.509 验证器中的证书撤销列表(CRL)现在被缓存在名为 crl 的新 infinispan 缓存中。缓存提高了验证性能并降低内存消耗，因为每个源仅维护一个 CRL。

检查 All provider configuration 章节的 crl-storage 部分，以了解新缓存提供程序的选项。

Condition - 子流 执行和 Condition - 客户端范围是 红帽构建的 Keycloak 中的新条件验证器。condition Condition - 子流执行检查之前的子流是否在身份验证流执行过程中成功执行（或未执行 ）。condition Condition - 客户端范围 检查配置的客户端范围是否存在，作为请求身份验证的客户端范围。如需了解更多详细信息，请参阅 条件流中的条件。

当为红帽构建的 Keycloak 开发扩展时，开发人员现在可以通过在 ProviderFactory 接口中实施方法 dependentOn （） 来指定供应商工厂类之间的依赖关系。有关详细描述，请参阅 Javadoc。

现在，所有 keycloak 都启用了 dark 模式支持。此功能以前存在于管理控制台、帐户控制台和登录页面中，现在也可在欢迎页面中找到。如果用户表示通过操作系统设置（如 light 或 dark 模式）或用户代理设置表示首选项，则主题会自动遵循该首选项。

如果您使用扩展 keycloak 主题的自定义主题，且您没有准备好支持 dark 模式，或者您存在阻止实施 dark 模式的冲突，您可以通过将以下属性添加到您的主题来禁用支持：

darkMode=false

另外，您可以通过在 realm 设置的 Theme 选项卡中关闭 Dark mode 设置来禁用对内置 Keycloak 主题的支持。

在以前的版本中，点 Admin Console 中的所有活跃会话 会导致仅删除常规会话。尽管有效无效，仍会显示离线会话。

这种方法已更改。现在，在注销所有活跃会话时，所有会话（常规和离线）都会被删除。

在这个发行版本中，红帽构建的 Keycloak JavaScript 适配器和红帽构建的 Keycloak Node.js 适配器将有一个独立于红帽构建的 Keycloak 服务器发行周期。26.2.0 发行版本可能是最后一个适配器，这些适配器与红帽构建的 Keycloak 服务器一起发布，但现在，这些适配器可以在与红帽构建的 Keycloak 服务器不同时发布。

KEYCLOAK_SESSION cookie 的格式已更新，以纯文本形式省略任何私有数据。到目前为止，cookie 的格式是 realmName/userId/userSessionId。现在，cookie 包含用户会话 ID，由 SHA-256 和 URL 编码。

AUTH_SESSION_ID cookie 的格式已更新，以包含 auth 会话 ID 的签名，以通过签名验证来确保其完整性。新格式为 base64 (auth_session_id.auth_session_id_signature)。在这个版本中，旧格式将不再被接受，这意味着旧的 auth 会话将不再有效。这个更改不会影响用户会话。

当您实施自己的供应商时，这些更改可能会影响您，并且您依赖内部 Keycloak Cookie 的格式。

允许您导入外部生成的密钥(rsa 和 java-keystore factories)的密钥供应商现在检查相关证书的有效性（如果存在）。因此，红帽构建的 Keycloak 中无法再导入过期证书的密钥。如果证书在运行时过期，密钥将转换为被动密钥（启用但不活跃）。被动密钥不用于新令牌，但仍然有效来验证先前发布的令牌。

默认 生成的密钥 供应商生成证书有效期为 10 年（具有或具有关联证书的类型）。由于长期有效性以及经常轮转密钥的建议，因此生成的供应商不会执行这个检查。

在本发行版本中，在事件触发时，管理事件可能会保存有关上下文的更多详情。在升级过程中，您应该预期更新数据库模式，来将新列opg _JSON 添加到 ADMIN_EVENT_ENTITY 表中。

除了前面的 yyyy-MM-dd 格式外，Admin Events API 现在支持根据 Epoc 时间戳过滤事件。这提供了对要检索的事件窗口的更精细的控制。

另外还添加了 direction 查询参数，允许控制返回的项目的顺序（如 asc 或'desc'）。在以前的版本中，事件总是以 desc 顺序返回（首先是最新的事件）。

最后，返回的事件表示现在包含 id，它为事件提供唯一标识符。

X.509 authenticator 有一个新的选项 x509-cert-auth-crl-abort-if-non-updated (如果管理控制台中未更新，则为 CRL 中止 )。如果将 CRL 配置为验证证书，且在下一次更新字段中指定的时间不会更新 CRL，这个选项将中止登录。新选项在 Admin Console 中默认为 true。有关 CRL 下一个更新字段的详情，请参阅 RFC5280、section-5.1.2.5。

为与之前的行为兼容，保持 false 值。请注意，现有配置没有新选项，并且将像此选项设为 false 时一样操作，但 Admin Console 会在编辑时添加默认值 true。

reset-credential-email (Send Reset Email)是 重置凭据 流(忘记密码 功能)中使用的验证器，用于将电子邮件发送到具有重置凭据令牌链接的用户。现在，这个验证器有一个新的选项 force-login (在重置后强制登录)。当此选项设为 true 时，验证器会终止会话并强制使用新的登录。

默认值为 only-federated，它支持 secure-by-default 策略。这个值表示，联合用户强制登录为 true，内部数据库用户为 false。因此，由用户联邦供应商管理的所有用户（其实现不能与红帽构建的 Keycloak 紧密集成）强制在重置凭证流后再次登录，以避免出现问题。

如需更多信息，请参阅启用忘记密码。

现在，您可以根据请求范围、ACR (Authentication Context Class Reference)等条件动态选择身份验证流。这可以通过将新的 AuthenticationFlowSelectorExecutor 与新的 ACRCondition 等条件相结合来实现。https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.2/html-single/server_administration_guide/#client_policies如需了解更多详细信息，请参阅 服务器管理指南。

到现在为止，使用 User API 查询用户凭证不会返回由用户存储供应商管理的凭证，因此，防止获取与联邦凭证关联的额外元数据，如最后一次更新凭证的时间。

在本发行版本中，我们向 org.keycloak.credential.CredentialInputUpdater 接口添加新的方法 getCredentials (RealmModel, UserModel)，以便用户存储供应商可以返回他们对域中特定用户管理的凭证。通过这样做，用户存储供应商可以指示凭证是否已链接到其中，并提供额外的元数据，以便在通过管理控制台管理用户时显示其他信息。

对于 LDAP，现在应该可以看到基于标准 pwdChangedTime 属性更新密码最后一次的时间；或者，如果使用 Microsoft AD，则基于 pwdLastSet 属性。

要检查凭证是否是本地 - 由红帽构建的 Keycloak - 或联邦管理，您可以检查 CredentialRepresentation 和 CredentialModel 类型中提供的 federationLink 属性。如果设置，federationLink 属性包含与给定用户存储供应商关联的组件模型的 UUID。

红帽构建的 Keycloak 传出 SMTP 邮件配置 现在支持令牌身份验证(XOAUTH2)。许多服务提供商（如 Microsoft 和 Google）正在移至 SMTP OAuth 身份验证，结束了对基本身份验证的支持。令牌通过 Client Credentials Grant 来收集。

添加了一个新的 admin 设置： Clients → Advanced → Fine grain OpenID Connect configuration → Use "at+jwt" as access token header type

如果启用，访问令牌将获取 位于+jwt 的标头类型，以遵守 rfc9068#section-2.1。否则，访问令牌标头类型将是 JWT。

默认设置为关闭此设置。

选项 spi-storage-​ldap-​secure-referral 用于禁用过滤引用已弃用。当这个功能在以后的发行版本中被删除时，将强制执行过滤。

在以前的版本中，db 选项默认为生产环境中的 dev-file （启动 ）和开发(start-dev)模式，而 dev-file 永远不会在 production 模式中被支持。在本发行版本中，我们弃用了此行为，在一些以后的发行版本中，db 选项不会在生产模式中默认为 dev-file。对于 build 或 non-optimized start 和 non-server 命令，在 production 配置集中 导入、导出 或 bootstrap-admin，应该明确提供一个值。

此更改是防止在生产环境中意外使用 dev-file (H2)数据库，这通常代表错误配置。

以下 JavaScript 授权客户端的 API 已被弃用，并将在下一个主发行版本中删除：

当在 KeycloakAuthorization 实例中调用方法时，不再需要这些 API，因为按需自动执行初始化。您可以安全地删除依赖于这些 API 的任何代码。

/realms/<realm>/protocol/openid-connect/registrations 端点（用于由 OIDC 客户端启动注册）现已弃用，因为存在从 OIDC 客户端启动注册的标准方法。现在，Red Hat build of Keycloak 支持这个方法。它使用参数 prompt=create。

Organization 和 OrganizationMembers API 中的 getAll （） 方法现已弃用，并将在下一个主发行版本中删除。反之，在 Organization 和 OrganizationMembers API 中使用对应的 list (first, max) 方法。

udp,jdbc-ping-udp,tcp,azure,ec2 和 google 传输堆栈已被弃用。用户应当使用基于 TCP 的 jdbc-ping 堆栈来直接替换。

由于 OpenShift v3 到期生命周期，所以从红帽构建的 Keycloak 中删除了对 OpenShift v3 的身份代理的支持。

以前默认包括的 robots.txt 文件现已被删除。默认 robots.txt 文件会阻止所有重写，这会阻止 noindex/nofollow 指令被跟随。所需默认行为是，红帽构建的 Keycloak 页面不会在搜索引擎结果中显示，这通过现有的 X-Robots-Tag 标头来完成，默认设为 none。如果需要不同的行为，则可以覆盖每个标头的值。

如果您之前在这个情况的反向代理配置中添加了规则，您现在可以将其删除。

因为红帽构建的 Keycloak 支持的用户代理不再支持 X-XSS-Protection 标头，所以它已被删除。此标头是 Internet Explorer、Chrome 和 Safari 的功能，在检测到跨站点脚本(XSS)攻击时，停止了加载的页面。

我们不会因为用户代理中缺少支持而影响任何部署，并且此功能由 内容安全策略(CSP) 提供。