升级指南

默认支持主机名 v2 选项，因为旧的主机名选项已被移除。

所需迁移列表：

正如您所见，为主机名和 hostname -admin 选项删除了 *- url 后缀。选项 hostname 接受主机名和 URL，但 hostname-admin 现在只接受完整的 URL。

另外，无法单独设置 路径 或端口。您可以通过为主机名和 hostname -admin 选项提供完整的 URL 来达到此目的。

如果端口不是 URL 的一部分，它将从传入的请求标头动态解析。

HTTPS 不再强制执行，除非它是主机名和 hostname -admin URL 的一部分。如果没有指定，则使用协议(http/https)会从传入请求动态解析。hostname-strict-https 选项已被删除。

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --https-port=8543 --hostname-path=/auth --hostname-strict-https=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=https://mykeycloak.org:8543/auth

# Hostname v1
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-strict-backchannel=true

# Hostname v2
bin/kc.[sh|bat] start --hostname=mykeycloak.org --hostname-backchannel-dynamic=false

kcadm 和 kcreg 解析和处理选项和参数是如何改变的。来自使用错误（错误的选项或参数）的错误消息可能与之前的版本稍有不同。另外，使用错误时，退出代码为 2，而不是 1。

红帽构建的 Keycloak 没有在组路径中被转义的斜杠。因此，名为 top 的 group/slash 子组使用完整路径 /top/group/slash，这清楚误导。从这个版本开始，可以启动服务器以在名称中执行这些斜杠的转义：

bin/kc.[sh|bat] start --spi-group-jpa-escape-slashes-in-group-path=true

转义字符是波形符 ~。前面的示例生成路径 /top/group~/slash。转义将最后一个斜杠标记为名称的一部分，而不是层次结构分隔符。

默认情况下禁用转义，因为它代表了行为的更改。建议使用转义功能，但未来版本可能会成为默认设置。

在 master 域存在前使用-- import-realm 选项运行 start 或 start-dev 命令时，如果导入材料中存在，则会导入它。之前的行为是首先创建 master 域，然后其导入跳过。

优化的 启动选项现在需要首先构建优化的服务器镜像。这可以通过先运行 kc.sh|bat build 或通过任何其他服务器命令( 如启动、导出、导入)来实现。

选项 cache -stack, 和 cache-config-file 不再是构建选项，它们只能在运行时指定。这消除了执行构建阶段的需要，并因镜像而重建镜像。请注意，在构建阶段不会识别它们，因此您需要将它们从构建阶段删除，并将它们添加到 运行时 阶段。 如果您没有将当前缓存选项添加到 运行时 阶段，红帽构建的 Keycloak 将回退到默认的缓存设置。

在某些情况下，红帽构建的 Keycloak 使用 HTTP 与外部服务器进行通信。为了避免当那些供应商发送太多数据时拒绝服务，Red Hat build Keycloak 现在默认将响应限制为 10 MB。

用户可以通过设置供应商配置选项 spi-connections-http-client-default-max-consumed-response-size 来配置这个限制：

bin/kc.[sh|bat] --spi-connections-http-client-default-max-consumed-response-size=1000000

kc.[sh|bat] import 命令现在启用了占位符替换。在以前的版本中，在启动时只对域导入启用占位符替换。

如果要禁用 import 命令的占位符替换，请添加系统属性 -Dkeycloak.migration.replace-placeholders=false

在 Red Hat build of Keycloak 26 中，所有用户会话都默认保留在数据库中。通过禁用该功能，可以将此行为恢复到以前的状态。配置分布式缓存 指南中的 Volatile 用户会话 流程。

启用持久会话后，在线用户会话、离线用户会话、在线客户端会话和离线客户端会话的内存缓存会默认限制为每个节点 10000 个条目，这会减少 Keycloak 用于大型安装的总内存用量。根据需要，从内存驱除的项目将从数据库按需加载。启用这个功能后，预期会减少内存用量以及每次登录时数据库利用率增加，注销和刷新令牌请求。

要在红帽构建的 Keycloak 多站点设置中配置外部 Data Grid 中的缓存大小，请参阅使用 Data Grid Operator 部署 HA。

启用此功能后，选项 spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override 和 spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override 不再可用，因为它们之前用来覆盖离线会话已保持在内存中。

要在启用了 persistent-user-sessions 时注销一个域的所有在线用户会话，请执行以下步骤：

由于数据库现在是用户会话的真实来源，因此可以限制会话缓存的大小来减少内存用量。如果您使用默认的 conf/cache-ispn.xml 文件，则存储用户和客户端会话的缓存默认配置为仅存储 10000 会话和每个条目的一个所有者。

使用选项 cache-embedded-sessions-max-count, cache-embedded-client-sessions-max-count ,cache- embedded-offline-sessions-max-count 和 cache-embedded-offline-client-sessions-max-count 来更新缓存的大小。

有关更新的资源要求的详情，请参阅 调整 CPU 和内存资源概念。

现在默认启用嵌入式缓存的指标。要为延迟启用直方图，请将 cache-metrics-histograms-enabled 选项设置为 true。

红帽构建的 Keycloak 提供的指标现在包含以 http_server 开始的 HTTP 服务器指标。有关一些示例，请参见以下信息。

http_server_active_requests 1.0
http_server_requests_seconds_count{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 1.0
http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 0.048717142

使用新的选项 http-metrics-histograms-enabled 和 http-metrics-slos 启用默认的直方存储桶或特定存储桶以实现服务级别目标(SLO)。参阅 Prometheus 文档中的有关直方图的更多信息，了解如何使用 http_server_requests_seconds_bucket 中提供的额外指标系列。

管理端口 9000 上可以访问 /health 和 /metrics 端点，该端点默认开启。这意味着这些端点不再公开给红帽构建 Keycloak 端口 8080 和 8443。

要反映旧行为，请使用 property --legacy-observability-interface=true，这不会在管理端口上公开这些端点。但是，此属性已弃用，并将在以后的发行版本中删除，因此不建议使用它。

管理接口使用与默认红帽构建的 Keycloak HTTP 服务器不同的 HTTP 服务器，并可单独配置它们。请注意，如果没有为管理界面属性提供值，则会从 Keycloak HTTP 服务器的默认红帽构建中继承它们。

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

默认情况下，Red Hat build of Keycloak 不使用 XA 数据源。但是，当使用多个数据源时，这被视为不安全。从这个版本开始，如果您在红帽构建的 Keycloak 中添加额外的数据源，则需要使用 XA datasources。如果默认数据源支持 XA，您可以通过设置 --transaction-xa-enabled=true 选项来实现。对于额外的数据源，您需要在 quarkus.properties 文件中使用 quarkus.datasource.<your-datasource-name>.jdbc.transactions=xa 选项。最多一个数据源可以是非 XA。如果没有用于事务存储的持久性存储，不支持恢复。

proxy 选项已从服务器中删除。

红帽构建的 Keycloak Pod 现在具有默认的关联性，以防止将同一 CR 的多个实例部署到同一节点上，并且来自同一 CR 的所有 Pod 都更喜欢在同一区中，以防止扩展缓存集群。

为了遵循最佳实践，引入了 Operator 的默认 CPU 和内存限值/请求。它会影响非 OLM 和 OLM 安装。要覆盖 OLM 安装的默认值，请编辑 operator 订阅中的 resources 部分。https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md#resources

此方法被添加到 org.keycloak.cluster.ClusterProvider 中：

当多个事件发送到同一 taskKey 时，此方法批处理事件仅执行单个网络调用。这是用于减少流量和网络相关资源的优化。

在 Red Hat build of Keycloak 26 中，新方法具有默认的实现，以保持与自定义实现的向后兼容性。默认实现会为每个事件执行单个网络调用，它将在以后的 Keycloak 版本中删除。

RealmProvider Java API 现在包含一个新的方法 Stream<RealmModel> getRealmsStream (String search)，它允许按名称搜索域。虽然从提供程序加载后会过滤流的默认实现，但建议实现它，以便进行更有效的实施。

随着提高组的可伸缩性，现在它们会在删除域时直接从数据库中删除。因此，删除域时不再触发与组相关的事件，如 GroupRemovedEvent。

如果您在域被删除时具有处理任何与组相关的事件的扩展，请确保使用 RealmRemovedEvent 在域及其组被删除时执行任何清理或自定义处理。

GroupProvider 接口也使用新的 preRemove (RealmModel) 方法更新，以强制实现在域被删除时正确处理删除组。

现在，REFRESH_TOKEN 事件中的 userId 始终从用户会话中获取，而不是刷新令牌中的 sub 声明。REFRESH_TOKEN_ERROR 事件中的 userId 现在始终为 null。此更改的原因是，刷新令牌中的 sub 声明的值可能为 null，在使用对主题标识符或其他方法覆盖子声明时，可选 的子 声明甚至与真实用户 ID 的不同。

但是，在 REFRESH_TOKEN_ERROR 事件中缺少 userId 时，现在添加了一个 refresh_token_sub 详情作为向后兼容信息。

Keycloak JS 库不再由红帽构建的 Keycloak 服务器静态提供。这意味着以下 URL 不再可用：

另外，链接到这些 URL 上库的 keycloakJsUrl 属性已从 Admin Console 主题中删除。如果您的自定义主题使用此属性包含库，您应该更新主题以使用不同的方法包含库。

现在，您应该使用软件包管理器（如 NPM ）在项目中包含该库。该程序库在 NPM 注册表上作为 keycloak-js 提供。您可以使用以下命令安装它：

npm install keycloak-js

或者，服务器的分发还包括 keycloak-js-26.0.0.tgz 存档中的库副本。您可以将库从那里复制到您的项目。如果您在没有构建的情况下直接在浏览器中使用库，则需要自己托管该库。软件包管理器仍然是建议将库包含在项目中，因为它将在以后更轻松地更新库。

在以前的版本中，可以在不传递任何配置的情况下构建 Keycloak 实例。然后，根据包含的 keycloak.js 脚本的路径，从 keycloak.json 文件中自动从服务器加载配置。因为库不再从服务器静态提供，所以这个功能已被删除。现在，在构造 Keycloak 实例时需要显式传递配置：

// Before
const keycloak = new Keycloak();

// After
const keycloak = new Keycloak({
    url: "http://keycloak-server",
    realm: "my-realm",
    clientId: "my-app"
});

// Alternatively, you can pass a URL to a `keycloak.json` file.
// Note this is not reccomended as it creates additional network requests, and is prone to change in the future.
const keycloak = new Keycloak('http://keycloak-server/path/to/keycloak.json');

Keycloak JS 现在使用 Web Crypto API 来计算支持 PKCE 所需的 SHA-256 摘要。由于此 API 的异步性质，以下公共方法现在始终返回 Promise ：

确保将代码更新为 等待 这些方法：

// Before
keycloak.login();
const loginUrl = keycloak.createLoginUrl();
const registerUrl = keycloak.createRegisterUrl();

// After
await keycloak.login();
const loginUrl = await keycloak.createLoginUrl();
const registerUrl = await keycloak.createRegisterUrl();

确保将您的代码更新为 等待 这些方法。

当提供的构建时选项在启动时与在最近优化的 Keycloak 构建过程中在服务器镜像中保留的值不同时，红帽构建的 Keycloak 现在将无法启动。在以前的版本中，在这种情况下会显示警告信息。

名为 basic 的新客户端范围被添加为 realm "default" 客户端范围，因此将添加到所有新创建的客户端。客户端范围还在迁移过程中自动添加到所有现有客户端。

此范围包含以下声明的预配置的协议映射器：

这提供了额外的帮助来减少轻量级访问令牌中的声明数量，但也有机会配置始终自动添加的声明。

在具有许多身份提供程序时，作为域和机构可扩展性的改进的一部分，域表示不再包含身份提供程序列表。但是，在导出域时，它们仍然可从 realm 表示中可用。

要获取域中身份提供程序的查询，首选使用 /realms/{realm}/identity-provider/instances 端点。此端点支持过滤器和分页。

在 IDENTITY_PROVIDER 表中添加了新的索引，以改进获取与某个机构关联的 IDP 的查询性能，以及获取可用于登录的 IDP ( 启用，而不是 link_only，没有标记为 hide_on_login)。

如果表目前包含 300,000 个条目，红帽构建的 Keycloak 将在自动模式迁移过程中默认跳过创建索引，而是在迁移过程中记录控制台上的 SQL 语句。在这种情况下，在红帽构建 Keycloak 后，必须在 DB 中手动运行语句。

另外，kc.org 和 hideOnLoginPage 配置属性已迁移到身份提供程序本身，以便在搜索供应商时更有效地查询。因此，API 客户端应使用 getOrganizationId/setOrganizationId 和 isHideOnLogin/setHideOnLogin 方法，并避免使用现已弃用的旧配置属性设置这些属性。

Argon2 现在是红帽在非FIPS 环境中构建 Keycloak 的默认密码哈希算法。

Argon2 是 2015 密码散列竞争者，是 OWASP 的建议哈希算法。

在 Red Hat build of Keycloak 24 中，PBKDF2 的默认哈希迭代从 27.5K 增加到 210K，从而导致生成密码哈希所需的 CPU 时间量增加 10 倍。使用 Argon2，您可以实现更高的安全性，与以前的红帽构建的 Keycloak 版本几乎相同。一个缺点是 Argon2 需要更多内存，这是防止 GPU 攻击的要求。红帽构建的 Keycloak 中 Argon2 的默认值需要每个哈希请求 7MB。

为防止过量内存和 CPU 使用量，Argon2 的并行计算默认限制为 JVM 可用的内核数。为了支持 Argon2 的内存密集型性质，我们已将默认的 GC 从 ParallelGC 更新至 G1GC 以获得更好的堆利用率。

请注意，Argon2 不兼容 FIPS 140-2。因此，如果您在 FIPS 环境中，默认算法仍为 PBKDF2。另请注意，如果您处于非FIPS 环境，并且计划迁移到 FIPS 环境，请考虑将密码策略改为 FIPS 兼容算法，如 outset 中的 pbkdf2-sha512。否则，用户在切换到 FIPS 环境后将无法登录。

如果未设置，则 http-pool-max-threads 将默认为 50 或 4 x （可用处理器）。在以前的版本中，它默认为 200 或 8 x 更大的（可用处理器）。减少大多数使用场景的数量或任务线程会因为活跃线程的上下文切换而降低性能。

当 RESOURCE_SERVER_RESOURCE 和 RESOURCE_SERVER_PERM_TICKET 表具有 100k 条目且用户通过 1k 资源授予了访问权限时，这些查询不佳。这个查询已被简化，并引入了 请求者 和 所有者 列的新索引。

新索引都应用到 RESOURCE_SERVER_PERM_TICKET 表。如果表目前包含 300,000 个条目，红帽构建的 Keycloak 将在自动模式迁移过程中默认跳过创建索引，而是在迁移过程中记录控制台上的 SQL 语句。在这种情况下，在红帽构建 Keycloak 后，必须在 DB 中手动运行语句。

由于从 AccessToken、IDToken 和 JsonWebToken 中删除已弃用的方法后，SingleUseObjectKeyModel 也改变，以保持与过期值相关的方法名称的一致性。

前面的 getExpiration 方法现已弃用，您应该更喜欢使用新的 getExp 方法来避免 2038 后溢出。

如果攻击者并行启动了很多登录尝试，则攻击者可能会对密码进行更多的猜测，而不是暴力保护配置所允许的。这是因为在暴力强制保护器已锁定用户之前进行暴力检查。为防止这种争用，Brute Force Protector 现在会拒绝在同一服务器中进行另一次登录尝试时发生的所有登录尝试。

如果您希望禁用此功能，请使用以下命令：

bin/kc.[sh|bat] start --spi-brute-force-protector-default-brute-force-detector-allow-concurrent-requests=true

由于安全问题，如果传递的 redirect uri 包含 userinfo 部分或其 路径访问 父目录(/../)，则重定向 URI 验证现在会执行精确的字符串匹配（不包括通配符）。

完整通配符 * 仍可用作具有这些特征的 http URI 开发中的有效重定向。在生产环境中，为该类型的任何 URI 配置准确的有效重定向 URI。

请注意，不建议在生产环境中使用通配符有效的重定向 URI，而不是 OAuth 2.0 规格涵盖的。

Marshalling 是将 Java 对象转换为字节的过程，以便在红帽构建的 Keycloak 服务器之间在网络上发送它们。在 Red Hat build of Keycloak 26 中，marshalling 库已从 JBoss Marshalling 改为 Infinispan Protostream。库彼此不兼容，需要一些步骤来确保会话数据不会丢失。

指定 http-relative-path 属性时，用户会自动重定向到托管 Red Hat build of Keycloak 的路径。这意味着，当相对路径设置为 /auth，并且用户访问 localhost:8080/ 时，该页面会被重定向到 localhost:8080/auth。

当指定 http-management-relative-path 或 http-relative-path 属性时，同样的更改适用于管理界面。这个变化提高了用户体验。用户不再需要显式设置 URL 的相对路径。

org.keycloak.common.util.Encode 现在总是使用 UTF-8 charset 进行 URL 编码，而依赖于 file.encoding 系统属性。

在本发行版本中，LDAP 连接池配置只依赖于系统属性。主要的原因是 LDAP 连接池配置是 JVM 级别的配置，而不是特定于单个域或 LDAP 提供程序实例。

与之前的版本相比，任何与 LDAP 连接池相关的域配置都将被忽略。如果您要从将以下设置设置为 LDAP 提供程序的早期版本迁移，请考虑使用系统属性：

如需了解更多详细信息 ，请参阅配置连接池。

在本发行版本中，撤销的访问令牌写入数据库，并在使用嵌入式缓存时默认重启集群时重新载入。

要禁用此行为，请使用 SPI 选项 spi-single-use-object-infinispan-persist-revoked-tokens，如 All provider configuration 所述。

SingleUseObjectProvider 的 SPI 行为已更改，它只用于撤销的令牌，且只能使用 包含 的方法。默认情况下会强制执行此设置，可以使用 SPI 选项 spi-single-use-object-infinispan-persist-revoked-tokens 来禁用。

Red Hat build of Keycloak 26 对推荐的高可用性多站点架构进行了显著改进，最重要的是：

由于上述更改，现有 Red Hat build of Keycloak 部署需要以下更改。

现在，当从应用程序启动所需操作执行重定向时，通过 kc_action 参数返回所需的操作供应商名称。这简化了为客户端执行哪些所需操作的检测。执行的结果可以通过 kc_action_status 参数来决定。

注： 此功能需要对 Keycloak JS 适配器进行更改，因此，如果要使用此功能，建议升级到最新版本的适配器。

红帽 Keycloak 的构建现在根据文件扩展决定密钥存储和信任存储的格式。如果文件扩展是 .p12、.pkcs12 或 .pfx，则格式为 PKCS12。如果文件扩展是 .jks、.keystore 或 .truststore，则格式为 JKS。如果文件扩展是 .pem、.crt 或 .key，则格式为 PEM。

您仍然可以通过明确指定 https-key-store-type 和 https-trust-store-type 来覆盖自动检测。这也适用于管理界面及其 https-management-key-store-type。FIPS 严格模式的限制保持不变。

keycloak 主题 的通用 资源的一些路径已更改，特别是第三方库的资源。确保相应地更新您的自定义主题：

另外，以下资源已从 常见 主题中删除：

如果您之前在主题中使用了任何删除的资源，请确保将它们添加到您自己的主题资源中。

现在，我们的 FIPS 140-2 集成已在 BouncyCastle FIPS 库的版本 2 中经过测试和支持。此版本通过 Java 21 认证。如果使用 FIPS 140-2 集成，建议将 BouncyCastle FIPS 库升级到最新文档中所述的版本。

BouncyCastle FIPS 版本 2 已通过 FIPS 140-3 认证。因此，只要在 FIPS 140-3 兼容系统上使用它，Red Hat build of Keycloak 就可以符合 FIPS 140-3。这可能是基于 RHEL 9 的系统，它本身与 FIPS 140-3 兼容。但请注意，基于 RHEL 8 的系统只通过 FIPS 140-2 认证。

要执行自动迁移，请启动连接到所需数据库的服务器。如果新服务器版本更改了数据库架构，则迁移会自动启动，除非数据库有太多记录。

例如，在包含数百万条记录的表上创建索引可能会非常耗时，并导致重要的服务中断。因此，自动迁移存在 300000 记录的阈值。如果记录数量超过这个阈值，则不会创建索引。相反，您可以使用 SQL 命令在服务器日志中找到可以手动应用的警告信息。

要更改阈值，请为 connections-liquibase 供应商设置 index-creation-threshold 属性：

kc.[sh|bat] start --spi-connections-liquibase-quarkus-index-creation-threshold=300000

要启用数据库模式的手动升级，请将默认的 connection- jpa 提供者的 migration- strategy 属性值设置为 "manual" ：

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

使用此配置启动服务器时，服务器会检查是否需要迁移数据库。所需的更改被写入 bin/keycloak-database-update.sql SQL 文件，您可以检查并手动针对数据库运行。

要更改导出的 SQL 文件的路径和名称，请设置默认 connection- jpa 供应商的 migration- export 属性：

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

有关如何将此文件应用到数据库的详情，请查看您的关系数据库文档。将更改写入到文件后，服务器将退出。

如果您自定义任何模板，请查看新版本以决定更新自定义模板。如果您进行了较小的更改，您可以将更新的模板与自定义模板进行比较。但是，如果您进行了许多更改，请考虑将新模板与自定义模板进行比较。此比较将向您显示您需要进行哪些更改。

您可以使用 diff 工具比较模板。以下屏幕截图比较了 Login 主题和示例自定义主题中的 info.ftl 模板：

此比较显示，第一次更改(Hello world!!)是自定义状态，而第二个更改(如果 pageRedirectUri)是基础主题的更改。通过将第二个更改复制到自定义模板，您已成功更新您的自定义模板。

在替代方法中，以下屏幕截图将旧安装中的 info.ftl 模板与新安装中更新的 info.ftl 模板进行比较：

此比较显示在基本模板中更改的内容。然后您可以手动对修改的模板进行相同的更改。由于这种方法更为复杂，因此只有在第一个方法不可行时才使用此方法。

如果您添加了对其他语言的支持，则需要应用上面列出的所有更改。如果您还没有添加了对其他语言的支持，您可能不需要更改任何内容。只有在您更改了主题中的受影响的消息时才需要进行更改。

您可能需要更新您的自定义样式，以反映对内置主题中样式所做的更改。考虑使用 diff 工具将旧服务器安装与样式表的更改进行比较。

例如：

$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

检查更改并确定它们是否影响您的自定义样式。