升级指南

重大变更被定义为需要现有用户对其配置进行更改。

值得注意的变更是指内部行为的更改，旨在防止常见的错误配置、修复错误或简化 Keycloak 的运行。

值得注意的变更是指内部行为的更改，旨在防止常见的错误配置、修复错误或简化 Keycloak 的运行。

重大变更被定义为需要现有用户对其配置进行更改。

此版本中，公共 API 或已记录的行为没有重大更改。

值得注意的变更是指内部行为的更改，旨在防止常见的错误配置、修复错误或简化 Keycloak 的运行。

此处列出了在本版本中继续像以前一样工作的功能，但在未来的主要版本中将被移除。

使用 REALM_FILESEPARATOR_KEY 密钥解析器时，Keycloak 现在限制对 realm 之外的 FileVault 密钥的访问。在管理控制台中指定表达式占位符时，现在禁止使用可能导致路径遍历的字符。

此外， KEY_ONLY 密钥解析器现在转义 _ 字符，以防止在使用 REALM_UNDERSCORE_KEY 解析器时读取链接到另一个 realm 的密钥。转义只是将 _ 替换为 __ ，因此，例如， ${vault.my_secret} 现在查找名为 my__secret 的文件。我们认识到这是一个重大更改；因此，会记录警告以简化过渡。

编组是将 Java 对象转换为字节的过程，以便在 Keycloak 服务器之间通过网络发送它们。在 Keycloak 26 中，编组库已从 JBoss Marshalling 更改为 Infinispan Protostream。这些库彼此不兼容，并且需要一些步骤来确保会话数据不会丢失。

为了防止丢失用户会话，请先升级到 Keycloak 25，并按照 Keycloak 25 的迁移指南中概述的方式启用持久会话功能。

Operator 将不再默认为 hostname v1 设置 proxy=passthrough。这允许使用 hostname v2 进行固定边缘主机名的部署按预期工作，而无需其他选项。

以下方法已添加到 org.keycloak.cluster.ClusterProvider

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

在 Keycloak 26 中，新方法具有默认实现，以保持与自定义实现的向后兼容性。默认实现为每个事件执行单个网络调用，并且将在 Keycloak 的未来版本中移除。

为了提高组的可伸缩性，现在在移除 realm 时直接从数据库中移除组。因此，在移除 realm 时不再触发组相关事件，如 GroupRemovedEvent 。

如果您有扩展程序在移除 realm 时处理任何组相关事件，请确保改为使用 RealmRemovedEvent ，以便在移除 realm 及其组时执行任何清理或自定义处理。

GroupProvider 接口也已更新，添加了一个新的 preRemove(RealmModel) 方法，以强制实现正确处理在移除 realm 时移除组的情况。

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

当指定 http-management-relative-path 或 http-relative-path 属性时，管理界面也适用相同的情况。

这改善了用户体验，因为用户不再需要显式地将相对路径设置为 URL。

Keycloak Pod 现在将具有默认的亲和性，以防止来自同一 CR 的多个实例部署在同一节点上，并且来自同一 CR 的所有 Pod 将优先位于同一区域中，以防止拉伸缓存集群。

为了遵循最佳实践，引入了 Operator 的默认 CPU 和内存限制/请求。这会影响非 OLM 安装和 OLM 安装。要覆盖 OLM 安装的默认值，请编辑 operator 的 subscription 中的 resources 部分。

以下项目已被弃用，将在即将到来的 Keycloak 版本中移除，且没有替代项

org.keycloak.common.util.Encode 现在始终使用 UTF-8 字符集进行 URL 编码，而不是隐式依赖于 file.encoding 系统属性。

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

与以前的版本相比，任何与 LDAP 连接池相关的 realm 配置都将被忽略。如果您是从以前的版本迁移而来，并且以下任何设置已设置为您的 LDAP 提供程序，请考虑改用系统属性

有关更多详细信息，请参阅 配置连接池。

此版本引入了轻松地为 base/login 和 keycloak.v2/login 主题的登录页面添加自定义页脚的功能。为了使用自定义页脚，请在您的自定义登录主题中创建一个包含所需内容的 footer.ftl 文件。

有关更多详细信息，请参阅 向登录主题添加自定义页脚。

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

要禁用此行为，请使用 SPI 选项 spi-single-use-object-infinispan-persist-revoked-tokens ，如 所有提供程序配置 指南中所述。

SingleUseObjectProvider 的 SPI 行为已更改，对于吊销的令牌，仅必须使用方法 put 和 contains 。默认情况下强制执行此操作，并且可以使用 SPI 选项 spi-single-use-object-infinispan-persist-revoked-tokens 禁用。

Keycloak 26 对推荐的 HA 多站点架构进行了重大改进，最值得注意的是

由于上述更改，您的现有 Keycloak 部署需要进行以下更改。

如果您在单站点设置中使用外部 Infinispan，则 Keycloak 的早期版本不支持此功能，Keycloak 26 也不支持此功能。为了防止用户通过 Keycloak 缓存 XML 中的手动配置或通过 CLI 选项意外使用它，现在使用功能标志 cache-embedded-remote-store 对其进行保护。它被标记为实验性功能，因此不受支持。除非启用此实验性功能，否则 Keycloak 26 将不会使用此类配置启动并显示错误。

如果您一直在使用外部 Infinispan 来在重启和升级之间保持用户登录状态，请改用默认启用的 persistent-user-sessions 功能。然后不再需要外部 Infinispan。

实验性功能 cache-embedded-remote-store 将在未来的次要版本中移除 。

当所有管理员用户都被锁定后，重新获得对 Keycloak 实例的访问权限曾经很困难。该过程需要多个高级步骤，包括直接数据库访问和手动更改。为了改善用户体验，Keycloak 现在提供了多种引导新管理员帐户的方法，可用于从此类情况中恢复。

因此，环境变量 KEYCLOAK_ADMIN 和 KEYCLOAK_ADMIN_PASSWORD 已弃用。您应该改用 KC_BOOTSTRAP_ADMIN_USERNAME 和 KC_BOOTSTRAP_ADMIN_PASSWORD 。这些也是通用选项，因此可以通过 cli 或其他配置源指定，例如 --bootstrap-admin-username=admin 。有关更多信息，请参阅新的 引导管理员和恢复 指南。

当从应用程序发起的必需操作执行重定向返回时，必需操作提供程序名称现在通过 kc_action 参数返回。这简化了检测为客户端执行了哪个必需操作。执行结果可以通过 kc_action_status 参数确定。

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

类 UserSessionCrossDCManager 已弃用，并计划在 Keycloak 的未来版本中移除。请阅读 UserSessionCrossDCManager Javadoc 以获取要使用的替代方法。

作为改进 realm 和组织在拥有许多身份提供程序时的可伸缩性的一部分，realm 表示不再保存身份提供程序的列表。但是，当导出 realm 时，它们仍然可以从 realm 表示中获得。

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

CLI 命令 kc.[sh|bat] import 现在已启用占位符替换。以前，占位符替换仅在启动时为 realm 导入启用。

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

RealmProvider Java API 现在包含一个新方法 Stream<RealmModel> getRealmsStream(String search) ，该方法允许按名称搜索 realm。虽然有一个默认实现，在从提供程序加载流后对其进行过滤，但鼓励实现提供更有效的实现。

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 严格模式的限制保持不变。

在 IDENTITY_PROVIDER 表中添加了新索引，以提高查询性能，这些查询用于获取与组织关联的 IDP，以及获取可用于登录的 IDP（已 enabled 、非 link_only 、未标记为 hide_on_login 的 IDP）。

如果该表当前包含超过 300,000 个条目，则默认情况下，Keycloak 将在自动模式迁移期间跳过索引的创建，而是在迁移期间在控制台上记录 SQL 语句。在这种情况下，必须在 Keycloak 启动后在数据库中手动运行这些语句。

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

GELF 支持已弃用一段时间，并且在此版本中，它已最终从 Keycloak 中移除。其他日志处理程序可用且完全受支持，可以替代 GELF 使用，例如 Syslog。有关详细信息，请参阅日志记录指南。

keycloak 主题的 common 资源的一些路径已更改，特别是第三方库的资源。请务必相应地更新您的自定义主题

此外，以下资源已从 common 主题中移除

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

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

已弃用的主机名 v1 功能已移除。此功能在 Keycloak 25 中已弃用，并由主机名 v2 替代。如果您仍在使用此功能，则必须迁移到主机名 v2。有关更多详细信息，请参阅配置主机名 (v2) 和初始迁移指南。

已弃用的 proxy 选项已移除。此选项在 Keycloak 24 中已弃用，并由 proxy-headers 选项与所需的主机名选项结合使用替代。有关更多详细信息，请参阅使用反向代理和初始升级指南。

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

使用类似于下面所示的配置更新您的自定义嵌入式 Infinispan 缓存配置文件，用于缓存 sessions、clientSessions、offlineSessions 和 offlineClientSessions

有关更多详细信息，请访问配置分布式缓存指南。

以前版本的 Keycloak 为用户和客户端会话的空闲时间添加了两分钟的宽限期。这是由于以前的架构中会话刷新时间在集群中异步复制而添加的。使用持久用户会话后，这不再是必需的，因此现在移除了宽限期。

要保留旧的行为，请更新您的 realm 配置，并将会话和客户端空闲时间延长两分钟。

以前版本的 Keycloak 支持通过打开注销端点 URL（例如 http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri）自动注销用户并重定向到应用程序。此功能在 Keycloak 18 中已弃用，并已在本版本中移除，以支持遵循 OpenID Connect 规范。

作为此更改的一部分，以下相关的 SPI 配置选项已被移除

如果您仍在使用这些选项或用于注销的 redirect_uri 参数，则应改为实施 OpenID Connect RP-Initiated Logout 规范。

--optimized 启动选项现在要求首先构建优化的服务器镜像。这可以通过首先运行 kc.sh|bat build 或通过任何其他不带 --optimized 标志的服务器命令（如 start、export、import）来实现。

org.keycloak.bom:keycloak-adapter-bom 和 org.keycloak.bom:keycloak-misc-bom BOM 文件已移除。适配器 BOM 不再有用，因为大多数 Java 适配器已被移除。misc BOM 仅包含一个构件，keycloak-test-helper，并且该构件也已在此版本中移除。

maven 构件 org.keycloak:keycloak-test-helper 已在此版本中移除。该构件为处理 Java 管理客户端提供了一些辅助方法。如果您使用这些辅助方法，则可以在需要时将它们 fork 到您的应用程序中。

JEE admin-client 已在此版本中移除。我们仍然保持对 Jakarta admin-client 的支持。

现在有用于更新 (UPDATE_CREDENTIAL) 和移除 (REMOVE_CREDENTIAL) 凭据的通用事件。凭据类型在事件的 credential_type 属性中描述。电子邮件事件侦听器支持新的事件类型。

以下事件类型现在已弃用，将在未来版本中移除：UPDATE_PASSWORD、UPDATE_PASSWORD_ERROR、UPDATE_TOTP、UPDATE_TOTP_ERROR、REMOVE_TOTP、REMOVE_TOTP_ERROR

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

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

BouncyCastle FIPS 版本 2 已通过 FIPS 140-3 认证。因此，只要在符合 FIPS 140-3 的系统上使用 Keycloak，Keycloak 就可以符合 FIPS 140-3 标准。这可能是基于 RHEL 9 的系统，该系统本身符合 FIPS 140-3 标准。但请注意，基于 RHEL 8 的系统仅通过 FIPS 140-2 认证。

groups.setOrCreateChild() 方法已从基于 JavaScript 的 Admin Client 中移除。如果您仍在使用此方法，请改用 createChildGroup() 或 updateChildGroup() 方法。

此版本包括对 Keycloak JS 库的几项更改，应予以考虑。这些更改的主要动机是将库与 Keycloak 服务器解耦，以便可以独立重构库，从而简化代码并在未来更易于维护。更改如下

当提供的构建时选项在启动时与上次优化的 Keycloak 构建期间服务器镜像中持久化的值不同时，Keycloak 现在将启动失败。以前，在这种情况下会显示警告消息。

使用功能版本，功能 account3、admin2 和 login2 已重命名。禁用功能时，无需使用版本，例如，现在使用 --features-disabled=admin 禁用管理控制台。

要使用 login 的特定版本，请使用 --features=login:v1。

如果攻击者并行发起大量登录尝试，则攻击者可能比暴力破解保护配置允许的密码猜测次数更多。这是由于暴力破解检查发生在暴力破解保护器锁定用户之前。为了防止这种竞争情况，暴力破解保护器现在拒绝所有在同一服务器中另一个登录正在进行时发生的登录尝试。

如果出于任何原因要禁用新功能，则有一个启动工厂选项

当客户端 scope 或完整的 realm 被删除时，关联的用户授权也应被移除。已在表 USER_CONSENT_CLIENT_SCOPE 上添加了一个新索引以提高性能。

请注意，如果表包含超过 300,000 个条目，则默认情况下，Keycloak 会在自动模式迁移期间跳过索引的创建，而是将 SQL 语句记录到控制台。这些语句必须在 Keycloak 启动后在数据库中手动运行。有关如何配置不同限制的详细信息，请查看升级指南。

默认情况下支持主机名 v2 选项，因为旧的主机名选项已弃用，并将在后续版本中移除。默认情况下会激活新选项，因此 Keycloak 将无法识别旧选项。

必要的迁移列表

如您所见，hostname 和 hostname-admin 选项的 *-url 后缀已移除。选项 hostname 接受主机名和 URL，但 hostname-admin 现在仅接受完整 URL。

此外，无法单独设置 path 或 port。您可以通过为 hostname 和 hostname-admin 选项提供完整 URL 来实现此目的。

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

除非 HTTPS 是 hostname 和 hostname-admin URL 的一部分，否则不再强制使用 HTTPS。如果未指定，则使用的协议 (http/https) 会从传入的请求动态解析。hostname-strict-https 选项已移除。

以前版本的 Keycloak 仅在数据库中存储离线用户会话和离线客户端会话。新功能 persistent-user-sessions 不仅在内存中，而且还在数据库中存储在线用户会话和在线客户端会话。这将允许用户即使在所有 Keycloak 实例重启或升级后仍保持登录状态。

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

Keycloak 提供的指标现在包括以 http_server 开头的 HTTP 服务器指标。请参见下面的示例。

使用新选项 http-metrics-histograms-enabled 和 http-metrics-slos 来启用默认直方图 bucket 或服务级别目标 (SLO) 的特定 bucket。有关直方图的更多信息，请阅读 Prometheus 文档中关于直方图 的内容，了解如何使用 http_server_requests_seconds_bucket 中提供的附加指标系列。

在 Keycloak 24 版本中，我们的密码哈希算法发生了一项更改，导致 CPU 使用率增加。为了解决这个问题，我们为非 FIPS 环境选择了不同的默认哈希算法 Argon2，这使 CPU 使用率恢复到 Keycloak 24 版本之前的水平。

在某些场景下，例如 brokering，Keycloak 使用 HTTP 与外部服务器通信。为了避免在这些提供程序发送过多数据时发生拒绝服务，Keycloak 现在默认将响应限制为 10 MB。

用户可以通过设置提供程序配置选项 spi-connections-http-client-default-max-consumed-response-size 来配置此限制

spi-truststore-file-hostname-verification-policy 和新的 tls-hostname-verifier 选项的默认值现在是 DEFAULT，而不是 WILDCARD。WILDCARD 和 STRICT 选项值已弃用 - 您应该只依赖 DEFAULT。

WILDCARD 支持的行为，DEFAULT 不支持的行为：* 允许子域名名称中的通配符（例如 *.foo.com）匹配任何内容，包括多个级别（例如 a.b.foo.com）。* 允许针对众所周知的公共后缀进行匹配 - 例如 foo.co.gl 可能匹配 *.co.gl

STRICT 支持的行为，DEFAULT 不支持的行为：* STRICT 使用一个小型的排除列表，用于以 2 个字母顶级域名结尾的 2 个或 3 个字母域名 (*.XXX.YY)，以确定通配符是否匹配。相反，DEFAULT 使用来自 https://publicsuffix.org/list/ 的更完整的公共后缀规则和排除列表

不希望您依赖 WILDCARD 或 STRICT 选项的这些行为。

当身份验证会话过期且用户已登录时，Keycloak 现在不会向最终用户显示消息您已登录。而是将有关过期身份验证会话的错误重定向到客户端应用程序，以便客户端可以对其进行操作并按照服务器管理指南身份验证会话章节中的描述重新启动身份验证。您可以考虑更新您的应用程序以使其能够处理此错误。

模块 org.keycloak:keycloak-model-legacy 模块在以前的版本中已弃用，并在此版本中移除。请改用 org.keycloak:keycloak-model-storage 模块。

在以前的版本中已弃用后，现在移除了启动时预加载离线会话的旧行为。

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

kcadm 和 kcreg 解析和处理选项和参数的方式已更改。来自用法错误、错误选项或参数的错误消息可能与以前的版本略有不同。此外，用法错误将具有退出代码 2 而不是 1。

当按用户属性搜索用户时，Keycloak 不再搜索用户属性名称强制小写比较。这意味着在搜索时，将使用 Keycloak 用户属性表上的本机索引。如果您已创建自己的基于 `lower(name)` 的索引来加速搜索，则现在可以将其移除。

名为 basic 的新客户端 scope 已添加为 realm “default” 客户端 scope，因此将添加到所有新创建的 OIDC 客户端。客户端 scope 也会在迁移期间自动添加到所有现有的 OIDC 客户端。

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

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

session_state 声明包含与 sid 声明相同的值，现在已从所有令牌中移除，因为它不是 OpenID Connect 前端通道注销和 OpenID Connect 后端通道注销规范所要求的。session_state 声明仍然按照 OpenID Connect 会话管理规范存在于访问令牌响应中。

请注意，setSessionState() 方法也已从 IDToken 类中移除，取而代之的是 setSessionId() 方法，而 getSessionState() 方法现在已被弃用。

新的 Session State (session_state) 映射器也已包含在内，可以分配给客户端 scope（例如 basic 客户端 scope）以恢复到旧的行为。

如果使用旧版本的 JS 适配器，则也应通过使用如上所述的客户端 scope 来使用 Session State (session_state) 映射器。

sub 声明以前总是添加到访问令牌中，现在默认添加，但使用新的 Subject (sub) 协议映射器。

Subject (sub) 映射器默认在 basic 客户端 scope 中配置。因此，升级到此版本后无需额外配置。

如果您正在使用 Pairwise subject identifier 映射器来映射访问令牌的 sub 声明，您可以考虑禁用或移除 Subject (sub) 映射器，但这并非严格必要，因为 Subject (sub) 协议映射器在 Pairwise subject identifier 映射器之前执行，因此 pairwise 值将覆盖 Subject (sub) 映射器添加的值。这也可能适用于其他自定义协议映射器实现，它们会覆盖 sub 声明，因为 Subject (sub) 映射器目前作为第一个协议映射器执行。

您可以仅对访问令牌、轻量级访问令牌和内省响应使用 Subject (sub) 映射器来配置 sub 声明。IDToken 和 Userinfo 始终包含 sub 声明。

该映射器对服务帐户无效，因为不存在用户会话，并且 sub 声明始终添加到访问令牌中。

nonce 声明现在仅添加到 ID 令牌，严格遵循 OpenID Connect Core 1.0 规范。正如规范中指出的，当在授权请求中发送相同的参数时，该声明在 ID 令牌中是强制性的。规范还建议在 刷新请求后不要添加 nonce。以前，该声明在所有响应（包括刷新）中都设置为所有令牌（访问令牌、刷新令牌和 ID 令牌）。

软件中还包含一个新的 Nonce backwards compatible 映射器，可以分配给客户端 scope 以恢复到旧的行为。例如，JS 适配器在版本 24.0.0 中修复问题 #26651 之前，检查了所有令牌中返回的 nonce 声明。因此，如果使用旧版本的 JS 适配器，则应通过使用客户端 scope 将映射器添加到所需的客户端。

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

但是，现在添加了 refresh_token_sub 详细信息作为向后兼容性，以便在 REFRESH_TOKEN_ERROR 事件中缺少 userId 的情况下提供有关用户的信息。

如果您在应用程序中使用最新的 Keycloak 服务器和旧版本的 javascript 适配器，您可能会受到上述令牌更改的影响，因为以前版本的 javascript 适配器依赖于 Keycloak 添加的声明，但这些声明不受 OIDC 规范的支持。这包括

您可以将协议映射器直接添加到相应的客户端，或者添加到某些客户端 scope，您的客户端应用程序可以使用这些客户端 scope 来依赖旧版本的 Keycloak Javascript 适配器。有关更多详细信息，请参阅前面专门介绍 session_state 和 nonce 声明的部分。

如果未设置 http-pool-max-threads，则默认值将为 50 或 4 x（可用处理器）中的较大值。以前，默认值为 200 或 8 x（可用处理器）中的较大值。由于减少了活动线程之间的上下文切换，因此对于大多数使用场景，减少任务线程数将导致略高的性能。

/health 和 /metrics 端点可通过管理端口 9000 访问，默认情况下该端口已开启。这意味着这些端点不再暴露于标准的 Keycloak 端口 8080 和 8443。

为了反映旧的行为，请使用属性 --legacy-observability-interface=true，这将不会在管理端口上暴露这些端点。但是，此属性已弃用，将在未来版本中移除，因此建议不要使用它。

管理接口使用与默认 Keycloak HTTP 服务器不同的 HTTP 服务器，并且可以单独配置它们。请注意，如果未为管理接口属性提供任何值，则它们将从默认 Keycloak HTTP 服务器继承。

有关更多详细信息，请参阅 配置管理接口。

Keycloak 从未转义组路径中的斜杠。因此，名为 group/slash 的组是 top 的子组，使用完整路径 /top/group/slash，这显然具有误导性。从该版本开始，可以启动服务器以对名称中的这些斜杠执行转义。

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

转义目前默认禁用，因为它代表行为上的更改。然而，建议启用转义，并且它可能成为未来版本中的默认设置。

方法 EnvironmentDependentProviderFactory.isSupported() 在多个版本中已被弃用，现在已被移除。

请改为实现 isSupported(Config.Scope config)。

在 22.0.2 版本中，LinkedIn 的 OAuh 2.0 社交提供程序已被新的 OpenId Connect 实现取代。旧的提供程序已被弃用但未移除，以防它在某些现有 realm 中仍然可用。Keycloak 25.0.0 肯定会移除旧的提供程序及其关联的 linkedin-oauth 功能。从现在开始，默认的 LinkedIn 社交提供程序是唯一可用的选项。

当 RESOURCE_SERVER_RESOURCE 和 RESOURCE_SERVER_PERM_TICKET 表格包含超过 10 万条条目，并且用户被授予访问超过 1 千个资源的权限时，这些查询的性能很差。查询已得到简化，并为 requester 和 owner 列引入了新的索引。

新的索引都应用于 RESOURCE_SERVER_PERM_TICKET 表格。如果表格当前包含超过 30 万条条目，Keycloak 将默认在自动架构迁移期间跳过索引的创建，而是在迁移期间在控制台上记录 SQL 语句。在这种情况下，必须在 Keycloak 启动后在数据库中手动运行这些语句。

有关如何配置不同限制的详细信息，请参阅 升级指南。

以下方法已从 AccessToken 类中移除

以下方法已从 IDToken 类中移除

以下方法已从 JsonWebToken 类中移除

您还应该预期令牌中未设置 exp 和 nbf 声明，因为它们是可选的。以前，这些声明被设置为值 0，这没有多大意义，因为它们的值应该是有效的 NumericDate。

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

之前的 getExpiration 方法现在已被弃用，您应该首选使用新引入的 getExp 方法，以避免 2038 年后的溢出。

接口 org.keycloak.credential.hash.PasswordHashProvider 上的方法 String encode(String rawPassword, int iterations) 已弃用。该方法将在未来的 Keycloak 版本之一中移除。可能是 Keycloak 27 版本。

方法 org.keycloak.common.util.CollectionUtil.intersection 已被移除。您应该在现有集合上使用 'java.util.Collection.retainAll' 代替。

org.keycloak.common.util.Resteasy 已被弃用。您应该使用 org.keycloak.util.KeycloakSessionUtil 来获取 KeycloakSession 代替。

强烈建议避免使用创建自定义提供程序以外的其他方式获取 KeycloakSession。

在以前的版本中，当验证会话是否仍然有效时，会话最大生存期和空闲超时计算略有不同。现在，该验证使用与项目其余部分相同的代码。

如果会话正在使用记住我功能，则空闲超时和最大生存期是通用 SSO 和记住我配置值之间的最大值。

Keycloak 现在要求外部 Infinispan 部署的 Infinispan 服务器版本至少为 15.0.0。HA 指南中概述的多站点设置支持外部 Infinispan 部署。

Oracle 数据库 JDBC 驱动程序不再是 Keycloak 发行版的一部分。如果您希望使用 Oracle DB，您必须手动安装与您的特定环境兼容的 Oracle 驱动程序版本。有关此过程的说明，请参阅 配置数据库 指南。

以下变量在管理主题中已弃用，将在未来版本中移除

以下变量在帐户主题中已弃用，将在未来版本中移除

接口 org.keycloak.models.AuthenticatedClientSessionModel 中的方法 String getCurrentRefreshToken()、void setCurrentRefreshToken(String currentRefreshToken)、int getCurrentRefreshTokenUseCount() 和 void setCurrentRefreshTokenUseCount(int currentRefreshTokenUseCount) 已弃用。它们已被需要标识符作为参数的类似方法替换，例如 getRefreshToken(String reuseId)，以便管理客户端会话中的多个刷新令牌。这些方法将在未来的 Keycloak 版本之一中移除。可能是 Keycloak 27 版本。

通过 Admin User API 更新用户属性时，更新用户属性（包括根属性，如 username、email、firstName 和 lastName）时，您无法执行部分更新。

如果您通过 Admin User API 更新用户属性，但未传递管理员具有写入权限的所有属性，则缺少的属性将被移除。另一方面，如果某个属性被标记为管理员只读，则不发送该属性不会将其移除。

有关用户配置文件设置的详细信息，请参阅 用户配置文件文档。

为了正确支持 realm 中的多个用户存储提供程序，org.keycloak.userprofile.UserProfileDecorator 接口已更改。

decorateUserProfile 方法不再在首次解析用户配置文件配置（并缓存它）时调用，而是在每次通过用户配置文件提供程序管理用户时调用。因此，该方法更改了其约定为

与之前的约定和行为不同，此方法仅为从中加载用户的用户存储提供程序调用。

出于安全考虑，如果传递的重定向 URI 包含 userinfo 部分或其 path 访问父目录 (/../)，则重定向 URI 验证现在执行精确字符串匹配（不涉及通配符）。

完整的通配符 * 仍然可以在开发中用作具有这些特征的 http(s) URI 的有效重定向。在生产环境中，对于任何此类 URI，都需要配置没有通配符的精确有效重定向 URI。

请注意，不建议在生产中使用通配符有效重定向 URI，并且 OAuth 2.0 规范未涵盖它们。

用于移除用户凭据的 Account REST 端点已弃用。从该版本开始，Account Console 不再使用此端点。它已被 Delete Credential 应用程序发起的动作取代，当用户想要移除用户凭据时，Account Console 会触发该动作。

Keycloak 24.0.0 的发行说明已更新，其中包含对预期性能影响的更正描述，以及大小调整指南。

“welcome”主题已更新为使用新的布局，现在使用 PatternFly 5 而不是 PatternFly 3。如果您正在扩展主题或提供自己的主题，则可能需要按如下方式更新它

如果您之前扩展了现已弃用的版本 2 的帐户控制台主题，您将需要更新您的主题以使用新版本 3 的帐户控制台主题。新版本的帐户控制台主题在如何自定义方面进行了一些更改。要从一个干净的状态开始，您可以按照新的 自定义快速入门 进行操作。

要移动您的自定义主题，请首先将 parent 更改为新主题

如果您有任何自定义 React 组件，您将直接导入 React，而不是使用相对路径

如果您使用 content.json 自定义主题，则文件结构有一些更改，具体来说

如果您直接从 Keycloak 服务器加载 Keycloak JS，则可以安全地忽略此部分。如果您从 NPM 包加载 Keycloak JS 并使用 Webpack、Vite 等捆绑器，则可能需要对您的代码进行一些更改。Keycloak JS 包现在在 package.json 文件中使用 exports 字段。这意味着您可能必须更改您的导入

不再允许在 --features 和 --features-disabled 列表中具有相同的功能。该功能应仅出现在一个列表中。

在 --features 列表中使用未版本化的功能名称（例如 docker）将允许为您启用最受支持/最新的功能版本。如果您需要在各个版本之间获得更可预测的行为，请引用您想要的特定版本，例如 docker:v1。

spi-truststore-file-* 选项和信任库相关选项 https-trust-store-* 已被弃用。 因此，请使用信任库材料的新默认位置 conf/truststores，或使用 truststore-paths 选项指定您所需的路径。 有关详细信息，请参阅相关的指南。

tls-hostname-verifier 属性应代替 spi-truststore-file-hostname-verification-policy 属性使用。

更改的附带影响是，现在信任库提供程序始终配置了一些证书（至少存在默认的 Java 受信任证书）。 此新行为可能会影响 Keycloak 的其他部分。

例如，如果 attestation conveyance 配置为 Direct 验证，则 webauthn 注册可能会失败。 以前，如果未配置信任库提供程序，则不会验证传入的证书。 但现在始终执行此验证。 注册失败，并显示 invalid cert path 错误，因为 dongle 发送的证书链不受 Keycloak 的信任。 身份验证器的证书颁发机构需要存在于信任库提供程序中，才能正确执行 attestation。

--proxy 选项已被弃用，并将在未来的版本中删除。 下表解释了已弃用的选项如何映射到受支持的选项。

当使用 Operator 时，您也可以设置 proxy headers

org.keycloak.representations.idm.UserRepresentation 和 org.keycloak.representations.account.UserRepresentation 表示类都已更改，以便在分别向 Admin 和 Account API 获取或发送表示形式有效负载时，根用户属性（例如 username、email、firstName、lastName 和 locale）具有一致的表示形式。

username、email、firstName、lastName 和 locale 属性已移动到新的 org.keycloak.representations.idm.AbstractUserRepresentation 基类。

此外，getAttributes 方法的目标是仅表示自定义属性，因此您不应期望在此方法返回的 map 中找到任何根属性。 此方法主要针对客户端在更新或获取给定用户的任何自定义属性时使用。

为了解析包括根属性在内的所有属性，添加了一个新的 getRawAttributes 方法，以便生成的 map 也包括根属性。 但是，此方法不能从表示形式有效负载中使用，其目标是在服务器管理用户配置文件时使用。

选项 https-client-auth 之前被视为运行时选项，但是 Quarkus 不支持这一点。 该选项需要在构建时而不是运行时处理。

从该版本开始，Keycloak 集群的第一个成员将顺序加载远程会话，而不是并行加载。 如果启用了离线会话预加载，这些会话也将顺序加载。

以前的代码导致集群在启动时资源消耗过高，并且在生产环境中难以分析，并且如果节点在加载期间重新启动，则可能导致复杂的故障情况。 因此，已更改为顺序会话加载。

对于离线会话，Keycloak 在此版本和以前版本中的默认设置是按需加载这些会话，与尝试并行预加载相比，这可以更好地扩展大量离线会话。 使用此默认设置的安装不受离线会话加载策略更改的影响。 启用了离线会话预加载的安装应迁移到禁用离线会话预加载的设置。

Keycloak 的默认行为是按需加载离线会话。 以前在启动时预加载它们的旧行为现在已被弃用，因为在启动时预加载它们无法随着会话数量的增长而很好地扩展，并且会增加 Keycloak 的内存使用量。 旧行为将在未来的版本中删除。

要在弃用但尚未删除的情况下重新启用旧行为，请使用功能标志和 SPI 选项，如下所示

UserSessionProvider 的 API 弃用了方法 getOfflineUserSessionByBrokerSessionId(RealmModel realm, String brokerSessionId)。 请改用方法 getOfflineUserSessionByBrokerUserIdStream(RealmModel, String brokerUserId) 先获取用户的会话，然后根据需要按代理会话 ID 进行过滤。

当为 Keycloak 的嵌入式缓存启用指标时，指标现在对缓存管理器和缓存名称使用标签。

要还原安装的更改，请使用自定义 Infinispan XML 配置并按如下方式更改配置

从该版本开始，Keycloak 支持存储和搜索长度超过 255 个字符的用户属性值，这在以前是一个限制。

在允许用户更新属性的设置中，例如通过帐户控制台，请通过添加验证来防止拒绝服务攻击。 确保不允许使用非托管属性，并且所有可编辑属性都具有限制输入长度的验证。

对于非托管属性，最大长度为 2048 个字符。 对于托管属性，默认最大长度为 2048 个字符。 管理员可以通过添加类型为 length 的验证器来更改此设置。

此更改在表 USER_ATTRIBUTE 和 FED_USER_ATTRIBUTE 上添加了新索引。 如果这些表包含超过 300000 个条目，则默认情况下 Keycloak 将在自动模式迁移期间跳过索引创建，而是在迁移期间将 SQL 语句记录到控制台上，以便在 Keycloak 启动后手动应用。 有关如何配置不同限制的详细信息，请参阅升级指南。

在此版本中，API 将使用 email-verification.ftl 模板，而不是 executeActions.ftl。

如果您已自定义 executeActions.ftl 模板以修改用户如何使用此 API 验证其电子邮件，请确保将您的修改转移到新模板。

将引入一个名为 lifespan 的新参数，以允许覆盖默认的生存期值（12 小时）。

如果您喜欢以前的行为，请按如下方式使用 execute-actions-email API。

版本 21 中引入的 SAML 加密兼容模式现已删除。 系统属性 keycloak.saml.deprecated.encryption 不再由服务器管理。 仍使用旧签名密钥进行加密的客户端应从新的 IDP 配置元数据中更新它。

在此版本中，我们调整了密码哈希默认值，以匹配 OWASP 密码存储建议。

作为此更改的一部分，默认密码哈希提供程序已从 pbkdf2-sha256 更改为 pbkdf2-sha512。 此外，基于 pbkdf2 的密码哈希算法的默认哈希迭代次数也发生了如下更改

如果 realm 没有使用 hashAlgorithm 和 hashIterations 显式配置密码策略，则新配置将在下一次基于密码的登录时生效，或者在创建或更新用户密码时生效。

通过 Keycloak CR 引用的 Secret 和 ConfigMap 现在将轮询更改，而不是通过 api 服务器监视。 检测到更改可能需要大约 1 分钟。

这样做是为了不需要对这些资源进行标签操作。 升级后，如果任何 Secret 仍然具有 operator.keycloak.org/component 标签，则可以删除或忽略它。

删除 Map Store 后，以下配置选项已重命名

删除 Map Store 后，以下模块已重命名

并且 org.keycloak:keycloak-model-legacy 模块已被弃用，并将在下一个版本中删除，以支持 org.keycloak:keycloak-model-storage 模块。

现在，当用户被暴力破解保护器临时锁定时，会有一个新的事件 USER_DISABLED_BY_TEMPORARY_LOCKOUT。 ID 为 KC-SERVICES0053 的日志已被删除，因为新事件以结构化形式提供了信息。

由于这是一个成功事件，因此默认情况下，新事件记录在 DEBUG 级别。 使用 服务器管理指南中的事件侦听器章节 中描述的设置 spi-events-listener-jboss-logging-success-level 来更改所有成功事件的日志级别。

要触发自定义操作或自定义日志条目，请按照 服务器开发人员指南 中的事件侦听器 SPI 中的描述编写自定义事件侦听器。

Operator 用于高级配置的属性键已从 operator.keycloak 更改为 kc.operator.keycloak。

当在 Keycloak CR 和 KeycloakRealmImport CR 中未指定 resources 选项时，将使用默认值。 Keycloak 部署和 realm 导入 Job 的默认 requests 内存设置为 1700MiB，limits 内存设置为 2GiB。

作为重构 Keycloak 中 cookie 处理的一部分，cookie 的设置方式有一些更改

对于自定义扩展，可能需要进行一些更改

Keycloak 用于签名内部令牌（Keycloak 本身使用的 JWT，例如刷新令牌或操作令牌）的算法正在从 HS256 更改为更安全的 HS512。 现在为 realm 添加了一个名为 hmac-generated-hs512 的新密钥提供程序。 请注意，在迁移的 realm 中，旧的 hmac-generated 提供程序和旧的 HS256 密钥仍然保留，并且仍然验证升级之前颁发的令牌。 按照轮换密钥指南，当不再存在旧令牌时，可以手动删除 HS256 提供程序。

当在容器中运行时，JVM 选项 -Xms 和 -Xmx 已被 -XX:InitialRAMPercentage 和 -XX:MaxRAMPercentage 取代。 Keycloak 没有指定静态最大堆大小设置，而是将最大值指定为容器总内存的 70%。

由于堆大小是根据容器总内存动态计算的，因此您应始终为容器设置内存限制。

有关更多详细信息，请参阅在容器中运行 Keycloak 指南。

随着提供与 GELF 集成的底层库的淘汰，Keycloak 将不再开箱即用地支持 GELF 日志处理程序。 此功能将在未来的版本中删除。 如果您需要外部日志管理，请考虑使用文件日志解析。

由于问题 #25078，jboss-logging 消息值现在被引用（默认情况下为字符 "）并经过清理以防止任何换行符。 提供程序中有两个新选项（spi-events-listener-jboss-logging-sanitize 和 spi-events-listener-jboss-logging-quotes）允许您自定义新行为。 例如，要避免清理和引用，服务器可以按以下方式启动

有关选项的更多信息，请参阅所有提供程序配置指南。

版本 23.0.0 在 Groups 资源上引入了一个新的端点 getSubGroups（“children”），其中参数 briefRepresentation 的含义是指检索子组的完整表示形式。 现在含义已更改为返回简要表示形式。

版本 1.8.0 在将重定向 URI 与客户端指定的有效重定向进行比较时，引入了主机名和 scheme 的小写。 不幸的是，它并非在所有协议中都完全有效，例如，主机对于 http 是小写的，但对于 https 不是。 由于 OAuth 2.0 安全最佳实践 建议使用精确字符串匹配来比较 URI，因此 Keycloak 将遵循该建议，并且从现在开始，即使对于主机名和 scheme，有效重定向也使用精确大小写进行比较。

对于依赖旧行为的 realm，其客户端的有效重定向 URI 现在应为每个应由服务器识别的 URI 保留单独的条目。

尽管在配置客户端时引入了更多步骤和冗长性，但新行为实现了更安全的部署，因为基于模式的检查通常是安全问题的原因。 这些问题是由于它们的实现方式以及它们的配置方式造成的。

旧版本的 Operator 创建了一个 Secret 来跟踪监视的 Secret。 新版本的 Operator 不再使用 -secrets-store Secret，因此可以删除它。

如果您使用的是 23.0.0 或 23.0.1 版本，并在 operator 日志中看到 “org.keycloak.operator.controllers.KeycloakAdminSecretDependentResource → java.lang.IllegalStateException: More than 1 secondary resource related to primary” 错误，则删除 -secrets-store Secret，或者升级到 23.0.2 版本，此问题已在 23.0.2 版本中解决。

RFC 9207 OAuth 2.0 授权服务器发行者识别规范在 OAuth 2.0/OpenID Connect 身份验证响应中添加了参数 iss，以实现安全的授权响应。

在之前的版本中，我们没有这个参数，但现在 Keycloak 默认添加了这个参数，这是规范要求的。

然而，一些 OpenID Connect / OAuth2 适配器，特别是较旧的 Keycloak 适配器，可能无法处理这个新参数。

例如，在客户端应用程序成功身份验证后，该参数将始终存在于浏览器 URL 中。在这些情况下，禁用向身份验证响应添加 iss 参数可能很有用。这可以在 Keycloak 管理控制台中为特定客户端完成，在客户端详细信息中的 OpenID Connect 兼容模式部分中进行配置，详情请参见与旧适配器的兼容性。存在专用的 从身份验证响应中排除发行者 开关，可以将其打开以阻止向身份验证响应添加 iss 参数。

JPA 允许在搜索时使用通配符 % 和 _，而其他提供程序（如 LDAP）仅允许使用 *。由于 * 是 LDAP 中自然的通配符，因此它在所有位置都有效，而在 JPA 中，它仅在搜索字符串的开头和结尾有效。从本版本开始，唯一的通配符是 *，它在所有提供程序的所有搜索字符串位置中都保持一致。特定提供程序中的所有特殊字符（如 JPA 的 % 和 _）都将被转义。对于精确搜索，使用添加引号（如 "w*ord"），其行为与之前的版本保持一致。

此版本现在遵循 Java 及更高版本的标准机制，该机制假定资源包文件以 UTF-8 编码。

以前版本的 Keycloak 支持在第一行使用注释（如 # encoding: UTF-8）指定编码，但现在不再支持，并且会被忽略。

主题的消息属性文件现在以 UTF-8 编码读取，并自动回退到 ISO-8859-1 编码。如果您使用不同的编码，请将文件转换为 UTF-8。

在本版本之前，当 Multivalued 设置禁用时，realm（User Realm Role）和客户端（User Client Role）协议映射器都会映射字符串化的 JSON 数组。

然而，Multivalued 设置指示声明应映射为列表，或者如果禁用，则仅映射来自同一值列表的单个值。

在此版本中，当角色和客户端映射器标记为单值（Multivalued 禁用）时，它们现在映射到用户的有效角色中的单个值。

在此版本中，我们希望引入一个切换开关来隐藏/显示密码输入。

通常，所有 <input type="password" name="password" /> 现在都封装在一个 div 中。输入元素后面跟着一个按钮，该按钮可以切换密码输入的可见性。

旧代码示例

新代码示例

当在 OpenShift 上运行时，启用 ingress，并将 spec.ingress.classname 设置为 openshift-default 时，您可以将 Keycloak CR 中的 spec.hostname.hostname 留空。operator 将为 CR 的存储版本分配一个默认主机名，类似于 OpenShift Route 在没有显式主机的情况下创建的主机名，即 ingress-namespace.appsDomain。如果 appsDomain 更改，或者您因任何原因需要不同的主机名，请更新 Keycloak CR。

auto-build CLI 选项已被标记为弃用很长时间。在此版本中，它已被完全移除，不再受支持。

执行 start 命令时，服务器会根据配置自动构建。为了阻止此行为，请设置 --optimized 标志。

kc.sh 不再对参数和环境变量 JAVA_OPTS_APPEND 和 JAVA_ADD_OPENS 使用额外的 shell eval，因此继续使用双重转义/引用将导致参数被误解。例如，不要使用

使用单次转义

此更改还意味着您不能使用单引号值调用 kc.sh 的所有参数。例如，您不能再使用

而是必须使用单独的参数

同样，不要使用

而是必须使用单独的参数

Dockerfile run 命令中也需要使用单独的参数。

表单操作 RegistrationProfile（在身份验证流程的 UI 中显示为 Profile Validation）已从代码库和所有身份验证流程中移除。默认情况下，它位于每个 realm 的内置注册流程中。用户属性的验证以及包括所有用户属性的用户创建都由 RegistrationUserCreation 表单操作处理，因此不再需要 RegistrationProfile。通常，与此更改无关，无需采取进一步操作，除非您在自己的提供程序中使用了 RegistrationProfile 类。

添加了一个新方法，允许搜索和分页顶级组。如果您实现了此接口，则需要实现以下方法

添加了端点 GET {keycloak server}/realms/{realm-name}/groups/{group_id}/children，作为获取支持分页的特定组的子组的一种方式

依赖 RESTEasy Classic 不再是一种选择，因为它不再可用。对于依赖 RESTEasy Classic 和 org.jboss.resteasy.spi.* 相关包的 SPI 和代码，将需要进行迁移。

端点 POST {keycloak server}/realms/{realm-name}/partial-export 和管理控制台中的相应操作现在需要 manage-realm 权限才能执行，而不是 view-realm 权限。此端点将 realm 配置导出到 JSON 文件中，新的权限更合适。参数 exportGroupsAndRoles 和 exportClients 分别将 realm 组/角色和客户端包含在导出中，继续管理相同的权限（query-groups 和 view-clients）。

自此版本起，Keycloak 支持 EventEntity details 列的长值。因此，它不再支持修剪事件详细信息长度的选项 --spi-events-store-jpa-max-detail-length 和 --spi-events-store-jpa-max-field-length。

此版本包括许多与用户配置文件相关的修复和更新，因为我们正在努力将此功能从预览版推广到正式支持版。SPI 存在细微更改，例如在 UserProfileProvider 接口上新添加的方法 boolean isEnabled(RealmModel realm)。此外，一些用户配置文件类和一些验证器相关类（但不是内置验证器实现）已从 keycloak-server-spi-private 模块移动到 keycloak-server-spi 模块。但是，java 类的包保持不变。在某些极端情况下，您可能会受到影响，例如当您使用自己的 UserProfileProvider 实现覆盖内置实现时。但是，请注意 UserProfileProvider 是不受支持的 SPI。

Map Store 在以前的版本中一直是一个实验性功能。从本版本开始，它已被移除，用户应继续使用当前的 JPA 存储。

自此版本起，不再可能使用 --storage 相关 CLI 选项。模块 keycloak-model-map* 已被移除。

所有翻译都已移动到一个文件中，用于管理控制台。如果您制作了自己的翻译或扩展了管理控制台，则需要将它们迁移到这种新格式。此外，如果您的数据库中有“覆盖”，则必须从键中删除命名空间。某些键仅在不同的命名空间中相同，这在帮助文档中最为明显。在这些情况下，我们在键后添加了后缀 Help。

如果您愿意，可以使用此 node 脚本来帮助迁移。它将获取所有单个文件并将它们放入一个新文件中，并处理一些映射

将其保存到 public/locale/<language> 文件夹中名为 transform.mjs 的文件中，并使用以下命令运行它

添加了一个新参数 --spi-user-profile-declarative-user-profile-max-email-local-part-length，用于设置电子邮件本地部分的最大长度，同时考虑向后兼容性。默认值为 64。用法示例

现在已从客户端选项卡“高级设置”的所有组合框中移除了 永不过期 选项。此选项具有误导性，因为不同的生存时间或空闲超时时间永远不是无限的，而是受常规用户会话或 realm 值的限制。因此，移除了此选项，转而使用其他两个剩余选项：从 realm 设置继承（客户端使用常规 realm 超时时间）和 在以下时间过期（为客户端覆盖该值）。在内部，永不过期 由 -1 表示。现在，该值在管理控制台中显示警告，管理员无法直接设置。

为专注于商业和就业的平台引入了一个新的社交身份提供程序，名为 LinkedIn OpenID Connect。LinkedIn 最近发布了一个面向开发人员的新产品，名为 使用 OpenID Connect 登录 LinkedIn。该产品提供了一种使用 OpenID Connect 对成员进行身份验证的新方法，但默认的 OpenID Connect v1.0 身份提供程序目前无法与其配合使用。因此，Keycloak 添加了这个新的身份提供程序，作为新产品的特定社交提供程序。

基于 OAuth 的旧 LinkedIn 方式似乎已从 开发者门户 中完全移除。现有的 LinkedIn 社交提供程序如何与当前应用程序协同工作尚不清楚。Keycloak 保留了旧的提供程序，并将其重命名为 LinkedIn (已弃用)，但在默认禁用的 linkedin-oauth 弃用功能中。它将在未来的版本中移除。如果需要，请在启动时再次启用它

Keycloak 将其代码库从 Java EE（企业版）迁移到其后继者 Jakarta EE，这为 Keycloak 带来了各种变化。

我们已升级所有 Jakarta EE 规范以支持 Jakarta EE 10，例如

Jakarta EE 10 提供了一种现代化、简化、轻量级的方法来构建云原生 Java 应用程序。此举措提供的主要更改是将命名空间从 javax.* 更改为 jakarta.*。这不适用于 JDK 中直接提供的 javax.* 包，例如 javax.security、javax.net、javax.crypto 等。

您的自定义扩展、提供程序或 JPA 实体可能会受到这些更改的影响。

Keycloak 已升级到 Quarkus Java 框架的第 3 版。Quarkus 3 延续了通过快速发展和使用最新技术提供尖端用户体验来推动 Java 开发的传统。它继续提高整体性能和效率。

Quarkus 3 基于 Jakarta EE 10，与 Keycloak 相同，在它们之间创建了平滑的互操作性。此外，它还包含与 Jakarta EE 10 Core Profile 对齐的 Eclipse MicroProfile 6。Quarkus 3 升级的核心部分是内置支持 JPA 3.1 和 Hibernate ORM 6。

Keycloak 现在受益于升级到 Hibernate ORM 6.2，其中包括改进的性能、更好的 SQL、现代 JDK 支持以及对现代 RDBMS 功能的支持。性能改进主要影响 JDBC、HQL 转换和 Criteria 转换。

如果您有自定义提供程序或 JPA 实体，这些更改可能会影响您。

我们建议查看 Quarkus 迁移指南 或 Hibernate 发行说明 以获取更多信息。

旧版 Promise API 方法已从 Keycloak JS 适配器中移除。这意味着不再可能在适配器返回的 Promise 上调用 .success() 和 .error()。而应使用标准化的 Promise 方法，例如 .then() 和 .catch()。

在以前的版本中，export 和 import 命令需要首先运行 build 命令。从本版本开始，如果构建时配置已更改，则 export 和 import 命令将执行 Keycloak 的自动重建。

当迁移首先运行 build 命令的现有脚本时，通过向 export 和 import 命令添加 --optimized 命令行选项进行迁移，以避免 Keycloak 自动重建映像。在此操作中不添加 --optimized 选项可能会导致 Keycloak 触发重建并恢复为默认值，然后连接到数据库进行导出和导入将不起作用。

以下示例假定运行时参数（如数据库密码）通过配置文件或环境变量提供。

在以前的版本中，export 和 import 命令仅允许在配置文件或环境变量中使用运行时参数，例如数据库 URL。从本版本开始，这些运行时参数现在也可以在命令行中使用。使用 --help 选项查找有关支持的参数的信息。

在升级到 Jakarta EE 后，Keycloak Admin 客户端的工件已重命名为更具描述性的名称，并考虑了长期可维护性。我们仍然提供两个单独的 Keycloak Admin 客户端，一个支持 Jakarta EE，另一个支持 Java EE。

我们停止发布 org.keycloak:keycloak-admin-client-jakarta 工件。用于 Keycloak Admin 客户端的默认工件（支持 Jakarta EE）是 org.keycloak:keycloak-admin-client（自 22.0.0 版本起）。

新的支持 Java EE 的工件是 org.keycloak:keycloak-admin-client-jee。

Keycloak 的代理配置设置对于 直通 模式不再解析请求中的 HTTP 转发标头，因为当代理以直通模式转发 HTTPS 连接时，代理无法添加、删除或更新 HTTP 标头。

希望解析客户端请求中的 HTTP 标头的安装应使用 边缘 或 重新加密 设置。

有关详细信息，请参见 使用反向代理。

当您使用 realm 本地化消息时，此更改可能只会影响您。

在此版本之前，当使用 realm 本地化消息时，跨主题的回退消息解析是不一致的。更多信息可以在以下 issue 中找到。

现在，所有主题的实现都已统一。通常，最具体的匹配语言标签的消息具有最高优先级。如果同时存在 realm 本地化消息和主题 i18n 消息，则 realm 本地化消息具有更高的优先级。总结来说，消息的优先级如下（RL = realm 本地化，T = 主题 i18n 文件）：RL <变体> > T <变体> > RL <区域> > T <区域> > RL <语言> > T <语言> > RL en > T en。

可能可以通过一个示例更好地解释这一点：当请求变体 de-CH-1996 并且存在该变体的 realm 本地化消息时，将使用此消息。如果不存在此类 realm 本地化消息，则会在主题 i18n 文件中搜索该变体的相应消息。如果不存在此类消息，则会搜索区域（de-CH）的 realm 本地化消息。如果不存在此类 realm 本地化消息，则会在主题 i18n 文件中搜索该区域的消息。如果仍然找不到消息，则会搜索语言（de）的 realm 本地化消息。如果没有匹配的 realm 本地化消息，则会在主题 i18n 文件中搜索该语言的消息。作为最后的后备方案，将使用英语 (en) 翻译：首先，将搜索英语 realm 本地化 - 如果未找到，则会在主题 i18n 文件中搜索英语消息。

UserQueryProvider 接口已拆分为两个。一个是 UserQueryMethodsProvider，提供查询用户的功能。第二个是 UserCountMethodsProvider，提供计算特定存储中用户数量的功能。

Keycloak 现在能够区分可以高效执行计数查询的用户存储提供程序和不能高效执行计数查询的用户存储提供程序。UserQueryProvider 接口仍然存在，并扩展了这两个新接口。因此，UserQueryProvider 的现有实现无需进行任何修改，因为它保留了相同的方法。

从本版本开始，Keycloak 在查询联合 LDAP 数据库时使用分页机制。搜索用户应与本地数据库中的搜索保持一致。

自此版本起，LDAPStorageProvider 仅实现 UserQueryMethodsProvider，而不实现 UserQueryProvider。

从本版本开始，我们将不再投入时间在以下 Keycloak OpenID Connect 适配器上

此举措已反映在我们的文档和快速入门存储库中。请考虑查看以下参考资料以获取更多信息

我们建议开始考虑将您的应用程序迁移到上述参考资料中的替代方案。这些适配器在未来的版本中应不再可用。

Keycloak JEE SAML 适配器已停止开发，在本版本发布后，我们将不再投入时间进行开发。

官方适配器现在基于 Jakarta，当您将应用程序切换到此技术后，应立即使用该适配器。

此更改已在我们的文档和快速入门存储库中。有关更多信息，请考虑查看以下参考资料

如果您无法将应用程序迁移到 Jakarta，您仍然可以使用“旧版”SAML JEE 适配器，并且仍然能够与服务器的未来版本集成。但是，请考虑尽快升级您的应用程序，因为我们不再为 JEE 提供支持。

预览功能 openshift-integration 已从 Keycloak 代码库中移除，并移动到单独的扩展中。这包括移动相关提供程序，例如自定义客户端存储提供程序和用于 Openshift 集成的令牌审查端点。

如果您使用了此功能，则在启动 Keycloak 服务器时，您不应再使用 openshift-integration 功能，而是需要从自定义扩展部署 JAR 文件。您可以查看 Openshift 扩展 及其 README 文件中的说明，了解如何将扩展部署到您的 Keycloak 服务器。

移除 openshift-integration 使我们能够从 Keycloak 发行版中移除一些第三方依赖项。这包括 openshift-rest-client、okio-jvm、okhttp、commons-lang、commons-compress、jboss-dmr 和 kotlin-stdlib。这意味着，如果您将这些库中的任何一个用作部署到 Keycloak 服务器的您自己的提供程序的依赖项，您可能还需要将这些 jar 文件显式复制到 Keycloak 发行版的 providers 目录中。

为了提供更好的运行时性能并尽可能利用底层堆栈，所有使用 javax.ws.rs.core.Context 注解进行上下文数据注入的点都被移除。预期的性能提升包括在请求生命周期中不再多次创建代理实例，并大幅减少运行时的反射代码量。

如果您正在扩展以下 SPI 之一

您应该检查您的自定义 JAX-RS（子）资源，以便按照以下方式获取任何上下文数据

如果您需要访问当前的请求和响应对象，您现在可以直接从 KeycloakSession 中获取它们的实例

已被替换为

如果您在调用 JAX-RS 资源方法时无法访问 KeycloakSession 实例，您可以从 JAX-RS 运行时获取上下文数据，如下所示

可以通过 KeycloakContext 实例从运行时获取其他上下文数据

如果您正在通过以下 SPI 扩展服务器的 REST API

您需要在打包自定义提供程序的 JAR 文件中添加一个空的 META-INF/beans.xml 文件。否则，它们在运行时不会被服务器识别。

如果您正在使用 RealmResourceSPI 或 AdminRealmResourceSpi，您可以选择在 META-INF 下添加一个名为 beans.xml 的空文件，或者使用 jakarta.ws.rs.ext.Provider 注解来注解 JAX-RS 资源类。

您还应该确保您的 JAX-RS 方法通过使用 @Consumes 和 @Produces 注解分别标记它们来声明预期的输入和输出媒体类型。

在早期版本的 Keycloak 中，提供程序和模型接口经历了一个清理过程，其中涉及弃用某些方法。在此版本中，这些方法已被移除，并且一些其他方法已被弃用。Keycloak 21 中这些方法的 Javadoc 包含了关于其对应替换的信息。

可以在同一命名空间中创建多个 Keycloak CR，并且它们将由 operator 独立管理。为了实现这一点，必须重新创建旧版本 operator 创建的 StatefulSets。当 operator 升级时，这将自动发生，并导致少量停机时间。

条件状态字段从布尔值更改为字符串，以符合标准的 Kubernetes 条件。在 CRD 中，它将暂时表示为接受任何内容，但它将始终是一个字符串。请确保您对该字段的任何使用都已更新为期望值 "True"、"False" 或 "Unknown"，而不是 true 或 false。

Keycloak 支持 IPv4/IPv6 双栈，并且默认可以通过 IPv4 和 IPv6 地址访问。在旧版本的 Keycloak 中，默认方法是仅使用 IPv4 地址。

有关更多详细信息，请参阅 使用 IPv4 或 IPv6 配置 Keycloak 服务器。

在之前的版本中，当 Keycloak 在 Java 17 上与 Javascript 提供程序（脚本身份验证器、Javascript 授权策略或用于 OIDC 和 SAML 客户端的脚本协议映射器）一起使用时，需要将 javascript 引擎复制到发行版中。现在不再需要这样做，因为 Nashorn javascript 引擎默认在 Keycloak 服务器中可用。当您部署脚本提供程序时，建议不要将 nashorn 脚本引擎及其依赖项复制到 Keycloak 发行版中。

服务帐户客户端的默认 客户端 ID 映射器已更改。Token Claim Name 字段值已从 clientId 更改为 client_id。client_id claim 符合 OAuth2 规范

clientId userSession 注释仍然存在。

从历史上看，可以通过直接调用 Keycloak() 函数来创建 Keycloak JS 适配器的实例

为了使其与 JavaScript 世界的现代约定保持一致，可以使用 new 运算符 来创建实例

函数式构造函数已被弃用一段时间，但从这个版本开始，当使用它时，我们将主动记录弃用消息。这种构造函数风格将在未来的版本中移除，因此请确保迁移您的代码以使用 new 运算符。

terms_and_conditions 用户属性在 21.0.0 版本中意外更改为大写。此版本将用户属性恢复为小写。该属性的值在接受条款和条件页面时设置。

如果您的任何自定义扩展依赖于此属性，您可能需要调整您的代码以同时检查 terms_and_conditions 和 TERMS_AND_CONDITIONS 属性。

Keycloak 提供了一个可选的指标端点，该端点以 Prometheus 格式导出指标。在此版本中，提供此数据的实现从 SmallRye 切换到 Micrometer，Micrometer 是 Quarkus 推荐的指标库。

由于此更改，指标已被重命名。下表显示了一些示例。

建议在升级之前和之后查看端点返回的所有指标，并更新仪表板和警报中的用法。

算法 RSA_SHA1 和 DSA_SHA1 在 SAML 适配器、客户端和身份提供程序上可以配置为 签名算法，已被弃用。我们建议使用基于 SHA256 或 SHA512 的更安全的替代方案。此外，在 Java 17 或更高版本上，使用这些算法验证已签名的 SAML 文档或断言的签名不起作用。如果您使用此算法，并且使用您的 SAML 文档的另一方在 Java 17 或更高版本上运行，则签名验证将不起作用。

可能的解决方法是从文件 $JAVA_HOME/conf/security/java.security 中配置的属性 jdk.xml.dsig.secureValidationPolicy 的“不允许的算法”列表中删除诸如 http://www.w3.org/2000/09/xmldsig#rsa-sha1 或 http://www.w3.org/2000/09/xmldsig#dsa-sha1 之类的算法。

在此版本中，Keycloak 将拒绝解密使用为签名目的生成的 realm 密钥加密的断言。此更改意味着从 IDP 到 SP（Keycloak 充当 SP）的所有加密通信将停止工作。

有两种方法可以使其工作

在 Keycloak 13 中，引入了 UserLoginFailureProvider，并且 UserSessionProvider 中的某些方法已移至此处。UserSessionProvider 中的方法已被弃用，现在已被移除。这些方法的 Javadoc 包含了相应的替换（请参阅 Keycloak 20 版本的 Javadoc）。

旧的管理控制台已在之前的版本中弃用，最终被移除。这也意味着您的自定义主题，如果使用它作为父主题或从中导入，将无法工作。强烈建议不要部署此类主题，因为扩展旧的管理控制台已不再适用，并且部署此类主题可能会在 Keycloak 中出现问题（至少在日志中会出现警告或错误）。

Keycloak 容器镜像 已被修改以增强安全性。因此，curl 和其他 CLI 工具已被移除，您可能已在自定义镜像中使用过它们。请参阅更新后的 容器指南，了解如何处理此更改的信息。

将 Keycloak Admin REST 客户端的 RESTEasy 版本更新到下一个主要版本。

Keycloak 出于开发目的附带了 H2 数据库驱动程序。因为它仅用于开发目的，所以绝不应在生产环境中使用。

在此版本中，H2 驱动程序已从 1.x 版本升级到 2.x 版本。此更改可能需要更改 H2 JDBC URL 或迁移现有 Keycloak 设置中的 H2 数据库文件。

此版本包含 Keycloak CR 中的以下重大更改

Keycloak Operator Lifecycle Manager 的默认通道已更改为 fast。

在 Keycloak 15 之前，我们清理了提供程序和模型接口，其中我们弃用了一些方法。这些方法的 Javadoc 包含相应的替换方法（请参阅 Keycloak 19 版本的 Javadoc）。在此版本中，这些方法已被移除。以下是所有已更改类的列表。

弃用和移除方法的最常见模式如下。

在 Keycloak 18.0.0 中，注销现在与新的 OIDC 规范兼容，该规范更改了 url 参数的处理方式。但是，为了也与早期版本保持兼容，引入了一个兼容性标志。有关向后兼容性选项的更多信息，请参阅 升级指南，该选项允许您的应用程序仍然使用旧格式的 url 参数。

虽然现在可以将 url 参数配置为兼容，但与 Keycloak 17 及更早版本仍然存在一个不兼容之处。如果用户未提供有效的 idTokenHint，则会显示注销提示而不是成功的注销重定向。因此，引入了一个新的兼容性标志 suppress-logout-confirmation-screen 以抑制注销屏幕。

您可以在启动服务器时通过输入以下命令来启用此参数

通过此配置，您仍然可以使用注销端点，而无需用户提示。

到目前为止，在其 SAML 客户端或客户端作用域上使用 SAML javascript 协议映射器的管理员，可以通过 Keycloak 管理控制台以及 RESTful Admin API 将脚本上传到服务器。

从现在开始，此功能被禁用，用户应直接将脚本部署到服务器。此行为与其他基于脚本的提供程序保持一致。有关更多详细信息，请查看 JavaScript 提供程序。

新的管理控制台现在是 Keycloak 中的默认控制台。如果您无法开始使用新的管理控制台，可以继续使用旧的管理控制台，方法是禁用新的控制台，例如运行

继续使用旧的管理控制台的另一种方法是将 master realm 或任何其他 realm 的主题设置为 keycloak。

由于新的管理控制台与旧的管理控制台显着不同，现在基于 React 并使用较新版本的 PatternFly，因此任何自定义主题都极有可能必须从头开始重新实现。要为新的管理控制台创建自定义主题，该主题应扩展 keycloak.v2 而不是 keycloak。

如果您已明确将 master realm 或任何其他 realm 的管理控制台主题设置为 keycloak，它将继续使用旧的管理控制台。要更新到新的管理控制台，您需要将主题更改为 keycloak.v2。

旧的管理控制台将在 Keycloak 21 中移除。

在此版本之前，您会在运行 start 命令时使用 --auto-build 来告诉服务器，如果任何构建选项在启动服务器之前已更改，则有条件地运行 build。

在此版本中，--auto-build 标志已弃用，您不再需要使用它来指示您要在启动服务器时设置构建选项。相反，如果任何构建选项已更改，服务器始终默认在启动服务器之前运行 build。新的行为改进了配置和启动服务器的整体体验，使其成为可选的（尽管强烈建议），以便为了获得最佳启动时间和内存占用而预先运行 build 命令。

现在，为了获得最佳启动时间和内存占用，请设置 --optimized 选项以禁用新的默认行为。--optimized 标志告诉服务器，不需要直接作为启动一部分检查和运行 build

如果您已经使用自定义镜像来设置构建选项并运行优化的 Keycloak 容器，请确保在调用 start 命令时设置 --optimized 选项。

有关更多详细信息，请查看 配置指南 和 容器指南。

在 Keycloak 19.0.0 之前，基于 quarkus 的 Keycloak 发行版总是意外地启用了以下非应用程序端点

从 Keycloak 19.0.0 开始，这些端点被禁用，请求将导致 404 HTTP 状态代码。如果您正在使用 /q/…​ 端点，请确保在升级到 Keycloak 19.0.0 时更改您的探测和监控系统以使用预期的健康端点。

预期的健康端点是

除了禁用 /q/ 端点外，以下是对健康端点进行的其它改进

预计未来会在这个领域有更多增强功能。有关更多信息，请参阅 健康指南

正如发布说明中所述，Keycloak 现在开箱即用地支持 gelf 日志记录，用于集中式日志记录系统。

如果您在之前的版本中自己添加了 gelf 相关的 quarkus jar 包，请务必切换到 日志记录指南 中受支持的配置选项，并从 providers 文件夹中删除您的 jar 包。

Keycloak 正在进行大规模重构，这会影响现有代码。其中一些更改需要更新现有代码。这些更改将在下面更详细地描述。

在此版本中，我们已弃用 旧式 Keycloak Operator 的 Keycloak CR 中的 podDisruptionBudget 字段。当 Operator 部署在 Kubernetes 1.25 及更高版本上时，将忽略此可选字段。

作为一种解决方法，您可以在集群中手动创建 Pod Disruption Budget，例如

另请参阅 Kubernetes 文档。

新的 Keycloak Operator 现在对 Keycloak 部署使用 StatefulSet 而不是 Deployment。由于 Operator 在此版本中是技术预览版，因此没有自动迁移。如果您在 18.0.z 中使用新的 Operator，请务必在升级到 19.0.0 后备份、删除并重新创建您的 Keycloak CR。

逐步验证是一项新功能。此功能提供 acr 客户端作用域，其中包含一个协议映射器，该映射器应将 acr 声明添加到令牌中。acr 声明现在不会像此版本之前那样自动添加，而是通过使用此客户端作用域和协议映射器来添加。

客户端作用域作为 realm “默认”客户端作用域添加，因此将添加到所有新创建的客户端。出于性能原因，客户端作用域不会在迁移期间自动添加到所有现有客户端。迁移后，客户端默认情况下不会具有 acr 声明。考虑以下可能的措施

以前版本的 Keycloak 支持通过打开注销端点 URL（例如 http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri）自动注销用户并重定向到应用程序。虽然该实现易于使用，但它可能对性能和安全性产生负面影响。新版本更好地支持基于 OpenID Connect RP-Initiated Logout 规范的注销。不再支持参数 redirect_uri；此外，在新版本中，用户需要确认注销。当您包含参数 post_logout_redirect_uri 以及带有用于登录的 ID 令牌的参数 id_token_hint 时，可以省略确认并执行自动重定向到应用程序。

现有部署会受到以下影响

有一个向后兼容性选项，允许您的应用程序仍然使用旧格式的 redirect_uri 参数。

您可以在启动服务器时通过输入以下命令来启用此参数

通过此配置，您仍然可以使用带有 redirect_uri 参数的格式。请注意，如果省略 id_token_hint，则需要确认屏幕。

以前版本的 Keycloak 支持通过管理界面（如管理控制台和 REST API）管理 JavaScript 代码。从此版本开始，不再可能这样做，您现在应该将脚本部署到服务器，以便配置以下提供程序

有关如何将脚本部署到服务器的更多详细信息，请参阅文档。请注意，要使用脚本，您仍然需要启用 scripts 技术预览功能。

部署脚本时，服务器将自动创建其相应的提供程序，以便您可以在配置身份验证流程、映射器和授权策略时选择它们。

一般来说，更新 realm 的步骤如下

Patternfly (PF) React 库已更新，@patternfly/react-core 从 v3.153.3 更新到 v4.147.0，@patternfly/react-icons 从 v3.15.16 更新到 v 4.11.8，以及 @patternfly/react-styles 从 v3.7.14 更新到 v4.11.8。对帐户控制台进行了一些小的 UI 更新，使其与 PF 设计标准保持一致。

由于 PF 中的重大更改，自定义开发的帐户 UI 可能与这些更新不兼容。大多数重大更改应通过更新 PF 组件上的 props 来解决。

资源

已知具有重大更改的组件

metrics-enabled 选项现在仅启用 Keycloak 的指标。要启用就绪和活跃度健康端点，有一个新的布尔选项 health-enabled。这允许更细粒度地使用这些选项，例如，启用指标但不为本地用例启用就绪/活跃度探测。为了保持与之前设置 metrics-enabled=true 时的相同行为，您需要在构建 Keycloak 时额外设置 health-enabled=true。

Keycloak 的默认分发版现在由 Quarkus 提供支持，这为您配置 Keycloak 和部署自定义提供程序带来了一些重大更改。有关更多信息，请查看 Quarkus 迁移指南。

Keycloak 的 WildFly 分发版现已弃用，支持将于 2022 年 6 月结束。我们建议尽快迁移到 Quarkus 分发版。但是，如果您需要在旧版 WildFly 分发版上保留一段时间，则需要考虑一些更改

如果您在迁移到 Quarkus 分发版时遇到问题，缺少配置某些内容的能力，或者有一般想法和反馈，请在 GitHub Discussions 中发起讨论。

自 Keycloak 15.1.0 中发布预览版 Quarkus 分发版以来，许多内容已更改。了解已更改内容的理想方法是查看新的 服务器指南。总而言之，更改包括

如果您使用了包含 client-scopes 条件的策略并直接编辑了 JSON 文档，则需要将 JSON 文档中的 “scope” 字段名称更改为 “scopes”。

Liquibase 从 3.5.5 版本更新到 4.6.2 版本，其中包括许多错误修复以及使用 ServiceLoader 注册自定义扩展的新方法。

从以前的 Keycloak 版本到 Keycloak 17.0.0 的迁移已经过所有当前支持的数据库的广泛测试，但我们要强调密切关注 升级指南 的重要性，特别是在升级前备份现有数据库。虽然我们尽力测试了 Liquibase 升级的后果，但某些安装可能正在使用我们未知的特定设置。

WildFly 25 弃用了旧式安全子系统，该子系统除其他外还用于配置 TLS。由于更改量很大，我们无法像过去那样提供迁移脚本。

我们建议您从 Keycloak 16 中提供的默认配置文件开始，并应用相关的更改，而不是复制以前版本的 Keycloak 的配置文件。

Keycloak 子系统的配置可以直接复制。

有关 Elytron 子系统的更多信息，请参阅 WildFly 文档。

对于由此带来的不便，我们深感抱歉，并理解这将使所有人升级到 Keycloak 16 变得更加困难，但我们实在找不到替代方法。

值得指出的一件事是切换到 Quarkus 分发版，我们计划在 Keycloak 17 中使其完全受支持，这将使配置和升级 Keycloak 变得更加容易。

有关 WildFly 25 的更多信息，请参阅 WildFly 25 发行说明。

Keycloak 现在尊重标准 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量，用于传出的 HTTP 请求。如果您定义了 HTTP_PROXY 变量，但在 SPI 配置中没有指定显式代理映射，则此更改可能会导致意外使用代理服务器。要防止 Keycloak 使用这些环境变量，您可以为所有请求显式创建无代理路由，如 .*;NO_PROXY。

在此版本中，我们已弃用和/或标记为不受支持 Keycloak Operator 中的某些功能。这涉及 Backup CRD 和 operator 管理的 Postgres 数据库。

以前，在 Keycloak Operator 创建 Keycloak CR 的示例中添加了一个不受支持的 metrics 扩展。这已被删除。

客户端策略功能自 Keycloak 12 以来一直是预览功能，并且没有适当的支持。如果您尝试过此功能并在 Keycloak 12 或 Keycloak 13 中配置了一些客户端策略或客户端配置文件，则需要在新版本中再次配置您的客户端策略和客户端配置文件。配置的格式已发生重大更改，因为它只是一个预览版，因此我们不提供 Keycloak 12 或 Keycloak 13 中创建的客户端策略和客户端配置文件的自动迁移。

当 standalone.xml 包含对任何 SmallRye 模块的引用时，需要手动更改。SmallRye 模块已从底层 WildFly 分发版中删除，并且如果配置引用它们，服务器将无法启动。因此，如果 standalone.xml 中的配置引用了这些模块，则通过 migrate-standalone.cli 的服务器配置迁移在对配置进行任何更改之前就会失败。在这种情况下，要执行服务器配置迁移，您必须手动删除所有引用 SmallRye 模块的行。在默认配置中，您需要专门删除以下行

Keycloak 服务器已升级为使用 Wildfly 23 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

Keycloak 服务器已升级为使用 Wildfly 22 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

添加了对只读用户属性的支持。这包括用户属性，这些属性不应由用户或管理员在通过 REST API 或 Keycloak 用户界面更新用户时进行编辑。如果您使用以下功能，这一点尤其重要

有关详细信息，请参阅 威胁模型缓解章节。

如果您使用 OpenID Connect 参数 request_uri，则您的客户端需要配置 Valid Request URIs。这可以通过管理控制台在客户端详细信息页面上配置，也可以通过管理 REST API 或客户端注册 API 配置。Valid Request URIs 需要包含特定客户端允许的请求 URI 值列表。这是为了避免 SSRF 攻击。可以像 Valid Redirect URIs 选项一样使用通配符或相对路径，但出于安全目的，我们通常建议使用尽可能具体的值。

Keycloak 服务器已升级为使用 Wildfly 22 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但有一些与迁移相关的更改值得一提。

Keycloak 服务器已升级为使用 Wildfly 21 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

使用 Docker 协议成功进行身份验证后，不会创建用户会话。有关详细信息，请参阅服务器管理指南。

Keycloak 登录主题组件已升级到 PatternFly 4。旧的 PatternFly 3 与新的 PatternFly 4 同时运行，因此可以保留 PF3 组件。但是，对登录主题的设计进行了一些更改。请根据这些更改升级您的自定义登录主题。在 keycloak/examples/themes/theme/sunrise 目录中可以找到包含必要更改的示例。无需其他设置。

从这个 Keycloak 版本开始，OAuth2 客户端凭据授权端点默认情况下不颁发刷新令牌。此行为与 OAuth2 规范一致。此更改的副作用是，在成功进行客户端凭据身份验证后，Keycloak 服务器端不会创建用户会话，从而提高了性能和内存消耗。建议使用客户端凭据授权的客户端停止使用刷新令牌，而是在每次请求时始终使用 grant_type=client_credentials 进行身份验证，而不是使用 refresh_token 作为授权类型。与此相关的是，Keycloak 在 OAuth2 撤销端点中支持撤销访问令牌，因此允许客户端在需要时撤销单个访问令牌。

为了向后兼容，仍然可以坚持旧版本的行为。当使用此功能时，在客户端凭据授权成功身份验证后，仍将颁发刷新令牌，并且还将创建用户会话。可以在 Keycloak 管理控制台中的特定客户端上启用此功能，在客户端详细信息中，在 OpenID Connect 兼容模式 部分，使用 对客户端凭据授权使用刷新令牌 开关。

Keycloak 服务器已升级为使用 Wildfly 20 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

在之前的 Keycloak 版本中，当 LDAP 提供程序配置为 导入用户 关闭时，即使某些非 LDAP 映射的属性被更改，也可以更新用户。这种情况导致了令人困惑的行为，即属性似乎已更新，但实际上并未更新。在当前版本中，如果任何非 LDAP 映射的属性被更改，则完全不允许执行更新。

这应该不会影响大多数部署，但某些情况下可能会在一些罕见的情况下受到影响。例如，如果您之前尝试使用管理 REST API 更新用户，并且该用户有一些不正确的属性更改，则可以进行更新。在当前版本中，更新是不可能的，您将立即被告知原因。

UserModel 中的字段 username、email、firstName 和 lastName 已迁移到自定义属性，为在即将到来的版本中向 Keycloak 添加更复杂的用户配置文件做准备。如果数据库包含具有完全相同名称的自定义属性的用户，则需要在升级之前迁移自定义属性。此迁移不会自动发生。否则，它们将不再从数据库中读取，并可能被删除。这种情况意味着现在也可以通过 UserModel.getFirstAttribute(UserModel.USERNAME) 访问和设置 username。其他字段也存在类似的含义。直接或间接子类化 UserModel 的 SPI 的实现者应确保 setUsername 和 setSingleAttribute(UserModel.USERNAME, …​)（以及其他字段的类似方法）之间的行为是一致的。策略评估功能的用户如果在其评估中使用属性数量，则必须调整其策略，因为现在每个用户默认都将拥有四个新属性。

UserModel 的公共 API 没有更改。无需更改前端资源或访问用户数据的 SPI。此外，数据库尚未更改。

Instagram IdP 现在使用新的 API，因为旧的旧版 API 已弃用。这需要获取新的 API 凭据。有关详细信息，请参阅服务器管理指南。

对于使用 Instagram IdP 的现有用户，特别是那些将其作为唯一身份验证选项的用户，需要特别注意。此类用户必须在 2020 年 9 月 30 日之前使用 Instagram IdP 登录 Keycloak。在那天之后，他们将必须使用不同的身份验证方法（如密码）登录以手动更新其 Instagram 社交链接，或在 Keycloak 中创建新帐户。这是因为 Instagram 用户 ID 在旧 API 和新 API 之间不兼容，但新 API 暂时返回新旧用户 ID 以允许迁移。Keycloak 会在用户登录后自动迁移 ID。

在以前的版本中，Keycloak 公布了两个内省端点：token_introspection_endpoint 和 introspection_endpoint。后者是 RFC-8414 定义的端点。前者以前已弃用，现在已删除。

不再需要在 JavaScript 适配器中设置 promiseType，并且两者都同时可用。建议尽快更新应用程序以使用原生 Promise API (then 和 catch)，因为旧版 API (success 和 error) 将在某个时候被删除。

9.0.1 版本修复了一个问题，该问题可能会在领域中创建重复的顶级组。然而，之前重复组的存在使升级过程失败。如果 Keycloak 服务器正在使用 H2、MariaDB、MySQL 或 PostgreSQL 数据库，则可能会受到此问题的影响。在启动升级之前，请检查服务器是否包含重复的顶级组。例如，可以在数据库级别执行以下 SQL 查询来列出它们

在每个领域中，只能存在一个同名的顶级组。重复项应在升级前进行审核和删除。升级中的错误包含消息 Change Set META-INF/jpa-changelog-9.0.1.xml::9.0.1- KEYCLOAK-12579-add-not-null-constraint::keycloak failed.

对如何选择登录页面的区域设置以及何时更新用户的区域设置进行了一些改进。

有关更多详细信息，请参阅服务器管理指南。

在 2038 年，int 将无法再保存自 1970 年以来的秒数值，因此我们正在努力将这些值更新为 long 值。此外，令牌表示中还存在另一个与处理 int 值相关的问题。int 默认情况下将在 JSON 表示中生成 0，但它不应包含在内。

有关已弃用方法的详细信息和替换方法，请参阅 JavaDocs。

旧的请求和固定主机名提供程序已替换为新的默认主机名提供程序。请求和固定主机名提供程序现在已弃用，建议尽快切换到默认主机名提供程序。

Keycloak 服务器已升级为使用 Wildfly 18 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

到目前为止，管理员可以通过 Keycloak 管理控制台以及 RESTful 管理 API 将脚本上传到服务器。

从现在开始，默认情况下此功能已禁用，用户应首选将脚本直接部署到服务器。有关更多详细信息，请查看JavaScript 提供程序。

在以前的版本中，开发人员被允许向 JavaScript 适配器提供客户端凭据。从现在开始，此功能已删除，因为客户端应用不安全，无法保存机密信息。

我们对身份验证流程进行了一些重构和改进，这需要在迁移期间引起一些注意。

我们增加了围绕用户凭据存储的灵活性。除其他事项外，每个用户可以拥有相同类型的多个凭据，例如多个 OTP 凭据。因此，对数据库架构进行了一些更改。但是，以前版本中的凭据应自动更新为新格式，并且用户仍然应该能够使用在以前版本中设置的密码或 OTP 凭据登录。

Keycloak 服务器已升级为使用 Wildfly 17 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

Keycloak 服务器已升级为使用 Wildfly 16 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

我们添加了一个新的 microprofile-jwt 可选客户端作用域来处理 MicroProfile/JWT Auth 规范中定义的声明。这个新的客户端作用域定义了协议映射器，用于将已验证用户的用户名设置为 upn 声明，并将领域角色设置为 groups 声明。

我们在 OIDC 身份提供程序配置中添加了一个名为 接受来自客户端的 prompt=none 转发 的新开关，以标识能够处理包含 prompt=none 查询参数的转发请求的 IDP。

到目前为止，当收到带有 prompt=none 的身份验证请求时，如果用户未在领域中进行身份验证，则领域将返回 login_required 错误，而无需检查用户是否已通过 IDP 进行身份验证。从现在开始，如果可以为身份验证请求确定默认 IDP（通过使用 kc_idp_hint 查询参数或为领域设置默认 IDP），并且如果为 IDP 启用了 接受来自客户端的 prompt=none 转发 开关，则身份验证请求将转发到 IDP 以检查用户是否已在那里进行身份验证。

重要的是要注意，仅当指定了默认 IDP 时，此开关才会被考虑在内，在这种情况下，我们知道将身份验证请求转发到哪里，而无需提示用户选择 IDP。如果无法确定默认 IDP，我们无法假定将使用哪个 IDP 来满足身份验证请求，因此不会执行请求转发。

Keycloak 服务器已升级为使用 Wildfly 15 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

Keycloak 4.8.1 及更早版本中的 Google 身份提供程序实现依赖于 Google+ API 端点进行授权和获取用户个人资料。从 2019 年 3 月起，Google 将取消对 Google+ API 的支持，转而使用新的 Google Sign-in 身份验证系统。Keycloak 身份提供程序已更新为使用新的端点，因此如果正在使用此集成，请确保升级到 Keycloak 4.8.2 或更高版本。

如果您遇到错误，提示在目录中找不到应用程序标识符，您将需要在 Google API 控制台 门户中重新注册客户端应用程序，以获取新的应用程序 ID 和密钥。

您可能需要调整自定义映射器，以适应 Google+ 用户信息端点提供的非标准声明，以及 Google Sign-in API 以不同名称提供的声明。请查阅 Google 文档，以获取有关可用声明的最新信息。

根据 LinkedIn 的说法，所有开发人员都需要迁移到其 API 和 OAuth 2.0 的版本 2.0。因此，我们更新了 LinkedIn 社交代理。

使用此代理的现有部署在尝试使用 LinkedIn API 的版本 2 获取用户个人资料时，可能会开始遇到错误。此错误可能与用于配置代理的客户端应用程序缺乏授权访问 Profile API 或在身份验证过程中请求特定 OAuth2 作用域的权限有关。

即使对于新创建的 LinkedIn 客户端应用程序，您也需要确保客户端能够请求 r_liteprofile 和 r_emailaddress OAuth2 作用域（至少），以及客户端应用程序可以从 https://api.linkedin.com/v2/me 端点获取当前成员的个人资料。

由于 LinkedIn 在访问成员信息方面施加的这些隐私限制，以及当前成员的 Profile API 返回的声明集有限，LinkedIn 社交代理现在使用成员的电子邮件地址作为默认用户名。这意味着在身份验证期间发送授权请求时，始终会设置 r_emailaddress。

我们添加了新的领域默认客户端作用域 roles 和 web-origins。这些客户端作用域包含协议映射器，用于将用户的角色和允许的 Web 源添加到令牌。在迁移期间，这些客户端作用域应自动添加到所有 OpenID Connect 客户端作为默认客户端作用域。因此，数据库迁移完成后无需进行任何设置。

要将原生 JavaScript Promise 与 JavaScript 适配器一起使用，现在需要在 init 选项中将 promiseType 设置为 native。

过去，如果原生 Promise 可用，则会返回一个包装器，该包装器同时提供旧版 Keycloak Promise 和原生 Promise。这导致了一些问题，因为错误处理程序并非总是在原生错误事件之前设置，从而导致 Uncaught (in promise) 错误。

Keycloak 4.5.0 及更早版本中的 Microsoft 身份提供程序实现依赖于 Live SDK 端点进行授权和获取用户个人资料。从 2018 年 11 月起，Microsoft 将取消对 Live SDK API 的支持，转而使用新的 Microsoft Graph API。Keycloak 身份提供程序已更新为使用新的端点，因此如果正在使用此集成，请确保升级到 Keycloak 4.6.0 或更高版本。

由于应用程序的 ID 格式发生更改，在“Live SDK 应用程序”下注册的旧版客户端应用程序将无法与 Microsoft Graph 端点一起使用。如果您遇到错误，提示在目录中找不到应用程序标识符，您将需要在 Microsoft 应用程序注册 门户中重新注册客户端应用程序，以获取新的应用程序 ID。

Keycloak 服务器已升级为使用 Wildfly 14 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

Keycloak 服务器已升级为使用 Wildfly 13 作为底层容器。这不直接涉及任何特定的 Keycloak 服务器功能，但是，请注意与迁移相关的这些更改

在以前的版本中，建议使用过滤器来指定允许的主机名。现在可以设置固定主机名，这使得更容易确保使用有效的主机名，并且还允许内部应用程序通过备用 URL（例如内部 IP 地址）调用 Keycloak。建议您在生产环境中切换到此方法。

我们增加了对客户端作用域的支持，这在迁移期间需要一些注意。