升级指南

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

为了防止丢失用户会话，请先升级到 Keycloak 25，然后按照 Keycloak 25 迁移指南中的说明启用持久会话功能。

运算符将不再默认设置为主机名 v1 设置 proxy=passthrough。这允许使用主机名 v2 为固定边缘主机名进行部署，以便在没有其他选项的情况下按预期工作。

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

当多个事件发送到同一个 taskKey 时，此方法会将事件批处理，并且只执行一次网络调用。这是一种优化方法，可以减少流量和与网络相关的资源。

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

为了提高组的可扩展性，现在在删除领域时直接从数据库中删除组。因此，当删除领域时，与组相关的事件（例如 GroupRemovedEvent）不再被触发。

如果您有扩展程序在删除领域时处理任何与组相关的事件，请确保使用 RealmRemovedEvent 而不是 GroupRemovedEvent 来执行任何清理或自定义处理，以便在删除领域及其组时执行任何清理或自定义处理。

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

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

当指定 http-management-relative-path 或 http-relative-path 属性时，管理界面也是如此。

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

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

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

以下项目已弃用，将在即将发布的 Keycloak 版本中删除，没有替代品

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

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

与之前的版本相比，任何与 LDAP 连接池相关的领域配置都将被忽略。如果您要从之前的版本迁移，其中在 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}/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（已启用、不是仅链接、未标记为隐藏在登录页面上的 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 选项与 hostname 选项结合使用（根据需要）替换。有关更多详细信息，请参阅 使用反向代理 和 初始升级指南。

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

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

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

以前版本的 Keycloak 在用户和客户端会话的空闲时间添加了 2 分钟的宽限期。 这是由于以前的体系结构，其中会话刷新时间在集群中异步复制。 使用持久用户会话，这不再必要，因此宽限期现在已删除。

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

以前版本的 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或通过任何其他服务器命令（如start、export、import）来实现，而不带--optimized标志。

org.keycloak.bom:keycloak-adapter-bom和org.keycloak.bom:keycloak-misc-bom BOM 文件已删除。 适配器 BOM 已经没有用处，因为大多数 Java 适配器都已删除。 杂项 BOM 仅包含一个工件keycloak-test-helper，该工件也将在本版本中删除。

maven 工件org.keycloak:keycloak-test-helper在本版本中已删除。 该工件提供了一些用于处理 Java 管理客户端的帮助方法。 如果您使用帮助方法，则可以根据需要将它们分叉到您的应用程序中。

JEE 管理客户端在本版本中已删除。 我们仍然支持 Jakarta 管理客户端。

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

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

在运行带有--import-realm选项的start或start-dev命令之前，如果主 realm 不存在，则如果它存在于导入材料中，它将被导入。 以前的行为是先创建主 realm，然后跳过其导入。

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

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

groups.setOrCreateChild()方法已从基于 JavaScript 的管理客户端中删除。 如果您仍在使用此方法，请改用createChildGroup()或updateChildGroup()方法。

此版本包含对 Keycloak JS 库的几个更改，应予以考虑。 这些更改的主要动机是将库与 Keycloak 服务器分离，以便可以独立地重构它，简化代码并使其在将来更容易维护。 更改如下

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

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

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

如果攻击者以并行方式启动了许多登录尝试，则攻击者对密码的猜测次数可能超过暴力破解保护配置允许的次数。 这是因为暴力破解检查发生在暴力破解保护器锁定用户之前。 为了防止这种竞争情况，暴力破解保护器现在拒绝在同一服务器上另一个登录正在进行时发生的所有登录尝试。

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

当客户端范围或整个 realm 被删除时，相关的用户同意也应该被删除。为了提升性能，一个新的索引被添加到 USER_CONSENT_CLIENT_SCOPE 表中。

注意，如果该表包含超过 300,000 条记录，Keycloak 默认会在自动 Schema 迁移过程中跳过索引创建，并将 SQL 语句日志记录到控制台。在 Keycloak 启动后，需要在数据库中手动运行这些语句。有关如何配置不同限制的详细信息，请查看 升级指南。

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

必要的迁移列表

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

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

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

除非它是 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 来启用默认直方图存储桶或服务级别目标 (SLO) 的特定存储桶。阅读有关 Prometheus 文档中的直方图 的更多信息，了解如何使用 http_server_requests_seconds_bucket 中提供的其他指标系列。

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

在某些情况下，例如 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 个字母或 3 个字母的顶级域结尾的 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 阶段不会被识别，因此您需要删除它们。

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

在按用户属性搜索用户时，Keycloak 不再搜索用户属性名称以强制执行小写比较。这意味着在搜索时现在将使用 Keycloak 对用户属性表进行的本机索引。如果您已创建了基于 `lower(name)` 的自己的索引以加快搜索速度，那么您现在可以删除它。

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

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

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

session_state 声明（包含与 sid 声明相同的值）现在已从所有令牌中删除，因为它不是 OpenID Connect 前端通道注销和 OpenID Connect 后端通道注销规范所必需的。session_state 声明仍将按照 OpenID Connect 会话管理规范出现在访问令牌响应中。

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

还包括一个新的 会话状态 (session_state) 映射器，可以将其分配给客户端范围（例如 basic 客户端范围）以恢复到旧的行为。

如果使用的是旧版本的 JS 适配器，则也应通过使用上面描述的客户端范围来使用 会话状态 (session_state) 映射器。

sub 声明（始终添加到访问令牌中）现在默认添加，但使用新的 主体 (sub) 协议映射器。

主体 (sub) 映射器在 basic 客户端范围内默认配置。因此，升级到此版本后不需要额外的配置。

如果您使用 成对主体标识符 映射器来映射访问令牌的 sub 声明，您可以考虑禁用或删除 主体 (sub) 映射器，但这并不严格需要，因为 主体 (sub) 协议映射器在 成对主体标识符 映射器之前执行，因此 pairwise 值将覆盖 主体 (sub) 映射器添加的值。这可能也适用于其他自定义协议映射器实现，这些实现覆盖 sub 声明，因为 主体 (sub) 映射器当前作为第一个协议映射器执行。

您可以使用 主体 (sub) 映射器仅为访问令牌、轻量级访问令牌和自检响应配置 sub 声明。IDToken 和 Userinfo 始终包含 sub 声明。

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

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

软件中还包括一个新的 Nonce 向后兼容 映射器，可以将其分配给客户端范围以恢复到旧的行为。例如，JS 适配器在解决问题 #26651（在 24.0.0 版本中）之前，检查了所有令牌中返回的 nonce 声明。因此，如果使用的是旧版本的 JS 适配器，则应通过使用客户端范围将其添加到所需的客户端。

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 规范支持。这包括

您可以将协议映射器直接添加到相应的客户端或某个客户端范围，这可供依赖 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 实现替换。旧的提供程序已弃用但未删除，以防它在某些现有领域仍然有效。Keycloak 25.0.0 肯定删除了旧的提供程序及其关联的linkedin-oauth功能。从现在起，默认的LinkedIn社交提供程序是唯一可用的选项。

当RESOURCE_SERVER_RESOURCE和RESOURCE_SERVER_PERM_TICKET表具有超过 100k 个条目，并且用户被授予对超过 1k 个资源的访问权限时，这些查询的执行效率低下。查询已简化，并为requester和owner列引入了新的索引。

新索引都应用于RESOURCE_SERVER_PERM_TICKET表。如果该表当前包含超过 300,000 个条目，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。外部 Infinispan 部署受 HA 指南中概述的多站点设置的支持。

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

以下变量已在管理主题中弃用，并将

以下变量已在帐户主题中弃用，并将

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

通过管理用户 API 更新用户属性时，在更新用户属性（包括username、email、firstName和lastName等根属性）时，不能执行部分更新。

如果通过管理用户 API 更新用户属性，但不传递管理员具有写入权限的所有属性，则将删除缺失的属性。另一方面，如果属性被标记为对管理员只读，则不发送该属性不会删除它。

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

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

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

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

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

完整通配符*仍可作为开发中的有效重定向在具有这些特征的 http(s) URI 中使用。在生产环境中，需要为任何类型的 URI 配置不带通配符的精确有效重定向 URI。

请注意，通配符有效重定向 URI 不建议用于生产环境，也不受 OAuth 2.0 规范的涵盖。

用于删除用户凭据的帐户 REST 端点已弃用。从本版本开始，帐户控制台不再使用此端点。它被替换为由帐户控制台在用户想要删除用户的凭据时触发的“删除凭据”应用程序启动操作。

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

“欢迎”主题已更新为使用新布局，现在使用 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 的其他部分。

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

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

您也可以在使用 Operator 时设置代理标头。

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

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

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

为了解析所有属性（包括根属性），添加了新的getRawAttributes方法，以便生成的映射还包含根属性。但是，此方法无法从表示形式有效负载中获取，它旨在由服务器在管理用户资料时使用。

选项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 会在自动模式迁移期间默认跳过索引创建，并在启动 Keycloak 之后在控制台中记录 SQL 语句以手动应用。有关如何配置不同限制的详细信息，请参阅升级指南。

在此版本中，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 的密码散列算法的默认散列迭代次数已更改如下：

如果领域未明确配置具有 hashAlgorithm 和 hashIterations 的密码策略，则新配置将在下次基于密码的登录时生效，或在创建或更新用户密码时生效。

现在将通过 Keycloak CR 引用的 Secrets 和 ConfigMaps 轮询更改，而不是通过 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.keycloak 更改为 kc.operator.keycloak。

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

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

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

Keycloak 用于对内部令牌（Keycloak 本身使用，例如刷新令牌或操作令牌）进行签名的算法已从 HS256 更改为更安全的 HS512。现在为领域添加了一个名为 hmac-generated-hs512 的新密钥提供程序。请注意，在迁移的领域中，将保留旧的 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（“子项”），其中参数 briefRepresentation 的含义是检索子组的完整表示。现在该含义已更改为返回简要表示。

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

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

虽然这在配置客户端时引入了更多步骤和冗长性，但新的行为使更安全的部署成为可能，因为基于模式的检查通常是安全问题的根源。这些问题源于它们的实现方式和配置方式。

旧版本的 operator 创建了一个密钥来跟踪被观察的密钥。新版本的 operator 不再使用 -secrets-store 密钥，因此可以将其删除。

如果您使用的是 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 密钥，或者升级到 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。

在本版本之前，realm（`用户 realm 角色`）和客户端（`用户客户端角色`）协议映射器在禁用 `Multivalued` 设置时映射一个字符串化的 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 中显示为 `配置文件验证`）已从代码库中删除，也从所有身份验证流中删除。默认情况下，它位于每个 realm 的内置注册流中。用户属性的验证以及包括所有用户属性的用户创建由 `RegistrationUserCreation` 表单操作处理，因此 `RegistrationProfile` 不再需要。通常，与此更改相关的操作不需要进一步的步骤，除非您在自己的提供者中使用了 `RegistrationProfile` 类。

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

端点 `GET {keycloak 服务器}/realms/{realm}/groups/{group_id}/children` 添加为一种获取支持分页的特定组的子组的方法

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

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

从本版本开始，Keycloak 支持 `EventEntity` 详细信息列的较长值。因此，它不再支持修剪事件详细信息长度的选项 `--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。使用示例：

现在已从客户端高级设置选项卡的所有组合中移除“永不过期”选项。此选项具有误导性，因为不同的生存期或空闲超时并非无限，而是受一般用户会话或领域值的限制。因此，此选项已被移除，取而代之的是另外两个选项：“继承自领域设置”（客户端使用一般领域超时）和“在...分钟后过期”（该值将覆盖客户端）。在内部，“永不过期”由-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 相同，在它们之间创建了流畅的互操作性。此外，它包含 Eclipse MicroProfile 6，与 Jakarta EE 10 Core Profile 相一致。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 管理客户端的工件已重命名为更具描述性的名称，并考虑了长期可维护性。我们仍然提供两个独立的 Keycloak 管理客户端，一个使用 Jakarta EE，另一个使用 Java EE 支持。

我们停止发布org.keycloak:keycloak-admin-client-jakarta工件。使用 Jakarta EE 支持的 Keycloak 管理客户端的默认工件是org.keycloak:keycloak-admin-client（从版本 22.0.0 开始）。

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

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

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

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

此更改仅在使用领域本地化消息时才会影响您。

在此版本之前，当使用领域本地化消息时，回退消息的解析在主题之间不一致。有关更多信息，请查看以下问题。

所有主题的实现现已统一。一般来说，与最特定匹配语言标签的消息具有最高优先级。如果同时存在领域本地化消息和主题 18n 消息，则领域本地化消息具有更高的优先级。总结来说，消息的优先级如下（RL = 领域本地化，T = 主题 i18n 文件）：RL <variant> > T <variant> > RL <region> > T <region> > RL <language> > T <language> > RL en > T en。

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

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

您需要将一个名为beans.xml 的空文件添加到打包自定义提供程序的 JAR 文件中。否则，运行时服务器无法识别它们。

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

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

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

可以在同一个命名空间中创建多个 Keycloak CR，并且将由操作员独立管理。为了允许这样做，必须重新创建由操作员的旧版本创建的 StatefulSets。这将在升级操作员时自动发生，并导致少量停机时间。

条件状态字段已从布尔值更改为字符串，以符合标准 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 映射器已更改。令牌声明名称 字段值已从 clientId 更改为 client_id。client_id 声明符合 OAuth2 规范。

clientId 用户会话注释仍然存在。

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

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

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

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

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

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

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

在升级之前，建议在更改之前和之后审查从端点返回的所有指标，并更新其在仪表板和警报中的使用情况。

算法 RSA_SHA1 和 DSA_SHA1 可配置为 SAML 适配器、客户端和身份提供者上的 签名算法，现已弃用。我们建议使用基于 SHA256 或 SHA512 的更安全的替代方案。此外，使用这些算法验证签名 SAML 文档或断言在 Java 17 或更高版本上不起作用。如果您使用此算法，并且使用您的 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 管理 REST 客户端的 RESTEasy 版本更新到下一个主要版本。

Keycloak 随 H2 数据库驱动程序一起用于开发目的。由于它仅用于开发目的，因此绝不应在生产环境中使用。

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

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

Keycloak 运算符生命周期管理器的默认通道已更改为 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 管理 API 将脚本上传到服务器。

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

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

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

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

如果您已明确将主 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，请确保切换到日志记录指南中支持的配置选项，并将您的 jar 从 providers 文件夹中删除。

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

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

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

另请参阅Kubernetes 文档。

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

升级身份验证是一项新功能。此功能提供acr客户端范围，其中包含一个协议映射器，该映射器应该在令牌中添加acr声明。acr声明现在不会像此版本之前那样自动添加，但会随着此客户端范围和协议映射器的使用而添加。

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

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

现有的部署受到以下方式的影响

存在一个向后兼容选项，允许您的应用程序继续使用redirect_uri参数的旧格式。

您可以在启动服务器时启用此参数，方法是输入以下命令

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

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

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

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

一般而言，更新您的领域的步骤如下

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 讨论中发起讨论。

自 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 的以前版本复制配置文件，而是从 Keycloak 16 中提供的默认配置文件开始，并应用相关的更改。

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

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

对于由此带来的不便，我们深表歉意，我们也理解这将使每个人都难以升级到 Keycloak 16，但我们实在找不到其他方法。

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

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

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

在此版本中，我们弃用了 Keycloak 运算符中的某些功能，或将其标记为不支持。这与 Backup CRD 和运算符管理的 Postgres 数据库有关。

以前，在 Keycloak 运算符创建 Keycloak CR 的示例中添加了不受支持的指标扩展。此扩展已删除。

客户端策略功能自 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，则存在一个要求，即您的客户端需要配置 有效的请求 URI。 这可以通过管理控制台的客户端详细信息页面或通过管理 REST API 或客户端注册 API 进行配置。 有效的请求 URI 需要包含允许特定客户端使用的请求 URI 值列表。 这样做是为了避免 SSRF 攻击。 可以类似地使用通配符或相对路径，例如 有效的重定向 URI 选项，但是出于安全目的，我们通常建议使用尽可能具体的值。

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

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

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

Keycloak 登录主题组件已升级到 PatternFly 4。 旧的 PatternFly 3 与新的同时运行，因此可以保留 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 提供程序配置为 导入用户 OFF 时，即使更改了某些非 LDAP 映射属性，也可以更新用户。 这种情况导致了令人困惑的行为，属性似乎已更新，但实际上并没有更新。 在当前版本中，如果更改了任何非 LDAP 映射属性，则根本不允许执行更新。

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

UserModel 中的 username、email、firstName 和 lastName 字段将迁移到自定义属性，作为在即将发布的版本中将更复杂的用户信息添加到 Keycloak 的准备工作。 如果数据库包含具有该确切名称的自定义属性的用户，则需要在升级之前迁移自定义属性。 此迁移不会自动进行。 否则，它们将不再从数据库中读取，并且可能会被删除。 这种情况意味着 username 现在也可以通过 UserModel.getFirstAttribute(UserModel.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，两者同时可用。建议尽快更新应用程序以使用本机承诺 API（then 和 catch），因为遗留 API（success 和 error）将在某个时刻被移除。

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

每个 realm 中只能存在一个具有相同名称的顶级组。在升级之前，应审查并删除重复项。升级中的错误包含消息 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 声明，并将 realm 角色设置为 groups 声明。

我们在 OIDC 身份提供者配置中添加了一个名为 Accepts prompt=none forward from client 的新开关，用于识别能够处理包含 prompt=none 查询参数的转发请求的 IDP。

到目前为止，当接收到包含 prompt=none 的身份验证请求时，如果用户未在 realm 中认证，则 realm 会返回 login_required 错误，而不会检查用户是否已由 IDP 认证。从现在开始，如果可以为身份验证请求确定一个默认 IDP（通过使用 kc_idp_hint 查询参数或为 realm 设置默认 IDP），并且如果已为 IDP 启用了 Accepts prompt=none forward from client 开关，则身份验证请求将被转发到 IDP 以检查用户是否已在那里认证。

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

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

Keycloak 版本 4.8.1 及之前版本的 Google 身份提供者实现依赖于 Google+ API 端点进行授权并获取用户资料。从 2019 年 3 月起，Google 将不再支持 Google+ API，转而采用新的 Google 登录身份验证系统。Keycloak 身份提供者已更新为使用新的端点，因此如果您正在使用此集成，请确保您升级到 Keycloak 4.8.2 或更高版本。

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

您可能需要调整 Google+ 用户信息端点提供的非标准声明的自定义映射器，这些声明在 Google 登录 API 中以不同的名称提供。有关可用声明的最新信息，请参阅 Google 文档。

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

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

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

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

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

要将本机 JavaScript 承诺与 JavaScript 适配器一起使用，现在需要在 init 选项中将 promiseType 设置为 native。

过去，如果本机承诺可用，则会返回一个包装器，该包装器提供传统的 Keycloak 承诺和本机承诺。这会导致问题，因为错误处理程序并不总是先于本机错误事件设置，从而导致 Uncaught (in promise) 错误。

Keycloak 版本 4.5.0 及之前版本的 Microsoft 身份提供者实现依赖于 Live SDK 端点进行授权并获取用户资料。从 2018 年 11 月起，Microsoft 将不再支持 Live SDK API，转而采用新的 Microsoft Graph API。Keycloak 身份提供者已更新为使用新的端点，因此如果您正在使用此集成，请确保您升级到 Keycloak 4.6.0 或更高版本。

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

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

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

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

我们添加了对客户端范围的支持，这需要在迁移过程中进行一些注意。

我们添加了对 UMA 2.0 的支持。此版本的 UMA 规范对服务器如何获取权限引入了一些重要更改。

以下是 UMA 2.0 支持引入的主要更改。有关详细信息，请参阅 授权服务指南。

OpenID Connect 会话管理规范要求 session_state 参数存在于 OpenID Connect 身份验证响应中。

在过去版本中，我们没有此参数，但现在 Keycloak 根据规范要求默认情况下添加了此参数。

但是，一些 OpenID Connect/OAuth2 适配器，尤其是旧版本的 Keycloak 适配器，可能会遇到此新参数的问题。

例如，在成功认证到客户端应用程序后，该参数将始终存在于浏览器 URL 中。在这些情况下，禁用将 session_state 参数添加到身份验证响应可能很有用。这可以通过 Keycloak 管理控制台中的特定客户端完成，在客户端详细信息中的 OpenID Connect Compatibility Modes 部分中，如 与旧适配器的兼容性 中所述。存在专用的 Exclude Session State From Authentication Response 开关，可以将其打开以防止将 session_state 参数添加到身份验证响应中。

我们添加了两种新的密码哈希算法 (pbkdf2-sha256 和 pbkdf2-sha512)。新的领域将使用 pbkdf2-sha256 哈希算法，哈希迭代次数为 27500。由于 pbkdf2-sha256 比 pbkdf2 速度稍快，因此迭代次数从 20000 增加到 27500。

如果密码策略包含哈希算法的默认值（未指定）和迭代次数（20000），则现有领域将进行升级。如果您更改了哈希迭代次数，则需要手动更改为 pbkdf2-sha256，如果您想要使用更安全的哈希算法。

OpenID Connect 规范要求在初始授权请求中使用具有 openid 值的 scope 参数。因此，在 Keycloak 2.1.0 中，我们更改了适配器，以便在重定向 URI 到 Keycloak 中使用 scope=openid。现在，我们也更改了服务器部分，ID 令牌将仅在实际使用 scope=openid 时发送到应用程序。如果未使用，则 ID 令牌将被跳过，并且仅访问令牌和刷新令牌将发送到应用程序。这也允许您有意省略 ID 令牌的生成 - 例如为了节省空间或提高性能。

直接授权（OAuth2 资源所有者密码凭据授权）和服务帐户登录（OAuth2 客户端凭据授权）现在默认情况下也不使用 ID 令牌。您需要显式添加 scope=openid 参数才能包含 ID 令牌。

我们正在努力支持多个数据中心。作为第一步，我们引入了身份验证会话和操作令牌。身份验证会话取代了先前版本中使用的客户端会话。操作令牌目前主要用于身份验证器或 requiredActionProvider 需要向用户发送电子邮件并要求用户点击电子邮件中的链接的场景。

以下是与之相关的具体更改，可能会影响您的迁移。

第一个相关的更改是在 standalone.xml 或 standalone-ha.xml 中引入新的 Infinispan 缓存 authenticationSessions 和 actionTokens。如果您使用我们的迁移 CLI，则无需过多关注，因为您的 standalone(-ha).xml 文件将自动迁移。

第二个更改是身份验证 SPI 方法中某些签名的更改。如果您使用自定义 Authenticator 或 RequiredActionProvider，这可能会影响您。AuthenticationFlowContext 和 RequiredActionContext 类现在允许检索身份验证会话，而不是客户端会话。

我们还添加了一些对粘性会话的初步支持。如果您不希望受到影响并希望获得更好的性能，您可能希望更改您的负载均衡器/代理服务器并对其进行配置。路由已添加到新的 AUTH_SESSION_ID cookie 中。更多信息请参阅集群文档。

另一个更改是 token.getClientSession() 被删除了。这可能会影响您，例如，如果您使用的是客户端发起的身份代理链接功能。

ScriptBasedAuthenticator 将绑定名称从 clientSession 更改为 authenticationSession，因此如果您使用此身份验证器，则需要更新您的脚本。

最后，我们在管理控制台中添加了一些新的超时设置。这使您可以例如为管理员和用户自己触发的电子邮件操作指定不同的超时设置。

如果您从 2.2.0 或更早版本迁移，并且您使用了脱机令牌，那么您的脱机令牌在令牌标头中没有 KID。我们在 2.3.0 中添加了 KID 到令牌标头，并支持多个领域密钥，因此 Keycloak 可以根据令牌 KID 找到正确的密钥。

对于没有 KID 的脱机令牌，Keycloak 2.5.1 将始终使用活动领域密钥来查找用于令牌验证的正确密钥。换句话说，旧脱机令牌的迁移将起作用。因此，例如，您的用户在 1.9.8 中请求了脱机令牌，然后您从 1.9.8 迁移到 2.5.1，然后您的用户仍然能够在 2.5.1 版本中刷新他的旧脱机令牌。

但存在一个限制。一旦您更改了活动领域密钥，用户将无法再刷新旧脱机令牌。因此，在所有使用脱机令牌的用户刷新了他们的令牌之前，您不应更改活动领域密钥。显然，新刷新的令牌将在标头中包含 KID，因此在所有用户交换了他们的旧脱机令牌后，您可以自由地更改活动领域密钥。

在 standalone.xml 或 standalone-ha.xml 配置文件中，infinispan 子系统中定义的 realms 缓存现在默认情况下具有 10000 条记录的逐出。这与 users 缓存的默认设置相同。

此外，authorization 缓存现在默认情况下没有任何逐出。

keycloak-server-spi 模块已拆分为 keycloak-server-spi 和 keycloak-server-spi-private。keycloak-server-spi 中的 API 在次要版本之间不会更改，但我们保留权利，并且可能会在次要版本之间更改 keycloak-server-spi-private 中的 API。

SAML 断言和文档中的密钥现在使用 RSA-OAEP 加密方案进行加密。如果您想使用加密的断言，请确保服务提供商理解这种加密方案。在极少数情况下，如果 SP 无法处理新方案，Keycloak 可以使用旧的 RSA-v1.5 加密方案，方法是在使用系统属性 keycloak.saml.key_trans.rsa_v1.5 设置为 true 的情况下启动。

即使您在集群中使用 Keycloak，在 standalone-ha.xml 中的 infinispan 子系统中定义的 realms 和 users 缓存现在始终是本地缓存。存在一个单独的缓存 work，它处理在集群节点之间发送失效消息，并通知整个集群哪些底层 realms 和 users 缓存中的记录应该失效。

所有支持分页的管理员 REST API 端点现在都有一个默认的最大结果数，设置为 100。如果您想返回超过 100 个条目，则需要使用 ?max=<RESULTS> 显式指定。

在 2.3.0 版本中，我们添加了对公钥轮换的支持。当管理员在 Keycloak 管理控制台中轮换领域密钥时，客户端适配器将能够识别它并自动从 Keycloak 下载新的公钥。但是，仅当您的适配器中没有使用 realm-public-key 选项以及硬编码的公钥时，才会执行此新的密钥自动下载。因此，我们不再建议在适配器配置中使用 realm-public-key 选项。

请注意，此选项仍然受支持，但仅当您确实想要在适配器配置中拥有硬编码的公钥并且永远不会从 Keycloak 下载公钥时，它可能很有用。从理论上讲，这样做的一个原因是在适配器和 Keycloak 之间存在不受信任的网络时，为了避免中间人攻击，但在这种情况下，使用 HTTPS 更好，它将保护适配器和 Keycloak 之间的所有请求。

在此版本中，我们向 infinispan 子系统添加了新的缓存 keys，它在 standalone.xml 或 standalone-ha.xml 配置文件中定义。它还定义了一些逐出和过期设置。此缓存用于在内部缓存服务器信任的实体（使用签名 JWT 进行身份验证的身份提供者或客户端）的外部公钥。

JPA 和 Mongo 的 databaseSchema 属性现在已弃用，并被 initializeEmpty 和 migrationStrategy 替换。initializeEmpty 可以设置为 true 或 false，并控制是否应初始化一个空数据库。migrationStrategy 可以设置为 update、validate 和 manual。manual 仅支持关系数据库，并将写入一个包含数据库模式所需更改的 SQL 文件。请注意，对于 Oracle 数据库，创建的 SQL 文件包含 Oracle SQL 客户端理解的 SET DEFINE OFF 命令。如果脚本被任何其他客户端使用，请使用您选择的工具的等效命令替换这些行，以禁用变量扩展，或者如果此功能不适用，则完全将其删除。

以下场景会受到影响

身份提供者不再提供将其设置为默认身份验证提供者的选项。请改为转到“身份验证”，选择浏览器流程并配置身份提供者重定向器。它提供了一个设置默认身份提供者的选项。

从 1.0.0.Final 升级不再受支持。要升级到此版本，请先升级到 1.9.8.Final，然后再升级到 2.0.0。

新域的默认密码哈希间隔已从 1 增加到 20K。此更改将影响用户身份验证时的性能。例如，使用旧的默认值 (1) 对密码进行哈希处理不到 1 毫秒，但使用新的默认值 (20K) 进行相同的操作可能需要 50-100 毫秒。

用于将管理员用户添加到 Keycloak 的脚本已重命名为add-user-keycloak。

我们已删除选项 auth-server-url-for-backend-requests，因为在某些情况下使用它会导致问题。更详细地说，可能从两个不同的上下文（内部和外部）访问 Keycloak 服务器，这会导致令牌验证等问题。

如果您仍然希望使用此选项提供的网络优化（避免应用程序通过负载均衡器发送回通道请求，而是直接发送到本地 Keycloak 服务器），您可能需要在主机配置（DNS）级别进行处理。

我们已将主题和提供程序目录从standalone/configuration/themes和standalone/configuration/providers分别移动到themes和providers。如果您已添加自定义主题和提供程序，则需要将它们移动到新位置。您还需要更新keycloak-server.json，因为它已更改。

以前，如果您已将我们的 SAML 或 OIDC Keycloak 子系统适配器安装到 WildFly 或 JBoss EAP 中，我们将自动将 Keycloak 客户端 jar 包含到每个应用程序中，无论您是否正在使用 Keycloak。现在，这些库仅在为该适配器（通过子系统或 web.xml 中的 auth-method）打开 Keycloak 身份验证时添加到您的部署中。

客户端注册服务端点已从{realm-name}/clients移动到{realm-name}/clients-registrations。

在 OpenID Connect 身份验证响应中，我们以前将会话状态返回为session-state，这与规范不一致，现已重命名为session_state。

在 1.2 中，我们弃用了一些与 OpenID Connect 规范不一致的端点，这些端点现已删除。这也适用于在 1.8 中被新的 introspect 端点取代的 validate 令牌端点。

template.ftl 中的反馈已移动，格式略有更改。

我们的大多数模块和源代码已合并到两个 Maven 模块中：keycloak-server-spi 和 keycloak-services。SPI 接口在 server-spi 中，实现位于 keycloak-services 中。所有依赖 JPA 的模块已合并到 keycloak-model-jpa 下。同样，mongo 和 Infinispan 也分别在 keycloak-model-mongo 和 keycloak-model-infinispan 模块下。

为了消除安全漏洞，对于支持它的平台（Tomcat 8、Undertow/WildFly），Keycloak OIDC 和 SAML 适配器将在登录后更改会话 ID。您可以关闭此行为检查适配器配置开关。

Keycloak SAML SP 客户端适配器现在需要一个特定端点/saml，以便在您的 IDP 中注册。

在以前的版本中，我们附带了一个具有默认密码的默认管理员用户，该用户现已删除。如果您要进行 1.8 的全新安装，则需要在第一步中创建一个管理员用户。

为了更符合 OAuth2 规范，我们添加了一个用于令牌自省的新端点。新端点可以在/realms/{realm-name}/protocols/openid-connect/token/introspect访问，它完全基于RFC-7662。

/realms/{realm-name}/protocols/openid-connect/validate端点现已弃用，我们强烈建议您尽快迁移到新的自省端点。进行此更改的原因是 RFC-7662 提供了一个更标准、更安全的自省端点。

现在可以从 OpenID Connect 提供者的配置/realms/{realm-name}/.well-known/openid-configuration获取新的令牌自省 URL。您将在响应中找到一个名为token_introspection_endpoint的声明。只有机密客户端被允许调用新端点，这些客户端通常充当资源服务器，并寻找令牌元数据以执行本地授权检查。

为了更符合 OpenID Connect 规范，我们在管理控制台的“客户端设置”页面中添加了标志，您可以在其中启用/禁用各种 OpenID Connect/OAuth2 流程（标准流程、隐式流程、直接访问授予、服务帐户）。作为此的一部分，我们默认情况下对新客户端禁用了直接访问授予（对应于 OAuth2 的资源所有者密码凭据授予）。

从先前版本迁移的客户端仅在它们具有仅直接授予标志时才启用直接访问授予。仅直接授予标志已删除，因为如果您启用直接访问授予并禁用标准+隐式流程，您将实现相同的效果。

我们还向每个域添加了内置客户端admin-cli。此客户端启用了直接访问授予。因此，如果您使用的是 Admin REST API 或 Keycloak admin-client，您应该更新您的配置以使用admin-cli代替security-admin-console，因为后者默认情况下不再启用直接访问授予。

在此版本中，我们添加了首次代理登录，它允许您指定在通过身份提供者（或社交提供者）登录新用户时应执行的操作，但尚未链接到社交帐户的 Keycloak 用户。作为此工作的一部分，我们在身份提供者中添加了选项首次登录流程，您可以在其中指定流程，然后可以在管理控制台的“身份验证”选项卡下配置此流程。

我们还从身份提供者设置中删除了选项在首次登录时更新个人资料，并将其移动到查看个人资料身份验证器的配置中。因此，一旦您指定了应为您的身份提供者使用哪个流程（默认情况下是首次代理登录流程），您就可以转到“身份验证”选项卡，选择该流程，然后在查看个人资料身份验证器下配置该选项。

web.xml 中的 form-error-page 将不再适用于客户端适配器身份验证错误。您必须为各种 HTTP 错误代码定义错误页面。如果您想捕获和处理适配器错误条件，请参阅文档以了解更多详细信息。

接口本身和方法签名没有改变。但是，行为存在一些变化。我们在本版本中添加了首次代理登录流程，并且现在在首次代理登录流程完成后调用IdentityProviderMapper.importNewUser方法。因此，如果您希望在“查看个人资料”页面中使用任何属性，您需要使用preprocessFederatedIdentity方法，而不是importNewUser。您可以通过调用BrokeredIdentityContext.setUserAttribute来设置任何属性，并且该属性将在“查看个人资料”页面上可用。

旧版本的 Keycloak 允许多次重复使用刷新令牌。Keycloak 仍然允许这样做，但也提供了一个选项撤销刷新令牌来禁止它。该选项位于管理控制台中的令牌设置下。当刷新令牌用于获取新的访问令牌时，还会包含新的刷新令牌。启用该选项后，下次刷新访问令牌时应使用此新的刷新令牌。无法多次重复使用旧的刷新令牌。

我们进行了一些重组并重命名了一些包。这主要是关于重命名 util 类内部包。您在应用程序中使用的最重要的类（例如 AccessToken 或 KeycloakSecurityContext）以及 SPI 仍然没有变化。但是，您可能会受到轻微影响，需要更新类的导入。例如，如果您使用多租户和 KeycloakConfigResolver，您将受到影响，因为例如 HttpFacade 类已移动到不同的包中 - 现在是org.keycloak.adapters.spi.HttpFacade。

我们在本版本中添加了对离线令牌的支持，这意味着我们现在将“离线”用户会话持久化到数据库中。如果您未使用离线令牌，则不会为您持久化任何内容，因此您无需关心更多数据库写入带来的性能下降。但是，在所有情况下，您都需要更新standalone/configuration/keycloak-server.json并添加userSessionPersister，如下所示：

如果您希望会话持久化到 Mongo 而不是经典的 RDBMS，请使用提供程序mongo。

Infinispan 现在是默认的也是唯一的域和用户缓存提供程序。在非集群模式下，将使用本地 Infinispan 缓存。我们还删除了自定义内存缓存和无缓存提供程序。如果您在 keycloak-server.json 中将 realmCache 或 userCache 设置为 mem 或 none，请删除这些设置。由于 Infinispan 是唯一的提供程序，因此 realmCache 和 userCache 对象不再需要，可以删除。

Infinispan 现在是默认的也是唯一的用户会话提供者。在非集群模式下，将使用本地 Infinispan 缓存。我们还删除了 JPA 和 Mongo 用户会话提供者。如果您在 keycloak-server.json 中将 userSession 设置为 mem、jpa 或 mongo，请将其删除。由于 Infinispan 是唯一的提供者，因此 userSession 对象不再需要，可以将其删除。

对于想要提高用户会话持久性的任何人，可以通过将用户会话缓存配置为拥有多个所有者或使用复制缓存来实现。还可以将 Infinispan 配置为持久化缓存，但这样做会影响性能。

在默认主题中，我们现在已从注册页面和帐户管理中删除了联系信息。管理控制台现在列出了所有用户属性，而不仅仅是与联系相关的属性。管理控制台还具有向用户添加/删除属性的功能。如果您想添加联系信息，请参阅示例中包含的地址主题。

过去，直接授权 API（或资源所有者密码凭据）默认情况下是禁用的，并且存在在 realm 上启用它的选项。直接授权 API 现在始终启用，用于 realm 的启用/禁用选项已删除。

数据库中又有一些更改。请务必在升级之前备份您的数据库。

UserFederationProvider 接口中有一些细微的更改。您可能需要在升级到较新版本时同步您的实现并升级一些方法，这些方法已更改签名。更改非常小，但需要为了提高联合的性能。

继上一个版本中进行的发布更改之后，Keycloak 的独立下载现在基于 WildFly 9.0.0.Final。这也影响了覆盖层，覆盖层只能部署到 WildFly 9.0.0.Final 或 JBoss EAP 6.4.0.GA。服务器不再支持 WildFly 8.2.0.Final。

现在有 3 个独立的适配器下载文件，分别用于 WildFly、JBoss EAP 和 JBoss AS7

确保您获取了正确的适配器。

您还需要更新 standalone.xml，因为扩展模块和子系统定义已更改。有关详细信息，请参阅 保护应用程序指南。

Keycloak 现在提供 3 个下载文件：独立版、覆盖层版和演示版。独立版适用于生产环境和非 JEE 开发人员。覆盖层版旨在将 Keycloak 添加到现有的 WildFly 8.2 或 EAP 6.4 安装中，主要用于开发。最后，我们还有一个演示（或开发）版，面向想要开始使用 Keycloak 的开发人员。此版本包含 WildFly 服务器，其中包括 Keycloak 服务器和适配器。它还包含所有文档和示例。

此版本再次包含一些数据库更改。最重要的是应用程序和 OAuth 客户端合并。请务必在升级之前备份您的数据库。

应用程序和 OAuth 客户端现在已合并到 Clients 中。管理控制台的 UI 和数据库也进行了更新。您的数据库数据应自动更新。以前设置的应用程序将转换为具有关闭的 同意需要 开关的客户端，而 OAuth 客户端将转换为具有打开此开关的客户端。

此版本包含一些数据库更改。请务必在升级之前备份您的数据库。

访问令牌和 ID 令牌中 iss 声明的值已从 realm name 更改为 realm url。这是 OpenID Connect 规范要求的。如果您正在使用我们的适配器，则无需进行任何更改，除非您一直在使用仅限承载者而不指定 auth-server-url，则现在必须添加它。如果您正在使用其他库（或 RSATokenVerifier），则在验证 iss 时需要进行相应的更改。

为了符合 OpenID Connect 规范，身份验证和令牌端点已更改为具有单个身份验证端点和单个令牌端点。根据规范，response_type 和 grant_type 参数用于选择所需的流程。旧端点（/realms/{realm-name}/protocols/openid-connect/login、/realms/{realm-name}/protocols/openid-connect/grants/access、/realms/{realm-name}/protocols/openid-connect/refresh、/realms/{realm-name}/protocols/openid-connect/access/codes）现在已弃用，将在未来版本中删除。

主题的布局已更改。目录层次结构过去是 type/name，现在已更改为 name/type。例如，名为 sunrise 的登录主题过去部署到 standalone/configuration/themes/login/sunrise，现在已移动到 standalone/configuration/themes/sunrise/login。进行此更改是为了便于将同一主题的不同类型分组到一个文件夹中。

如果您过去将主题作为 JAR 部署，则需要创建自定义主题加载程序，这需要 Java 代码。现在已简化为仅需要一个纯文本文件 (META-INF/keycloak-themes.json) 来描述 JAR 中包含的主题。

以前，管理控制台中存在一个专门的 Claims 选项卡，用于应用程序和 OAuth 客户端。它用于配置哪些属性应进入特定应用程序/客户端的访问令牌。它已删除，并由更灵活的协议映射器取代。

您无需关心从先前版本迁移数据库。我们对 RDBMS 和 Mongo 都进行了迁移脚本，这些脚本应确保为特定应用程序/客户端配置的声明将转换为相应的协议映射器（尽管在迁移到较新版本之前备份数据库仍然更安全）。对于从先前版本导出的 JSON 表示形式，也是如此。

我们重构了社交提供者 SPI，并将其替换为更灵活的身份代理 SPI。管理控制台中的 Social 选项卡已重命名为 Identity Provider 选项卡。

同样，您无需关心从先前版本迁移数据库，就像 Claims/协议映射器一样。社交提供者配置和您用户对“社交链接”的配置都将转换为相应身份提供者。

您唯一需要执行的操作是更改特定第三方社交提供者的管理控制台中允许的 Redirect URI。您可以先进入 Keycloak 管理控制台，从配置身份提供者的页面复制 Redirect URI。然后，您可以简单地将此作为允许的 Redirect URI 粘贴到第三方提供者的管理控制台中（例如，Facebook 管理控制台）。