2.5. 版本 26.4.2 的显著变化

如果您要通过下载发行版升级 Red Hat build of Keycloak，则升级过程已更改。在以前的版本中，建议将 conf/ 文件夹的内容从旧复制到新安装。新流程建议根据新版本中包含的文件重新应用对 cache-ispn.xml 或自定义缓存配置的任何更改。

这可以防止意外降级功能，例如，通过在以前的版本中使用旧的 cache-ispn.xml 文件。

现在，配置数据库中会显示每个数据库的支持版本。https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.4/html-single/server_configuration_guide/db-#db-但是，如果底层数据库特定的 Hibernate dialect 允许使用与显示的不同版本，则它不是受支持的配置。

如果您要通过 User API 查询用户，其中您要获取与特定属性键（除了值）匹配的用户，在调用 /admin/realms/{realm}/users 时，请考虑将 确切的 请求参数设置为 false。

例如，搜索属性 myattribute 设置的所有用户，如下所示：

GET /admin/realms/{realm}/users?exact=false&q=myattribute:

GET /admin/realms/{realm}/users?exact=false&q=myattribute:

Red Hat build of Keycloak Admin Client 也使用新方法更新，以便使用 确切的 请求参数根据属性搜索用户。

当在域设置中禁用 "Remember Me" 选项时，之前使用"Remember Me"标记创建的所有用户会话现在都被视为无效。用户将需要再次登录，关联的刷新令牌将不再可用。在没有选择 "Remember Me" 的情况下创建的用户会话不受影响。

在运行 PostgreSQL 读取器和写器实例时，红帽构建的 Keycloak 需要始终连接到写入器实例才能正常工作。

从这个版本开始，在使用原始 PostgreSQL 驱动程序时，红帽 Keycloak 的 build 会将 PostgreSQL JDBC 驱动程序的 targetServerType 属性设置为 primary，以确保它始终连接到可写的主实例，且永远不会在故障转移或切换场景中连接到二级 reader 实例。

您可以通过在 DB URL 或附加属性中为 targetServerType 设置自己的值来覆盖此行为。

EVENT_ENTITY 表现在有一个索引 IDX_EVENT_ENTITY_USER_ID_TYPE，列 USER_ID、TYPE 和 EVENT_TIME，它允许在 Admin 控制台中对特定用户和事件类型的事件进行快速搜索。

如果表包含超过 300,000 个条目，红帽构建的 Keycloak 会在自动模式迁移期间跳过索引创建。但是，SQL 语句会在迁移过程中显示在控制台中，以便您可以在红帽构建 Keycloak 启动后手动应用它。有关配置其他限制的详情，请参阅 迁移数据库。

如果您在 FIPS 140-2 模式下运行红帽构建的 Keycloak，请将 Bouncy Castle 库更新至发行文档中列出的版本。

当升级到 Bouncy Castle 2.1.x 时，现在 FIPS 140-2 模式支持 EdDSA。

当使用远程缓存时，如果 Data Grid 服务器上不存在，红帽构建的 Keycloak 现在会在启动过程中自动创建必要的缓存。

对于多集群设置，仍建议预先使用 Cache CR 创建缓存，以验证缓存的正确初始化，并避免在缓存只在其中一个站点中存在缓存时启动错误。

以前的红帽构建的 Keycloak 版本会警告有问题的配置，例如，如果配置了错误的所有者，或者在启用易失性用户会话时没有设置缓存大小。本文档还声明为易失性用户会话更新 cache-ispn.xml 配置文件。

当前版本始终将安全设置用于受影响的用户和客户端会话缓存的所有者数和最大缓存大小，并且仅记录 INFO 消息。使用这个行为，您不再需要更新 cache-ispn.xml 配置文件。如果您之前使用自定义 cache-ispn.xml 来使用 volatile 用户会话，我们建议恢复这些更改并使用标准配置文件。

conf/cache-ispn.xml 文件不再包含默认的缓存配置。您仍然可以覆盖此文件中红帽构建的 Keycloak 使用的缓存配置，但如果未设置 the -cache-config-mutate=true 选项，Red Hat build of Keycloak 会记录警告。您仍然可以在不设置这个选项的情况下添加自定义缓存。

在升级现有部署时，从现有的 conf/cache-ispn.xml 中删除所有默认缓存配置，并使用 the-cache-... 选项更改缓存大小。

为了防止数据库服务器意外关闭连接，需要确保针对服务器的 wait_timeout 设置正确配置红帽构建的 Keycloak 连接池。

从这个版本开始，红帽构建的 Keycloak 定义了默认的 db-pool-max-lifetime 为 7 小时，MySQL 和 MariaDB 数据库的 50 分钟，因为默认的 wait_timeout 为 8 小时。

如果服务器定义了大于默认值的 wait_timeout，或者提供了 db-pool-max-lifetime 值，则会在 Keycloak 启动的红帽构建中记录警告。

Red Hat build of Keycloak 现在在 root URL 级别 /.well-known/ 中公开一个 RFC8414-compliant 端点，以便客户端通过签发者 URL 发现 OAuth 2.0 授权服务器元数据和其他已知的供应商。

例如，OAuth 2.0 授权服务器元数据信息由此 URL 公开：

https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server

https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server

现在，这个 URL 还提供：

https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}

https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}

若要从此中受益，请在反向代理配置中公开路径 /.well-known/。

默认调度策略已被更新，以便为区和节点创建一个拓扑分布约束，以便在存在故障时增加可用性。在以前的版本中，默认策略首选所有节点都部署到同一可用区。如需了解更多详细信息，请参阅 高可用性指南。

在以前的版本中，配置 JGroups 网络地址和端口，您需要使用 jgroups.bind nginx 和 jgroups.external 的 system 属性。此发行版本引进了以下 CLI 选项，允许这些地址和端口由红帽构建的 Keycloak 直接配置：

使用旧属性配置端口没有改变，但建议使用 CLI 选项，因为前面的方法可能被弃用。

经过身份验证的客户端会话的缓存密钥已针对嵌入式 Infinispan 进行了更改，而公共 API 没有改变。因此，您不能在之前版本的集群中同时运行 26.4.1。

当使用 /realms/{realm-name}/broker/{provider_alias}/token 端点作为 OAuth 2.0 IDP （提供刷新令牌和 JSON 响应）或 OIDC IDPs 时，如果访问令牌已过期，则令牌将自动通过端点检索，如果访问令牌已过期，并且 IDP 提供了刷新令牌。

当使用 GitHub 作为 IDP 时，您现在可以启用 JSON 响应来利用此端点的令牌刷新。

默认情况下，关闭持久用户会话更新的批处理，因为它对一些数据库供应商的性能造成负面影响，这会给其他数据库供应商带来的好处。您可以使用 CLI 选项 --spi-user-sessions-​infinispan-​use-batches=true 启用批处理，但建议用户加载测试其环境以验证性能改进。

会话备注的名称现在作为管理控制台中的必填字段显示。

令牌声明的名称现在作为 Admin 控制台中的必填字段显示。

从这个版本开始，当启用易失性用户会话时，红帽默认只为内存中离线用户和客户端会话的 10,000 个条目构建 Keycloak 缓存。这个变化大大减少了内存用量。

要更改离线会话缓存的大小，请使用 cache-embedded-offline-sessions-max-count 和 cache-embedded-offline-client-sessions-max-count 选项。

在类加载器和基于文件夹中的资源捆绑包的命名现在与 Java ResourceBunndle failinggetBundle 文件名一致。对于所有包含的社区语言（如 de 或 pt-BR ），文件仍然命名为 messages_de.properties 或 messages_pt_BR.properties。如果您添加了自定义语言代码，请检查您的文件名是否仍相同。

"Chinese （传统）" 和 "Chinese (simplified) " 语言被命名，因为红帽构建的 Keycloak 社区中 zh-TW 和 zh-CN 的原因被命名为 zh-TW 和 zh-CN。作为迁移到新语言代码 zh-Hant 和 zh-Hans，基于类加载器和文件夹的开始，基于旧语言代码 zh-TW 和 zh-CN 以及 messages_zh_Hant.properties 和 messages_zh_Hant.properties 文件。messages_zh_Hant.properties 中的条目优先于 messages_zh_TW.properties 中的条目，而 messages_zh_Hans.properties 中的条目优先于 messages_zh_CN.properties 中的条目。

更新 Email 现在是一个支持的功能，因此在服务器启动过程中它现在被启用。如果在域中启用了 Update Email required 操作，则为域启用该功能。在身份验证流过程中更新配置集时，该功能会稍微更改之前版本的行为（比如在运行 UPDATE_PROFILE required 操作时）。如果用户在身份验证流中更新配置集时设置了电子邮件，则 email 属性不可用。

当 SAML 客户端启用 Encrypt Assertions 时，SAML 响应中包含的断言会根据 XML 加密语法和处理 规格进行加密。用于加密的算法已被修复且过时。从这个版本开始，默认加密选项为最新版本，并更适合安全。另外，如果特定客户端需要不同的算法，您可以配置加密详情。您可以在客户端中定义新属性，以指定用于加密的确切算法。在 Admin Console 中，当在 Keys 选项卡中启用 Encrypt Assertions 时，这些属性会出现在客户端设置选项卡、Signature 和 Encryption 部分中。

为了保持向后兼容性，红帽构建的 Keycloak 升级会修改现有的 SAML 客户端，以设置加密属性，如以前一样工作。因此，现有客户端使用相同的之前的算法接收相同的加密断言。如果客户端支持新的默认配置，则建议删除属性。

有关客户端配置的更多信息，请参阅创建 SAML 客户端。

当验证电子邮件地址作为所需操作或应用程序启动操作时，用户默认只能每 30 秒重新发送验证电子邮件，而在早期版本中没有限制重新发送电子邮件。

管理员可以在域的 Authentication 部分中 验证电子邮件 所需操作中为每个域配置间隔。

启用追踪后，对红帽构建的 Keycloak 集群的其他节点调用现在在 trace 中创建 span。

要禁用这种追踪，请将选项 tracing-infinispan-enabled 设置为 false。

如果没有在 LDAP 配置上将值指定为 connectionTimeout，或通过 com.sun.jndi.ldap.connect.timeout 系统属性指定，则默认的超时为 5 秒。此超时可确保请求看到错误，而不是在从池中获取 LDAP 连接或连接 LDAP 服务器时等待。

OTP 和恢复代码的登录主题中的输入字段并已被优化：

当发送 OIDC 身份验证请求（或 OAuth2 授权请求）时，每个标准 OIDC/OAuth2 参数的最大长度存在一个新的限制。每个标准参数的最大长度为 4,000 个字符，它是可能在以后的版本中减少的大量数字。现在，为了向后兼容，它仍然很大。唯一的例外是 login_hint 参数，其长度最大为 255 个字符。这个值与默认用户配置集配置中配置的 用户名和电子邮件 属性的最大长度一致。

如果要增加或降低这些数字，请使用标准 OIDC/OAuth2 参数的默认最大长度 req-params-default-max-size 选项启动服务器，或者您可以使用一个特定参数的 req-params-max-size 等内容。如需了解更多详细信息，请参阅 All provider configuration 下的 login-protocol 供应商配置。

从这个版本开始，红帽构建的 Keycloak 添加了一个新的选项，允许为 域 SMTP 配置（在管理控制台的 Realm 设置 部分中 Email 选项卡中的 Email 选项卡中的Allow UTF-8 字段）。有关电子邮件配置的更多信息 ，请参阅为域配置电子邮件。

在发送时，启用选项会在 UTF-8 中对电子邮件地址进行编码，但它依赖于 SMTP 服务器来支持 SMTPUTF8 扩展的 UTF-8。如果禁用 Allow UTF-8，红帽构建的 Keycloak 将对电子邮件地址的域部分进行编码（如果使用了非 ASCIII 字符），并使用 punycode 对电子邮件地址进行编码，并将拒绝在本地部分中使用非 ASCIII 字符的电子邮件地址。内置的 User Profile 电子邮件验证器还检查地址的本地部分在禁用此选项时仅包含 ASCII 字符，从而避免注册 SMTP 配置无法使用的电子邮件。

如果您为域配置了 SMTP 服务器，请升级后执行以下迁移：

在 Admin Console 或 User API 中搜索用户时，从 /admin/realms/{realm}/users/count 端点返回的用户数现在与执行 /admin/realms/{realm}/users }/users}/users 时返回的实际用户数保持一致。

如果您依赖用户计数端点，请确保检查您的客户端，以便它们预期用户计数与搜索返回的实际用户数量保持一致。

添加 OTP、WebAuthn 或任何其他 2FA 凭据时，用户分配给此凭据的名称需要对给定用户是唯一的。这允许用户区分这些凭据，并在以后更新或删除它们。如果用户尝试使用已存在的名称创建凭证，则会显示错误消息，用户需要更改新凭据的名称。

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

到目前为止，OpenID Connect 代理不支持 OpenID Connect 供应商发布的 ID 令牌中的标准 email_verified 声明。

在这个发行版本中，代理被更新为遵守此声明中的值，以便为联邦（本地）用户帐户设置电子邮件验证状态。每当用户首次联合或重新验证时，如果启用了 Trust email 设置，并且 Sync Mode 设置为 FORCE，则用户帐户将更新为（取消）将电子邮件标记为（取消）。如果提供程序没有发送声明，则默认为原始行为，并根据验证设置电子邮件。

以后，我们可能会评估更改此特定配置，以避免基于联合用户帐户的电子邮件验证状态自动更新，具体取决于用例和社区的需求。

执行验证 现有帐户是第一个 登录流必须允许代理帐户链接到现有 Keycloak 用户的红帽构建的替代方案之一。当用户第一次通过代理登录到红帽构建的 Keycloak 时，会执行这一步，并且红帽构建的 Keycloak 中已存在身份提供程序帐户。执行会向当前红帽构建的 Keycloak 地址发送电子邮件，以确认用户控制该帐户。

由于此版本，只有外部身份提供程序发送的链接属性( 电子邮件和用户名)在审核过程中用户不会修改第一个 登录流 中，则验证现有帐户 by 电子邮件执行才会在第一个登录流中尝试。这个新行为可避免向可意外接受链接的现有红帽构建的 Keycloak 帐户发送验证电子邮件。

如果供应商需要修改身份提供程序发送的信息（因为代理中的电子邮件或用户名不同），则只有其他替代的 Verify Existing Account By Re-authentication 可将新帐户链接到现有的 Red Hat build of Keycloak 用户。

如果从身份提供程序接收的数据是必需的且无法修改，则可以禁用第一个登录流中的 Review Profile 步骤以避免用户干预。

如需更多信息，请参阅 第一个登录流。

在以前的版本中，当用户更新其凭证时，如更改密码或添加另一个因素（如 OTP 或 Passkey），它们默认 从其他设备 签名。从这个版本起，红帽构建的 Keycloak 显示从其他设备 注销的复选框，默认情况下不从其他设备 注销。现在，用户会有意启用此复选框，以注销与同一用户关联的所有相关会话。

与之前版本相关的，在以前的版本中，从其它 devices 复选框注销 只注销常规会话。从这个版本开始，它会退出离线会话，因为这是用户在当前屏幕设计时预期的情况。

要恢复到旧行为，启用已弃用的功能 logout-all-sessions:v1。此已弃用的功能将在以后的版本中删除。

Welcome Page 创建常规管理员用户，而不是临时用户。

细粒度 admin 权限(FGAP)功能现在包含一个新的范围： reset-password。此范围允许向管理员授予特定权限以重置用户密码，而不必授予他们更广泛的 管理 范围。

默认情况下，具有现有、更广泛的 USERS 资源类型的 管理 范围的用户将隐式具有重置用户密码的权限。系统首先检查显式 reset-password 范围。如果没有找到该权限，它将回退到检查管理员是否有 管理 范围。这样可确保现有具有 管理 范围的管理员继续能够重置密码，而无需更改其权限。

这种隐式回退机制确保了已经使用细粒度权限的部署有平稳的升级过程。回退将在以后的版本中被弃用并删除，因此建议查看和更新管理员权限，以便在适当的时候使用新的 reset-password 范围。

如需了解更多详细信息，请参阅 细粒度 admin 权限。

到目前为止，当从 LDAP 用户联邦供应商搜索用户时失败会导致整个请求失败，且不会返回用户。在本发行版本中，如果在搜索过程中发生错误，仍然会返回本地用户，并且错误将在 ERROR 级别记录，以便管理员可以调查问题的根本原因，并修复其 LDAP 配置或与 LDAP 服务器连接的问题。

当 LDAP 服务器出现临时问题时，这个变化提高了系统的弹性，确保仍可以访问本地用户，即使 LDAP 搜索失败。如果本地用户链接到失败的 LDAP 提供程序，该用户将被标记为 disabled 和 read-only，直到 LDAP 服务器再次可用为止。

从这个版本开始，admin 控制台用来获取红帽构建的 Keycloak 安装的一般信息的 serverinfo 端点只会返回管理(master)域中管理员的系统信息。这个变化是出于安全原因完成的。

如果出于某种原因，通用域中的管理员需要访问 serverinfo 响应的 systemInfo、cpuInfo 或 memoryInfo 字段，您需要为该 admin 用户创建并分配一个新的 view-system 角色：

以前的临时解决方案标记为已弃用，它可以在以后的 Red Hat build of Keycloak 版本中删除。

server-spi-private 模块中的 SimpleHttp util 重构并移到 org.keycloak.http.simple 软件包。

user-profile-commons.ftl 被更改为改进对本地化的支持。因此，如果您要扩展此模板，页面可能会开始显示 locale 字段。为避免这种情况，请使用上述更改更新主题模板。

当返回组的子组时，组的每个子组的子组计数不再会被缓存。随着 Fine-Grained Admin 权限引入，结果设置会根据定义为某个域的任何权限在数据库级别过滤，以便计数将相应地更改为这些权限。

不必缓存计数，每次都会执行查询以获取管理员可访问的预期组数。

大多数时候，此更改不会影响查询 API 的客户端来获取组的子组。但是，如果不是这种情况，则会向以下端点引入了一个新的参数 subGroupsCount ：

使用此参数，客户端可以决定是否要将计数返回给每个单独的组。如果不破坏现有部署，此参数默认为 true，以便在未设置该参数时返回计数。

在以前的版本中，默认 浏览器 流有一个 浏览器 - 条件 OTP 条件子流，它启用了一次性密码(OTP)作为第二因素身份验证(2FA)。从此版本开始，子流被重命名为 Browser - Conditional 2FA, OTP Form is Alternative，并包含两个 2FA 方法： WebAuthn Authenticator 和 Recovery Authentication Code Form。默认情况下，两个新执行都为 Disabled，但可以设置为 alternatives，将它们包含在流中。

升级的域不会被更改。更新的流程仅适用于新域。如果您自动化了域创建，请考虑此更改。

通过 tcp （或 ssl-tcp）协议发送的 syslog 消息现在默认使用计算，为某些 Syslog 服务器所需的大小添加前缀。

要更改此行为，请使用 --log-syslog-counting-framing 选项以及以下值之一： 协议独立 （默认）、true 或 false。

在版本 26.4.1 时，某些功能已被删除，其他功能被标记为已弃用，以便在后续版本中删除。有关这些更改的详情，请查看 发行注记。