发行说明

在此版本中，我们添加了对标准令牌交换的支持！令牌交换功能已预览很长时间，因此我们很高兴最终支持标准令牌交换。目前，这仅限于将内部令牌交换为符合 令牌交换规范 的内部令牌。它尚未涵盖与身份代理或主体模拟相关的用例。我们希望在后续版本中支持更多令牌交换用例。

有关更多详细信息，请参阅 标准令牌交换。

有关如何从先前 Keycloak 版本中使用的旧版令牌交换升级的信息，请参阅 升级指南。

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

有关更多详细信息，请参阅 细粒度管理员权限。

有关迁移的更多信息，请参阅 升级指南。

除了有用的指标名称列表 可观测性指南类别 外，现在还包含有关如何在 Grafana 中显示这些指标的指南。该指南包含两个仪表板。

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

这加强了默认安全设置，并最大限度地减少了新设置的配置步骤。

有关更多信息，请查看分布式缓存指南中的 保护传输堆栈。

当使用优化或自定义镜像时，如果旧镜像和新镜像包含相同版本的 Keycloak，则 Keycloak Operator 现在可以对新镜像执行滚动更新。当您想要推出例如更新的主题或提供程序而无需停机时，这非常有用。

要在 Operator 中使用此功能，请启用 Auto 更新策略，Keycloak Operator 将在镜像更改时短暂启动旧镜像和新镜像，以确定是否可以进行无需停机的滚动更新。有关此功能的更多详细信息，请阅读 Keycloak Operator 高级配置指南中的 管理滚动更新 部分。

用于确定是否可以进行滚动更新的检查也可在 Keycloak 命令行中使用，因此您可以在部署管道中使用它们。继续阅读 更新兼容性工具 指南，以获取有关命令行上可用功能的更多信息。

Admin Events API 现在除了之前的 yyyy-MM-dd 格式外，还支持基于 Epoc 时间戳过滤事件。这为检索事件窗口提供了更细粒度的控制。

还添加了 direction 查询参数，允许控制返回项目的顺序，如 asc 或 desc。过去，事件总是以 desc 顺序返回（最近的事件在前）。

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

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

有关更多详细信息，请参阅 日志记录指南。

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

查看 所有提供程序配置 指南中的 crl-storage 部分，了解新缓存提供程序的选项。

Keycloak Operator 现在默认创建 NetworkPolicy，以限制对用于 Keycloak 分布式缓存的内部端口的流量。

这加强了默认安全设置，并最大限度地减少了新设置的配置步骤。

您可以使用 Kubernetes NetworkPolicies 规则语法进一步限制对管理和 HTTP 端点的访问。

在 Operator 高级配置 中阅读有关此内容的更多信息。

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

有关更多信息，请查看 配置管理接口 指南。

引入了基于请求的范围、ACR（身份验证上下文类引用）和其他条件动态选择身份验证流程的功能。这可以使用 客户端策略 通过将新的 AuthenticationFlowSelectorExecutor 与诸如新的 ACRCondition 之类的条件相结合来实现。有关更多详细信息，请参阅 服务器管理指南。

最新版本的 OpenID Connect Core Specification 收紧了客户端身份验证方法 private_key_jwt 和 client_secret_jwt 的 JWT 客户端断言中的受众验证规则。Keycloak 现在默认强制执行用于客户端身份验证的 JWT 令牌中存在单个受众。

有关 JWT 客户端身份验证 Keycloak 版本中更改的受众验证的信息，请参阅 升级指南。

非常感谢 Thomas Darimont 的贡献。

到目前为止，使用 User API 查询用户凭据不会返回用户存储提供程序管理的凭据，因此会阻止获取与联合凭据关联的其他元数据，例如凭据上次更新的时间。

在此版本中，我们向 org.keycloak.credential.CredentialInputUpdater 接口添加了一个新方法 getCredentials(RealmModel, UserModel)，以便用户存储提供程序可以返回它们为 realm 中特定用户管理的凭据。通过这样做，用户存储提供程序可以指示凭据是否链接到它，并提供其他元数据，以便在通过管理控制台管理用户时可以显示其他信息。

对于 LDAP，现在应该可以根据标准 pwdChangedTime 属性或（如果使用 Microsoft AD）根据 pwdLastSet 属性查看密码上次更新的时间。

为了检查凭据是本地的（由 Keycloak 管理）还是联合的，您可以检查 CredentialRepresentation 和 CredentialModel 类型都可用的 federationLink 属性。如果设置了，则 federationLink 属性将保存与给定用户存储提供程序关联的组件模型的 UUID。

Keycloak 出站链接：为 realm 配置电子邮件[SMTP 邮件配置]现在支持令牌身份验证 (XOAUTH2)。许多服务提供商（Microsoft、Google）正在转向 SMTP OAuth 身份验证，并结束对基本身份验证的支持。令牌是使用客户端凭据授权收集的。

非常感谢 Sebastian Rose 的贡献。

已添加新的管理设置：客户端 → 高级 → 细粒度 OpenID Connect 配置 → 使用 “at+jwt” 作为访问令牌头类型

如果启用，访问令牌将获得符合 rfc9068#section-2.1 规范的 at+jwt 头类型。否则，访问令牌头类型将为 JWT。

此设置默认关闭。

非常感谢 Laurids Møller Jepsen 的贡献。

OpenID 可验证凭据颁发 (OID4VCI) 在 Keycloak 中仍然是一个实验性功能，但它获得了进一步的改进，特别是 文档，其中包含如何尝试此功能的步骤。

您可以在 Keycloak OAuth SIG 中找到重要的开发和讨论。欢迎 Keycloak 社区的任何人加入并提供反馈。

非常感谢 OAuth SIG 小组的所有成员参与此功能的开发和讨论。特别感谢 Awambeng Rodrick 和 Ingrid Kamga。

在 26.1.1 版本中，reset-credential-email（发送重置邮件）身份验证器添加了一个新的配置选项，以允许更改重置凭据流程后的默认行为。现在，force-login（重置后强制登录）选项添加了第三个配置值 only-federated，这意味着强制登录对于联合用户为 true，对于内部数据库用户为 false。新行为现在是默认行为。这样，所有由用户联合身份验证提供程序管理的用户（其实现可能与 Keycloak 的集成度不高）在重置凭据流程后都被强制再次登录，以避免任何问题。行为的这种变化是由于默认安全策略。

有关更多信息，请参阅“启用忘记密码”。

X.509 身份验证器有一个新选项 x509-cert-auth-crl-abort-if-non-updated（管理控制台中为“CRL 过期时中止”），用于在配置 CRL 以验证证书且 CRL 未在“下次更新”字段中指定的时间内更新时中止登录。新选项在管理控制台中默认为 true。有关 CRL “下次更新”字段的更多详细信息，请参阅 RFC5280，第 5.1.2.5 节。

值 false 被保留以与之前的行为兼容。请注意，现有配置将没有新选项，并且行为将如同此选项设置为 false，但管理控制台在编辑时将添加默认值 true。

reset-credential-email（发送重置邮件）是重置凭据流程（忘记密码功能）中使用的身份验证器，用于向用户发送包含重置凭据令牌链接的电子邮件。此身份验证器现在有一个新选项 force-login（重置后强制登录）。当此选项设置为 true 时，身份验证器将终止会话并强制执行新的登录。

有关此新选项的更多详细信息，请参阅“启用忘记密码”。

Keycloak 现在默认使用其数据库来发现同一集群的其他节点，这消除了额外的网络相关配置的需要，特别是对于云提供商而言。这也是一个开箱即用的默认设置，可以在云环境中使用。

以前版本的 Keycloak 默认使用 UDP 多播来发现其他节点以形成集群并同步 Keycloak 的复制缓存。这需要多播可用并正确配置，但在云环境中通常不是这种情况。

从这个版本开始，默认设置更改为 jdbc-ping 配置，该配置使用 Keycloak 的数据库来发现其他节点。由于这消除了对多播网络功能和 UDP 的需求，并且不再使用动态端口进行基于 TCP 的故障检测，因此对于使用先前默认设置的环境来说，这是一个简化且即插即用的替代方案。要启用以前的行为，请选择现在已弃用的传输堆栈 udp。

Keycloak Operator 将继续配置 kubernetes 作为传输堆栈。

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

从这个版本开始，当在 OpenJDK 21 上运行时，对于至少有 2 个 CPU 核心可用的环境，Keycloak 会自动在嵌入式 Infinispan 和 JGroups 中启用虚拟线程池支持。这消除了配置 JGroups 线程池的需要、将 JGroups 线程池与 HTTP 工作线程池对齐的需要，并减少了整体内存占用。

在上一个版本中，OpenTelemetry Tracing 功能是预览版，现在已完全支持。这意味着默认情况下启用 opentelemetry 功能。

Keycloak 的跟踪功能进行了多项改进，例如

有关更多信息，请参阅“启用跟踪”指南。

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

从这个版本开始，当未设置 --cache-config-file 时，默认的 Infinispan XML 配置文件是 conf/cache-ispn.xml，因为这既是预期行为，也是当前和先前版本的文档所暗示的行为。

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

有关更多详细信息，请参阅“日志记录”指南。

OpenID 可验证凭据颁发 (OID4VCI) 在 Keycloak 中仍然是一个实验性功能，但在此版本中得到了很大的改进。此功能受益于对现有配置的大量优化，并使该功能更具动态性和可定制性。

您可以在 Keycloak OAuth SIG 中找到重要的开发和讨论。欢迎 Keycloak 社区的任何人加入。

非常感谢 OAuth SIG 小组的所有成员参与此功能的开发和讨论。特别感谢 Francis Pouatcha、Ingrid Kamga、Pascal Knüppel、Thomas Darimont、Ogen Bertrand、Awambeng Rodrick 和 Takashi Norimatsu。

“最小 ACR 值”选项已作为配置选项添加到领域 OIDC 客户端。此添加是与步进式身份验证相关的增强功能，它使在登录到特定客户端时可以强制执行最小 ACR 级别。

非常感谢 Simon Levermann 的贡献。

现在支持 “启动用户注册”标准，该标准允许 OIDC 客户端使用参数 prompt=create 发起登录请求，以通知 Keycloak 应注册新用户而不是验证现有用户身份。“启动用户注册”在 Keycloak 中已经通过使用专用端点 /realms/<realm>/protocol/openid-connect/registrations 得到支持。但是，此端点现在已被弃用，取而代之的是标准方法，因为它是一个 Keycloak 特有的专有解决方案。

非常感谢 Thomas Darimont 的贡献。

EC-DSA 和 Ed-DSA 密钥提供程序存在一个新选项“生成证书”。当领域管理员创建生成的密钥时，可以为此密钥生成证书。证书信息在管理控制台和此密钥的 JWK 表示中可用，JWK 表示可以从带有领域密钥的 JWKS 端点获得。

非常感谢 Pascal Knüppel 的贡献。

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

非常感谢 Takashi Norimatsu 的贡献。

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

非常感谢 Manuel Schallar 和 Patrick Weiner 的贡献。

为了提高 Kubernetes 部署的安全性，可以在 Keycloak CR 中指定 网络策略。Keycloak Operator 接受入口规则，这些规则定义了允许流量从何处进入，并自动创建必要的网络策略。

如果您正在使用 Microsoft AD 并通过管理界面创建用户，则默认情况下用户将被创建为已启用。

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

“条件 - 子流已执行”和“条件 - 客户端作用域”是 Keycloak 中的新条件身份验证器。“条件 - 子流已执行”条件检查先前的子流在身份验证流程执行期间是否成功执行（或未执行）。“条件 - 客户端作用域”条件检查配置的客户端作用域是否作为请求身份验证的客户端的客户端作用域存在。有关更多详细信息，请参阅“条件流中的条件”。

在为 Keycloak 开发扩展时，开发人员现在可以通过在 ProviderFactory 接口中实现 dependsOn() 方法来指定提供程序工厂类之间的依赖关系。有关详细描述，请参阅 Javadoc。

我们现在为所有 keycloak 主题启用了深色模式支持。此功能以前存在于管理控制台、帐户控制台和登录页面中，现在也已在欢迎页面上提供。如果用户通过操作系统设置（例如，浅色或深色模式）或用户代理设置指示其偏好，则主题将自动遵循这些偏好。

如果您正在使用扩展任何 keycloak 主题的自定义主题，并且尚未准备好支持深色模式，或者存在阻止您实现深色模式的样式冲突，则可以通过将以下属性添加到您的主题来禁用支持

或者，您可以通过关闭领域设置中“主题”选项卡下的“深色模式”设置，在每个领域的基础上禁用对内置 Keycloak 主题的深色模式支持。

现在有一个新的指标可用，用于计算 Keycloak 执行了多少次密码验证。这使您可以更好地评估 CPU 资源的使用位置，并可以用于您的容量规划计算。

有关更多详细信息，请参阅“Keycloak 指标”和“CPU 和内存资源容量规划概念”。

在以前的版本中，在管理控制台中单击“注销所有活动会话”仅导致删除常规会话。脱机会话仍然会显示，尽管实际上已失效。

这种情况已更改。现在，注销所有活动会话时，所有会话（常规和脱机）都将被删除。

从这个版本开始，Keycloak JavaScript 适配器和 Keycloak Node.js 适配器将具有独立于 Keycloak 服务器发布周期的发布周期。26.1.0 版本可能是这些适配器与 Keycloak 服务器一起发布的最后一个版本，但从现在开始，这些适配器可能会在与 Keycloak 服务器不同的时间发布。

Keycloak 快速入门现在使用 main 作为基本分支。以前使用的 latest 分支已删除。main 分支依赖于 Keycloak 服务器、Keycloak 客户端库和适配器的最新发布版本。因此，对快速入门的贡献会立即对快速入门用户可见，而无需等待下一个 Keycloak 服务器版本。

KEYCLOAK_SESSION cookie 的格式已略微更新，以使其不包含纯文本形式的任何私有数据。到目前为止，cookie 的格式为 realmName/userId/userSessionId。现在，cookie 包含用户会话 ID，该 ID 通过 SHA-256 哈希并进行 URL 编码。

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

如果您正在实现自己的提供程序并依赖于内部 Keycloak cookie 的格式，则这些更改可能会影响您。

以前默认包含的 robots.txt 文件现在已删除。默认的 robots.txt 文件阻止了所有抓取，这阻止了 noindex/nofollow 指令被遵循。所需的默认行为是 Keycloak 页面不显示在搜索引擎结果中，这可以通过现有的 X-Robots-Tag 标头来实现，该标头默认设置为 none。如果需要不同的行为，则可以按领域覆盖此标头的值。

如果您之前为此在反向代理配置中添加了规则，则现在可以删除它。

允许导入外部生成的密钥（rsa 和 java-keystore 工厂）的密钥提供程序现在检查关联证书（如果存在）的有效性。因此，具有过期证书的密钥不能再导入到 Keycloak 中。如果证书在运行时过期，则密钥将转换为被动密钥（已启用但未激活）。被动密钥不用于新令牌，但仍可用于验证先前颁发的令牌。

默认的 generated 密钥提供程序生成有效期为 10 年的证书（具有或可以具有关联证书的类型）。由于有效期长且建议频繁轮换密钥，因此生成的提供程序不执行此检查。

在此版本中，管理事件可能包含有关事件触发时上下文的更多详细信息。升级时，您应该预计数据库架构将被更新，以在 ADMIN_EVENT_ENTITY 表中添加一个名为 DETAILS_JSON 的新列。

由于 OpenShift v3 早已停止生命周期，因此已从 Keycloak 中删除了对 OpenShift v3 的身份代理支持。

从 Keycloak 26 开始，组织功能已完全支持。

Keycloak 25 引入了 persistent-user-sessions 功能。启用此功能后，所有用户会话都将持久化在数据库中，而不是以前仅持久化脱机会话的行为。在 Keycloak 26 中，此功能默认启用。这意味着默认情况下所有用户会话都持久化在数据库中。

可以通过禁用该功能将此行为恢复到以前的状态。有关更多详细信息，请参阅“配置分布式缓存”指南中的“易失性用户会话”部分。

有关如何升级的信息，请参阅“升级指南”。

现在有一个新版本 (v2) 的 keycloak 登录主题，它提供了改进的外观和感觉，包括支持根据用户偏好自动切换到深色主题。

以前的版本 (v1) 现在已弃用，将在未来的版本中删除。

对于所有新领域，keycloak.v2 将是默认登录主题。此外，任何从未显式设置登录主题的现有领域都将切换到 keycloak.v2。

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

有关如何迁移的信息，请参阅“升级指南”。

过去，当所有管理员用户都被锁定后，重新获得对 Keycloak 实例的访问权限是一个具有挑战性和复杂性的过程。认识到这些挑战并旨在显着增强用户体验，Keycloak 现在提供了几种直接的方法来引导临时管理员帐户并恢复丢失的管理员访问权限。

现在可以使用特定选项运行 start 或 start-dev 命令来创建临时管理员帐户。此外，还引入了一个新的专用命令，允许用户轻松重新获得管理员访问权限。

有关详细说明和有关此主题的更多信息，请参阅“管理员引导和恢复”指南。

底层 Quarkus 对 OpenTelemetry Tracing 的支持已暴露给 Keycloak，并允许获取应用程序跟踪以获得更好的可观察性。它有助于查找性能瓶颈、确定应用程序故障的原因、跟踪分布式系统中的请求等等。该支持处于预览模式，我们很乐意获得任何反馈。

有关更多信息，请参阅“启用跟踪”指南。

OpenID 可验证凭据颁发 (OID4VCI) 在 Keycloak 中仍然是一个实验性功能，但在此版本中得到了极大的改进。您可以在 Keycloak OAuth SIG 中找到重要的开发和讨论。欢迎 Keycloak 社区的任何人加入。

非常感谢 OAuth SIG 小组的所有成员参与此功能的开发和讨论。特别感谢 Francis Pouatcha、Pascal Knüppel、Takashi Norimatsu、Ingrid Kamga、Stefan Wiedemann 和 Thomas Darimont。

DPoP（OAuth 2.0 所有权证明演示）预览功能已得到改进。DPoP 现在支持所有授权类型。在以前的版本中，此功能仅支持 authorization_code 授权类型。UserInfo 端点上的 DPoP 令牌类型也得到了支持。

非常感谢 Pascal Knüppel 的贡献。

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

现在可以在 admin REST API 上使用轻量级访问令牌。security-admin-console 和 admin-cli 客户端现在默认使用轻量级访问令牌，因此这两个客户端现在启用了“始终使用轻量级访问令牌”和“允许完整范围”。但是，管理控制台中的行为应保持不变。如果您对这两个客户端进行了更改，并且您将它们用于其他目的，请务必小心。

Keycloak JavaScript 适配器现在是一个独立的库，因此不再从 Keycloak 服务器静态提供。目标是将库与 Keycloak 服务器解耦，以便可以独立重构库，从而简化代码并使其在未来更易于维护。此外，该库现在没有第三方依赖项，这使其更轻巧，更易于在不同环境中使用。

有关更改的完整细分，请查阅“升级指南”。

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

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

当指定 http-management-relative-path 或 http-relative-path 属性时，同样适用于管理界面。

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

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

有关如何迁移的信息，请参阅“升级指南”。

基于客户端属性的条件已添加到客户端策略中。您可以使用此条件为具有指定客户端属性和指定值的客户端指定策略。在评估此条件时，可以使用 AND 或 OR 条件，如客户端策略文档中所述。

非常感谢 Yoshiyuki Tabata 的贡献。

现在可以为所有可用的日志处理程序指定日志级别，例如 console、file 或 syslog。这种更精细的方法提供了控制整个应用程序日志记录的能力，并可以根据您的需求进行定制。

有关更多信息，请参阅 日志记录指南。

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

当 proxy-headers 选项设置为指定受信任代理地址的允许列表时，可以使用 proxy-trusted-addresses。如果给定请求的代理地址不受信任，则将不会使用相应的代理头值。

proxy-protocol-enabled 选项控制服务器是否应在使用代理的情况下提供请求时使用 HA PROXY 协议。当设置为 true 时，返回的远程地址将是来自实际连接客户端的地址。

可以设置 https-certificates-reload-period 选项来定义密钥库、信任库和 https-* 选项引用的证书文件的重新加载周期。使用 -1 禁用重新加载。默认为 1 小时。

可以设置 --cache-embedded-${CACHE_NAME}-max-count= 来定义指定缓存中缓存条目数量的上限。

根据社区反馈，我们决定取消弃用 https-trust-store-* 选项，以便在受信任证书中实现更好的粒度。

java-keystore 密钥提供程序允许从外部 java 密钥库文件加载 realm 密钥，该提供程序已修改为管理所有 Keycloak 算法。此外，可以使用 Vault 配置检索密钥库和从密钥库检索实际密钥所需的密钥。因此，Keycloak realm 可以将任何密钥外部化到加密文件中，而无需在数据库中存储敏感数据。

有关此主题的更多信息，请参阅 配置 realm 密钥。

现在，Keycloak 允许配置 ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW 或 ECDH-ES+A256KW 作为客户端的加密密钥管理算法。椭圆曲线 Diffie-Hellman 临时静态 (ECDH-ES) 规范为 JWT 引入了三个新的标头参数：epk、apu 和 apv。目前，Keycloak 实现仅管理强制性的 epk，而其他两个（可选）永远不会添加到标头中。有关这些算法的更多信息，请参阅 JSON Web 算法 (JWA)。

此外，新的密钥提供程序 ecdh-generated 可用于生成 realm 密钥，并且 Java KeyStore 提供程序中添加了对 ECDH 算法的支持。

非常感谢 Justin Tay 的贡献。

现在可以在 realm 中拥有同一社交 Broker 的多个实例。

大多数情况下，realm 不需要同一社交 Broker 的多个实例。但是，由于引入了 organization 功能，应该可以将同一社交 Broker 的不同实例链接到不同的组织。

创建社交 Broker 时，您现在应该像其他任何 Broker 一样提供一个 Alias 和可选的 Display name。

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

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

base/login 和 keycloak.v2/login 主题中的 template.ftl 文件现在允许自定义登录框的页脚。这可以用于显示常用链接或在页面末尾包含自定义脚本。

新的 footer.ftl 模板提供了一个 content 宏，该宏在“登录框”底部呈现。

Keycloak CR 现在公开了用于控制 Keycloak Pod 调度的第一类属性。

有关更多详细信息，请参阅 Operator 高级配置。

KeycloakRealmImport CR 现在公开了 spec.placeholders，用于为导入中的占位符替换创建环境变量。

有关更多详细信息，请参阅 Operator Realm 导入。

在此版本中，LDAP 连接池配置完全依赖于系统属性。

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

Marshalling 是将 Java 对象转换为字节的过程，以便在 Keycloak 服务器之间通过网络发送。在 Keycloak 26 中，我们将 marshalling 格式从 JBoss Marshalling 更改为 Infinispan Protostream。

Infinispan Protostream 基于 Protocol Buffers (proto 3)，它具有向后/向前兼容性的优势。

由于所有使用 OSGi 元数据的 Java 适配器都已移除，因此我们已停止为我们的 jar 生成 OSGi 元数据。

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

有关如何迁移的信息，请参阅“升级指南”。

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

有关如何迁移的信息，请参阅“升级指南”。

保护应用程序和服务 文档已转换为与先前版本中转换的 服务器安装和配置 文档类似的新格式。该文档现在可在 Keycloak 指南 下找到。

Keycloak 不再发送 _LEGACY Cookie，这些 Cookie 是作为旧版浏览器不支持 Cookie 上的 SameSite 标志的权宜之计而引入的。

_LEGACY Cookie 还有另一个用途，即允许从不安全的上下文中登录。虽然这在 Keycloak 的生产部署中完全不建议使用，但在 localhost 之外通过 http 访问 Keycloak 却相当频繁。作为 _LEGACY Cookie 的替代方案，当 Keycloak 检测到正在使用不安全的上下文时，现在不会设置 secure 标志，而是设置 SameSite=Lax 而不是 SameSite=None。

UserRepresentation 中的 origin 属性已弃用，并计划在未来版本中移除。

相反，首选使用 federationLink 属性来获取用户链接到的提供程序。

Account Console v2 主题已从 Keycloak 中移除。此主题在 Keycloak 24 中已弃用，并被 Account Console v3 主题取代。如果您仍在使用此主题，则应迁移到 Account Console v3 主题。

Keycloak 现在支持 OpenJDK 21，因为我们希望坚持使用最新的 LTS OpenJDK 版本。

OpenJDK 17 支持在 Keycloak 中已弃用，并将在后续版本中移除，以支持 OpenJDK 21。

正如先前 Keycloak 版本的发行说明中所述，大多数 Java 适配器现在已从 Keycloak 代码库和下载页面中移除。

对于 OAuth 2.0/OIDC，这包括移除 Tomcat 适配器、WildFly/EAP 适配器、Servlet Filter 适配器、KeycloakInstalled 桌面适配器、jaxrs-oauth-client 适配器、JAAS 登录模块、Spring 适配器和 SpringBoot 适配器。您可以查看 我们之前的帖子 以获取一些替代方案的列表。

对于 SAML，这包括移除 Tomcat 适配器和 Servlet filter 适配器。WildFly 和 JBoss EAP 仍然支持 SAML 适配器。

通用的 Authorization Client 库仍然受支持，我们仍然计划支持它。它的目标是与任何其他 OAuth 2.0 或 OpenID Connect 库结合使用。您可以查看 quickstarts，了解一些示例，其中此授权客户端库与第三方 Java 适配器（如 Elytron OIDC 或 SpringBoot）一起使用。您还可以查看 quickstarts，了解与 WildFly 一起使用的 SAML 适配器示例。

在 Keycloak 24 中，“欢迎”页面已更新为使用 PatternFly 5，这是设计系统的最新版本，它是 Keycloak 用户界面的基础。在此版本中，管理控制台和 Account Console 也已更新为使用 PatternFly 5。如果您想扩展和自定义管理控制台和 Account Console，请查看 PatternFly 5 中的更改，并相应地更新您的自定义项。

Argon2 现在是非 FIPS 环境中 Keycloak 使用的默认密码哈希算法。

Argon2 是 2015 年密码哈希竞赛 的获胜者，并且是 OWASP 推荐的哈希算法。

在 Keycloak 24 中，PBKDF2 的默认哈希迭代次数从 27.5K 增加到 210K，导致生成密码哈希所需的 CPU 时间增加了 10 倍以上。使用 Argon2，可以以几乎与先前版本的 Keycloak 相同的 CPU 时间实现更好的安全性。一个缺点是 Argon2 需要更多内存，这是抵抗 GPU 攻击的要求。Keycloak 中 Argon2 的默认设置每个哈希请求需要 7MB。为了防止过度的内存和 CPU 使用，Argon2 并行计算哈希的默认值被限制为 JVM 可用的核心数。为了支持 Argon2 的内存密集型特性，我们将默认 GC 从 ParallelGC 更新为 G1GC，以获得更好的堆利用率。

请注意，Argon2 不符合 FIPS 140-2 标准。因此，如果您处于 FIPS 环境中，默认算法仍为 PBKDF2。另请注意，如果您处于非 FIPS 环境中，并且计划迁移到 FIPS 环境，请考虑在一开始就将密码策略更改为 FIPS 合规算法，例如 pbkdf2-sha512。否则，用户在切换到 FIPS 环境后将无法登录。

为了解决先前主机名配置设置的复杂性和缺乏直观性的问题，我们很荣幸推出主机名 v2 选项。

我们倾听了您的反馈，解决了棘手的问题，并为管理主机名配置创建了更顺畅的体验。请注意，即使这些选项背后的行为也已更改，并且需要您注意 - 如果您正在处理自定义主机名设置。

默认情况下支持主机名 v2 选项，因为旧的主机名选项已弃用，并将在后续版本中移除。您应尽快迁移到它们。

默认情况下激活新选项，因此 Keycloak 将无法识别旧选项。

有关如何迁移的信息，请参阅“升级指南”。

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

此功能是预览功能，默认情况下处于禁用状态。要使用它，请将以下内容添加到您的构建命令中

有关更多详细信息，请参阅 启用和禁用功能 指南。容量调整指南 包含一个新段落，描述了启用此功能后更新的资源需求。

有关如何升级的信息，请参阅“升级指南”。

以下用于设置自定义 Cookie 的 API 已移除

Keycloak 23 版本改进了用户在多个浏览器选项卡中并行进行身份验证的情况。但是，此改进未解决身份验证会话过期的情况。现在，对于用户已在一个浏览器选项卡中登录，而身份验证会话在其他浏览器选项卡中过期的情况，Keycloak 能够使用 OIDC/SAML 错误重定向回客户端应用程序，以便客户端应用程序可以立即重试身份验证，由于 SSO 会话，这通常应自动登录应用程序。有关更多详细信息，请参阅 服务器管理指南身份验证会话。

在以前的版本中，添加了对轻量级访问令牌的支持。在此版本中，我们设法从轻量级访问令牌中移除了更多内置声明。这些声明由协议映射器添加。其中一些甚至影响了常规访问令牌或 ID 令牌，因为 OIDC 规范并非严格要求它们。

有关更多详细信息，请参阅 升级指南。

调用令牌内省端点时，可以使用 HTTP 标头 Accept: application/jwt。当为特定客户端启用时，它会从令牌内省端点返回一个声明 jwt，其中包含完整的 JWT 访问令牌，这在客户端调用内省端点时使用轻量级访问令牌的情况下尤其有用。感谢 Thomas Darimont 的贡献。

Keycloak 支持一种新的密码策略，该策略允许您拒绝包含用户用户名的用户密码。

在管理控制台中，您现在可以在特定 realm 的 必需操作 选项卡中配置一些必需操作。目前，更新密码 是唯一内置的可配置必需操作。它支持设置 身份验证最长有效期，这是用户可以通过 kc_action 参数（例如在 Account Console 中更新密码时使用）更新密码而无需重新身份验证的最长时间。必需操作的排序也得到了改进。当身份验证期间存在多个必需操作时，所有操作会一起排序，无论这些操作是在身份验证期间设置的（例如通过 kc_action 参数）还是由管理员手动添加到用户帐户的操作。感谢 Thomas Darimont 和 Daniel Fesenmeyer 的贡献。

添加了对 Passkeys 条件 UI 的支持。当启用 Passkeys 预览功能时，会有一个专用的身份验证器可用，这意味着您可以从可用 Passkeys 帐户列表中选择并基于该帐户对用户进行身份验证。感谢 Takashi Norimatsu 的贡献。

添加了用于保护 SAML 客户端的默认客户端配置文件。在管理控制台中浏览 realm 的客户端策略时，您会看到一个新的客户端配置文件 saml-security-profile。使用它时，将对 SAML 客户端应用安全最佳实践，例如强制签名、禁用 SAML Redirect 绑定以及禁止通配符重定向 URL。

添加了新的身份验证器 Confirm override existing link。此身份验证器允许覆盖 Keycloak 用户的链接 IDP 用户名，该用户名之前已链接到不同的 IDP 身份。有关更多详细信息，请参阅 服务器管理指南。感谢 Lex Cao 的贡献。

OpenID for Verifiable Credential Issuance (OID4VCI) 的支持正在进行中。目前，这仍然是正在进行的工作，但正在逐步添加内容。Keycloak 可以充当 OID4VC Issuer，并支持 Pre-Authorized code flow。支持 JWT-VC、SD-JWT-VC 和 VCDM 格式的可验证凭据。感谢 OAuth SIG 小组的成员的贡献和反馈，尤其感谢 Stefan Wiedemann、Francis Pouatcha、Takashi Norimatsu 和 Yutaka Obuchi。

按用户属性搜索用户时，Keycloak 不再强制使用小写比较来搜索用户属性名称。此更改的目标是通过使用 Keycloak 在用户属性表上的本机索引来加速搜索。如果您的数据库排序规则不区分大小写，则您的搜索结果将保持不变。如果您的数据库排序规则区分大小写，则您可能会看到比以前更少的搜索结果。

对于 keycloak-authz-client 库的用户，调用 AuthorizationResource.getPermissions(…​) 现在可以正确返回 List<Permission>。

以前，即使方法声明声明了 List<Permission>，它也会在运行时返回 List<Map>。

此修复程序将破坏依赖于将 List 或其内容强制转换为 List<Map> 的代码。如果您以任何身份使用过此方法，您很可能已经这样做并受到影响。

导出客户端的授权设置时，不再设置资源、作用域和策略的 ID。因此，您现在可以将一个客户端的设置导入到另一个客户端。

指标和运行状况检查端点不再通过标准 Keycloak 服务器端口访问。由于这些端点应从外部世界隐藏，因此可以在单独的默认管理端口 9000 上访问它们。

它允许不将其作为 Kubernetes 环境中的标准 Keycloak 端点向用户公开。新的管理界面提供了一组新的选项，并且是完全可配置的。

Keycloak Operator 假定默认情况下管理界面已打开。有关更多详细信息，请参阅 配置管理界面。

Keycloak 现在支持 Syslog 协议进行远程日志记录。它利用 RFC 5424 中定义的协议。默认情况下，syslog 处理程序处于禁用状态，但启用后，它会将所有日志事件发送到远程 syslog 服务器。

有关更多信息，请参阅 配置日志记录 指南。

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

有关更多详细信息，请参阅 升级指南。

现在可以在运行时指定 cache、cache-stack 和 cache-config-file 选项。这消除了执行构建阶段和因它们而重建映像的需求。

有关更多详细信息，请参阅 升级指南。

高可用性指南现在包含有关如何配置 AWS Lambda 以防止从备份站点到主站点的预期自动故障恢复的指南。

在此版本中，我们最终从以下类中移除了已弃用的方法

有关更多详细信息，请参阅 升级指南。

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

有关更多详细信息，请参阅 升级指南。

受支持和测试的数据库现在包括 PostgreSQL 16。

在此版本中，我们将 Keycloak Organizations 作为技术预览功能交付。

此功能为 realm 提供了一些核心 CIAM 功能，这将作为未来更多功能的基础，以解决企业对企业 (B2B) 和企业对企业对客户 (B2B2C) 用例。

在功能方面，该功能已完成。但是，我们仍然需要做一些工作，使其在下一个主要版本中得到完全支持。剩余的工作主要是为生产部署准备该功能，重点是可伸缩性。此外，根据我们在下一个主要版本之前收到的反馈，我们最终可能会接受其他功能并为该功能增加更多价值，而不会影响其路线图。

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

此版本包含对重要安全问题的修复，该问题影响某些使用 PAR（推送授权请求）的 OIDC 机密客户端。如果您将 OIDC 机密客户端与 PAR 一起使用，并且您使用基于 client_id 和 client_secret 的客户端身份验证（作为 HTTP 请求正文中的参数发送）（OIDC 规范中指定的 client_secret_post 方法），强烈建议在升级到此版本后轮换客户端的客户端密钥。

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

有关更多详细信息，请参阅 升级指南。

由于使用 Operator 部署 Keycloak 时发布过程中的问题，它安装了 nightly 容器而不是 24.0.0。

作为此问题的快速修复，24.0.0 容器被标记为 nightly，并且 nightly 版本已暂时禁用。

如果您在昨天欧洲中部时间下午 5 点之前使用 Operator 安装或升级到 24.0.0，则数据库可能已使用错误的版本进行了更新。要检查您是否受到影响，请连接到您的数据库并运行以下 SQL 命令

如果以上命令返回匹配的行，您将需要采取一些措施，否则数据库迁移将不会为未来的版本运行。要解决此问题，请运行以下 SQL 命令

用户配置文件预览功能已提升为完全受支持，并且用户配置文件默认启用。

在过去的几个月中，Keycloak 团队花费了大量精力来完善用户配置文件功能，使其得到完全支持。在此版本中，我们继续努力。基于我们出色的社区的彻底测试和反馈，进行了许多改进、修复和完善。

以下是此功能的一些亮点：

用户配置文件的首个受支持功能版本只是一个起点和基线，未来将在此基础上交付更多身份管理相关的功能。

我们衷心感谢出色的 Keycloak 社区，许多想法、需求和贡献都来自社区！特别感谢

有关用户配置文件功能的更多详细信息，请参阅服务器管理指南。

早在 2022 年，我们就宣布在 Keycloak 19 中弃用 Keycloak 适配器。为了给社区更多时间来采纳，此计划被推迟。

考虑到这一点，这将是包含 OpenID Connect 和 SAML 适配器的 Keycloak 的最后一个主要版本。由于 Jetty 9.x 自 2022 年起已不受支持，Jetty 适配器已在此版本中移除。

通用的 Authorization Client 库将继续获得支持，并且旨在与任何其他 OAuth 2.0 或 OpenID Connect 库结合使用。

我们将继续交付的唯一适配器是用于最新版本的 WildFly 和 EAP 8.x 的 SAML 适配器。继续支持它的原因是 Keycloak 中大部分 SAML 代码库都来自 WildFly 的贡献。作为此贡献的一部分，我们同意长期维护用于 WildFly 和 EAP 的 SAML 适配器。

首次使用 Keycloak 时出现的“欢迎”页面已重新设计。它提供了更好的设置体验，并符合最新版本的 PatternFly。简化的页面布局仅包含一个用于注册第一个管理用户的表单。完成注册后，用户将直接被发送到管理控制台。

如果您使用自定义主题，您可能需要更新它以支持新的欢迎页面。有关详细信息，请参阅升级指南。

我们在 Keycloak 22 中引入了第 3 版帐户控制台作为预览功能。在此版本中，我们将其设为默认版本，并在过程中弃用第 2 版，该版本将在后续版本中移除。

这个新版本内置了对用户配置文件功能的支持，管理员可以使用该功能配置哪些属性在帐户控制台中对用户可用，并在用户登录后直接将其定向到其个人帐户页面。

如果您正在使用或扩展此主题的自定义功能，您可能需要执行额外的迁移。有关更多详细信息，请参阅升级指南。

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

作为此更改的一部分，默认密码哈希提供程序已从 pbkdf2-sha256 更改为 pbkdf2-sha512。此外，基于 pbkdf2 的密码哈希算法的默认哈希迭代次数也发生了更改。此更改意味着与最新建议对齐的更高安全性，但会对性能产生影响。可以通过将密码策略 hashAlgorithm 和 hashIterations 添加到您的 realm 来坚持旧的行为。有关更多详细信息，请参阅升级指南。

CORS 相关的 Keycloak 功能已提取到 SPI 中，这可以提供额外的灵活性。请注意，CorsSPI 是内部的，并且可能会在未来的版本中更改。感谢 Dmitry Telegin 的贡献。

Keycloak 引入了改进的信任库配置选项。Keycloak 信任库现在在整个服务器中使用，包括出站连接、mTLS 和数据库驱动程序。您不再需要为各个区域配置单独的信任库。要配置信任库，您可以将您的信任库文件或证书放在默认的 conf/truststores 中，或使用新的 truststore-paths 配置选项。有关详细信息，请参阅相关的指南。

功能现在支持版本控制。为了保持向后兼容性，所有现有功能（包括 account2 和 account3）都标记为版本 1。新引入的功能将使用版本控制，这意味着用户可以在所需功能的不同实现之间进行选择。

有关详细信息，请参阅功能指南。

现在可以将 SAML 身份提供商配置为自动从 IDP 实体元数据描述符端点下载签名证书。为了使用新功能，请在提供商中配置 Metadata descriptor URL 选项（发布包含证书的 IDP 元数据信息的 URL），并将 Use metadata descriptor URL 设置为 ON。证书将从该 URL 自动下载并缓存在 public-key-storage SPI 中。也可以使用提供商页面中的操作组合从管理控制台重新加载或导入证书。

有关新选项的更多详细信息，请参阅文档。

添加了一个新的健康检查端点，可在 /lb-check 访问。执行在事件循环中运行，这意味着即使在 Keycloak 需要处理请求队列中等待的许多请求的过载情况下，此检查也具有响应性。此行为在多站点部署中很有用，例如，可以避免故障转移到另一个负载过重的站点。端点当前正在检查嵌入式和外部 Infinispan 缓存的可用性。稍后可能会添加其他检查。

默认情况下不启用此端点。要启用它，请使用 multi-site 功能运行 Keycloak。有关更多详细信息，请参阅启用和禁用功能。

Keycloak CR 现在包含一个 startOptimized 字段，该字段可用于覆盖关于是否对启动命令使用 --optimized 标志的默认假设。因此，即使使用自定义 Keycloak 镜像，您也可以使用 CR 配置构建时选项。

现在可以使用新的 --proxy-headers 选项分别启用对 Forwarded 或 X-Forwarded-* 标头的解析。有关详细信息，请参阅反向代理指南。原始的 --proxy 选项现已弃用，并将在未来的版本中移除。有关迁移说明，请参阅升级指南。

在此版本中，我们正在封装根用户属性（例如 username、email、firstName、lastName 和 locale），方法是将它们移动到基类/抽象类中，以便在使用 Admin 和 Account REST API 时对这些属性的编组和解组方式进行对齐。

此策略提供了客户端管理属性方式的一致性，并确保它们符合为 realm 设置的用户配置文件配置。

有关更多详细信息，请参阅 升级指南。

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

有关更多详细信息，请参阅 升级指南。

在此版本中，如果用户已通过身份验证并且操作绑定到另一个用户，则您不能再执行诸如电子邮件验证之类的操作。例如，如果电子邮件链接绑定到不同的帐户，则用户无法完成验证电子邮件流程。

在此版本中，如果用户尝试点击链接以验证电子邮件，并且该电子邮件之前已验证，则会显示正确的消息。

除此之外，还会触发一个新的错误 (EMAIL_ALREADY_VERIFIED) 事件，以指示尝试验证已验证的电子邮件。您可以使用此事件来跟踪可能的用户帐户劫持尝试（如果链接已泄漏）或在用户不认识该操作时提醒用户。

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

有关更多详细信息，请参阅 升级指南。

为了减少内存需求，我们引入了一个配置选项来缩短导入到 Infinispan 缓存中的离线会话的生命周期。目前，默认情况下禁用离线会话生命周期覆盖。

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

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

有关更多详细信息，请参阅 升级指南。

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

有关更多详细信息，请参阅 升级指南。

对暴力破解保护进行了一些增强

在以前版本的 Keycloak 中，当用户、组或客户端策略的最后一个成员被删除时，该策略也会被删除。不幸的是，如果该策略在聚合策略中使用，则可能导致权限升级。为了避免权限升级，效果策略不再被删除，管理员将需要更新这些策略。

Keycloak CR 现在允许通过使用 cache spec configMapFile 字段来指定 cache-config-file 选项，例如

Keycloak CR 现在允许指定 resources 选项，用于管理 Keycloak 容器的计算资源。它提供了通过 Keycloak CR 为主 Keycloak 部署独立请求和限制资源的能力，以及通过 Realm Import CR 为 realm 导入 Job 独立请求和限制资源的能力。

当未指定任何值时，默认 requests 内存设置为 1700MiB，limits 内存设置为 2GiB。

您可以根据您的需求指定自定义值，如下所示

有关更多详细信息，请参阅Operator 高级配置。

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

有关更多详细信息，请参阅 升级指南。

Cookie 处理代码已重构和改进，包括一个新的 Cookie 提供程序。这为 Keycloak 处理的 Cookie 提供了更好的一致性，以及在需要时引入围绕 Cookie 的配置选项的能力。

用于 NameID 的用户属性映射器允许将 Name ID Format 选项设置为以下值

但是，Keycloak 不支持接收包含这些 NameIDPolicy 之一的 AuthnRequest 文档，因此永远不会使用这些映射器。支持的选项已更新为仅包含以下 Name ID 格式

Keycloak 不再为初始和最大堆大小指定硬编码值，而是使用相对于容器总内存的相对值。JVM 选项 -Xms 和 -Xmx 已被 -XX:InitialRAMPercentage 和 -XX:MaxRAMPercentage 替换。

有关更多详细信息，请参阅 升级指南。

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

对于某些环境而言，将 Keycloak 部署到多个独立站点对于提供高可用性和从故障中快速恢复至关重要。此版本支持 Keycloak 的主动-被动部署。

要开始使用，请使用高可用性指南，其中还包括在云环境中部署高可用性 Keycloak 的全面蓝图。

声明式用户配置文件在此版本中仍为预览功能，但我们正在努力将其提升为受支持的功能。欢迎提供反馈。如果您发现任何问题或有任何改进想法，欢迎创建Github issue，最好带有标签 area/user-profile。还建议查看升级指南，其中包含此版本迁移的更改，以获取有关迁移的其他信息。

对于具有许多组和子组的用例，围绕组搜索的性能得到了改进。有一些改进允许分页查找子组。感谢 Alice 的贡献。

Keycloak 22.0.2 中引入了一个安全漏洞。我们强烈建议不要升级到 22.0.2，对于任何已在生产环境中部署 22.0.2 的用户，请立即升级到 22.0.3。

对于在 Keycloak 升级到 22.0.2 后自行注册的用户，他们的密码未被安全存储，并且可能会暴露给 Keycloak 的管理员。这仅影响在升级推出后注册的用户，不影响任何先前注册的用户。

任何使用预览声明式用户配置文件的 realm 都不受此问题的影响，只有使用默认用户配置文件提供程序的 realm 才会受到影响。

要确定您的部署中是否有任何受影响的用户，您可以通过访问数据库并运行以下 SQL 语句来查询这些用户

我们建议联系任何受影响的用户，并为他们添加更新密码的必需操作。

如果存在任何受影响的用户，我们还建议通过运行以下 SQL 语句从数据库中删除这些属性

如果在 22.0.2 版本发布后对数据库进行了任何备份，并且存在受影响的用户，我们建议删除这些备份。

Keycloak 现在在一个 realm 中支持多个 LDAP 提供程序，这些提供程序支持与同一 Kerberos realm 的 Kerberos 集成。当 LDAP 提供程序无法找到通过 Kerberos/SPNEGO 身份验证的用户时，Keycloak 会尝试回退到下一个 LDAP 提供程序。Keycloak 还更好地支持单个 LDAP 提供程序支持多个彼此信任的 Kerberos realm 的情况。

允许使用 Keycloak 替换 OpenShift 3.x 中的内部 IdP 的 openshift-integration 预览功能已从 Keycloak 代码库中移除到单独的扩展项目中。

如果应用程序客户端使用非 http(s) 自定义方案，从现在开始，验证需要有效的重定向模式显式允许该方案。允许 custom 方案的示例模式为 custom:/test、custom:/test/* 或 custom:*。出于安全原因，像 * 这样的通用模式不再涵盖它们。

过去，Keycloak 是在多个 GitHub 存储库中维护的

拥有多个存储库引入了许多复杂性和辛劳。例如，对于单个更改，通常必须向不同的存储库发送多个拉取请求。

为了简化操作，我们现在已将所有内容迁移到主存储库。

Keycloak 中的 FIPS 140-2 支持在以前的版本中是预览版，现在已升级为正式支持。

Account Console 版本 3 现在作为 Keycloak 中的实验性功能提供。此版本支持使用“用户配置文件”功能创建的自定义字段。如果您希望试用并向我们提供一些早期反馈，您可以按如下方式启用它

作为移除已弃用适配器的一部分，Keycloak Policy Enforcer 已从适配器代码库中提取到单独的依赖项中

通过提供此依赖项，我们希望能够将策略执行器与您首选的 Java 堆栈集成。

它还提供内置支持，以启用策略执行器来保护使用 Wildfly Elytron 保护的 Jakarta 应用程序。

目前，此依赖项尚未 GA，因为我们仍在开发快速入门和文档。

这项工作不应影响使用已弃用适配器的现有应用程序。 = 默认情况下可用的 Javascript 引擎

在以前的版本中，当 Keycloak 在带有 Javascript 提供程序的 Java 17 上使用时，需要将 Nashorn javascript 引擎添加到分发中。现在不再需要这样做，因为 Nashorn javascript 引擎默认在 Keycloak 服务器中可用。

在 Keycloak 19 中，新的管理控制台已升级为新的默认管理控制台，旧的管理控制台已被弃用。在此版本中，旧的管理控制台已完全移除。

Keycloak 提供了一个可选的指标端点，该端点以 Prometheus 格式导出指标。在此版本中，提供此数据的实现从 SmallRye 切换到 Micrometer。由于此更改，指标已重命名。

有关详细信息，请参阅迁移指南。

现在已弃用使用 Java 11 运行 Keycloak 服务器，并计划在 Keycloak 22 中移除。

适配器在 Java 8、Java 11 和 Java 17 上仍然受支持。但是，我们计划在不久的将来移除对 Java 8 的支持。

我们在此版本中移除了对 Hashicorp vault 的开箱即用支持。

有关更多详细信息，请参阅此讨论。

在此版本之前，SAML SP 元数据包含用于签名和加密的相同密钥。从 Keycloak 的此版本开始，我们在 SP 元数据中仅包含用于加密的预期 realm 密钥。对于每个加密密钥描述符，我们还指定了它应该使用的算法。下表显示了支持的 XML-Enc 算法以及到 Keycloak realm 密钥的映射。有关更多详细信息，请参阅升级指南。

已从用户会话提供程序中移除几个已弃用的方法。如果尚未完成，则需要将其用法替换为 Keycloak 20 版本 Javadoc 中记录的相应替换项。有关更多详细信息，请参阅升级指南。

已弃用 RoleModel 中的 IS_CLIENT_ROLE 可搜索字段。应将其替换为与运算符 EXISTS 或 NOT_EXISTS 一起使用的 CLIENT_ID 可搜索字段。有关更多详细信息，请参阅 Keycloak 21 的 JavaDoc。

Keycloak 中的 FIPS 140-2 支持在以前的版本中是实验性的，现在已升级为预览版。为了创建此预览版本，进行了许多修复和改进。有关详细信息，请参阅FIPS 文档。欢迎提供反馈！

再次感谢 David Anderson、Sudeep Das 和 Isaac Jensen 在此功能上的巨大帮助。

除了识别非标准的 X-Forwarded-* 以获取代理添加的信息（否则当代理服务器参与请求路径时，这些信息将被更改或丢失），Keycloak 现在还可以利用标准的 Forwarded 标头来实现相同的目的。

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

请确保您的代理在向 Keycloak 节点发出请求时也覆盖了 Forwarded 标头。

为了增强安全性，Keycloak 容器镜像已通过两种方式进行了修改：首先，它现在基于 UBI9，而不是 UBI8。其次，我们已切换到 -micro，而之前使用的是 -minimal。

切换到 UBI9 不会对大多数用户产生任何影响。在极少数情况下，可能会出现 glibc 错误 CPU does not support x86-64-v2。x86-64-v2 自 2009 年以来已在处理器中可用。当您的虚拟化环境配置错误时，最有可能遇到此问题。

从 -minimal 更改为 -micro 具有更大的潜在影响。对镜像进行简单自定义的用户不会注意到任何差异，但是任何安装 RPM 的用户都需要更改其执行方式。在容器中运行 Keycloak 指南已更新，向您展示如何操作。

由于这些更改，影响 Keycloak 容器镜像的已知 CVE 减少了 82%！

在 Keycloak 17.0.0 中，推出了新的基于 Quarkus 的 Keycloak 分发版，而基于 WildFly 的分发版已被弃用。在此版本中，WildFly 分发版已被移除，并且不再受支持。

如果您仍在使用 WildFly 分发版，我们强烈建议尽快迁移到 Quarkus 分发版，有关更多详细信息，请参阅迁移指南。

我们很高兴地宣布，用于基于 Quarkus 的分发版的新 Keycloak Operator 不再是预览功能。我们添加了新功能以及许多改进，其中一些改进导致了重大更改。

Keycloak 现在同时支持服务器和适配器的 OpenJDK 17。

随着基于 WildFly 的分发版的移除，不再支持在 OpenJDK 8 上运行 Keycloak 服务器。我们还计划在 Keycloak 21 中移除对 OpenJDK 8 上的 Keycloak 适配器的支持。

从 Keycloak 22 开始，我们计划仅支持最新的 OpenJDK LTS 版本，并力求快速支持最新的 OpenJDK 版本。这意味着我们还将在 Keycloak 22 中移除对 Keycloak 服务器的 OpenJDK 11 支持。

在此版本中，我们引入了两个额外的服务器选项来设置前端请求和管理控制台的基本 URL

更多详细信息可以在配置主机名指南中找到。

在此版本中，我们对 kc.bat 进行了重要更改，以提供与在 Linux 上运行时相同的体验。

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

在此版本中，H2 驱动程序已从 1.x 版本升级到 2.x 版本。

应用程序能够直接从 Keycloak 服务器加载 keycloak.js。由于以这种方式加载 JavaScript 库不被认为是最佳实践，因此现在有一个功能保护，允许禁用此功能。

在 Keycloak 21 中，我们将弃用此选项，并在 Keycloak 22 中计划完全移除从 Keycloak 服务器加载 keycloak.js 的功能。

在以前的版本中，向用户显示的 OTP 应用程序列表在 Keycloak 中是硬编码的。随着 OTP 应用程序 SPI 的引入，现在可以禁用内置 OTP 应用程序，以及添加自定义 OTP 应用程序。

自定义身份提供商现在可以设置登录页面上使用的图标。感谢 Klaus Betz，他恰好也是 Keycloak 扩展程序的维护者，该扩展程序支持使用 AppleID 登录。

现在可以实验性地支持将 Keycloak 部署到启用 FIPS 140-2 的环境中。发布后不久将发布一篇博文，详细介绍如何尝试。欢迎反馈！

感谢 David Anderson，他贡献了此功能的部分内容。还要感谢 Sudeep Das 和 Isaac Jensen 的初步原型工作，这为我们提供了灵感。

现在可以通过 Admin REST API 按属性搜索组。感谢 Alice 的贡献。

现在可以允许用户在帐户控制台中查看其组成员资格。感谢 cgeorgilakis 的贡献。

已从数据提供程序和模型中删除几个已弃用的方法。如果尚未完成，则需要将其用法替换为 Keycloak 19 版本 Javadoc 中记录的相应替换项。有关更多详细信息，请参阅 升级指南。

一些 Keycloak OpenID Connect 适配器已达到生命周期结束，并且未包含在此版本中。

新的管理控制台现在已正式发布为默认管理控制台，旧控制台现已弃用。旧控制台将在 Keycloak 21 中删除。

Keycloak 存储正在发生变化，当前的存储虽然仍然受支持，但最终将被全新的实现所取代。此更改为云原生存储带来了更好的支持、不停机能力以及更好地支持为用户以外的其他领域实现自定义存储。

这意味着当前存储的受支持功能的几个深层更改将成为传统功能。传统存储和新存储不能同时使用；一次只能激活一个存储。

最明显的变化是 User Storage SPI 与新的存储 API（Map Storage API）不兼容。因此，User Storage SPI 将随着传统存储一起弃用，并将移动到名为 keycloak-model-legacy 的单独模块。此更改影响多个领域，特别是与用户联合身份验证和自定义用户提供程序相关的领域。

此外，API 已得到整合，以便存储层的详细信息对 REST 服务层透明。具体而言，服务将无法区分缓存对象和非缓存对象，也无法专门访问联合身份验证存储与本地存储。

因此，必须审查通过 KeycloakSession 方法访问本地存储或缓存中对象的自定义扩展。有关详细信息，请参阅 升级指南。

在之前的版本中，我们添加了对 OIDC 注销的支持。此版本包含一些其他修复和改进。亮点包括

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

有一个新的预览功能 UPDATE_EMAIL。启用此功能并在领域中启用相应标志后，将要求用户单击链接确认更新其电子邮件，该链接将发送到他们的新电子邮件地址。有关更多详细信息，请参阅 服务器管理指南。感谢 Réda Housni Alaoui 的贡献。

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

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

另请参阅 Kubernetes 文档。

从版本 19 开始，Keycloak 支持使用 GELF 将日志发送到集中式日志记录解决方案，如 ELK、EFK 或 Graylog。

您可以在 日志记录 指南中找到文档和示例，以帮助您快速启动并运行。

在此版本中，我们引入了一个全新的 Keycloak Operator 作为预览。除了从头开始重写之外，与传统 Operator 相比，面向用户的主要变化是使用的 Keycloak 发行版 – 新 Operator 使用 Keycloak 的 Quarkus 发行版。因此，API（以自定义资源定义的形式）已更改。有关详细信息，包括安装和迁移说明，请参阅 Operator 相关指南。

传统 Operator 将在 Keycloak 20 之前收到更新，届时 Keycloak WildFly 发行版将达到 EOL。

新的管理控制台现在已升级为预览版，计划在 Keycloak 19 中成为默认管理控制台。

如果您发现新控制台有任何问题，或对改进有任何建议，请通过 GitHub Discussions 告知我们。

Keycloak 现在支持逐步验证。此功能在 Keycloak 17 中添加，并在本版本中得到进一步完善。

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

感谢 Cornelia Lahnsteiner 和 Georg Romstorfer 的贡献。

Keycloak 现在支持通过客户策略进行客户端密钥轮换。此功能现在作为预览功能提供，并允许为机密客户端提供领域策略，从而允许同时使用最多两个密钥。

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

恢复代码作为双因素身份验证的另一种方式，现在作为预览功能提供。

进行了一些修复和改进，以确保 Keycloak 现在完全符合所有 OpenID Connect 注销规范

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

Keycloak 现在支持 WebAuthn 无 ID 身份验证。此功能允许 WebAuthn 安全密钥在身份验证期间识别用户，只要安全密钥支持常驻密钥。有关更多详细信息，请参阅 服务器管理指南。感谢 Joaquim Fellmann 的贡献。

除了这些之外，还有更多 WebAuthn 改进和修复。

upload-script 功能已被标记为已弃用很长时间。在此版本中，它已完全删除，并且不再受支持。

如果您正在使用以下任何功能

您应该阅读此 文档，以了解如何继续依赖这些功能，但将脚本部署到服务器而不是通过管理界面来管理它们。

Keycloak 现在支持限制用户可以拥有的会话数。限制可以放置在领域级别或客户端级别。

有关更多详细信息，请参阅 服务器管理指南。感谢 Mauro de Wit 的贡献。

为了降低滥用 SAML ECP 配置文件的风险，Keycloak 现在阻止所有未明确允许它的 SAML 客户端使用此流程。可以使用客户端配置中的允许 ECP 流程标志启用配置文件，请参阅 服务器管理指南。

此版本包含一些重要的错误修复。此外，我们要感谢 Leandro José de Bortoli 对 FAPI 相关功能（如 JARM 支持和 CIBA 改进）的贡献。

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

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

Keycloak 服务器已升级为使用 WildFly 16。

感谢 tnorimat，Keycloak 现在支持使用 PS256 签名和验证令牌。

新的内置客户端范围，使按照 Eclipse MicroProfile 规范颁发令牌变得容易。

Keycloak 服务器已升级为使用 WildFly 15。

现在可以使用 Keycloak 完全保护 OpenShift 3.11，包括自动将服务帐户作为 OAuth 客户端公开为 Keycloak 的客户端的能力。

这目前是一项技术预览功能。

到目前为止，Drools 策略默认情况下处于启用状态。 但是现在，此策略类型仅作为技术预览功能提供，要使用它，您需要启用预览配置文件或相应的功能。 有关更多详细信息，请查看授权服务指南。

DB2 支持已被弃用一段时间。 在此版本中，我们已删除对 DB2 的所有支持。

引入了为记住我会话指定不同的会话空闲和最大超时的能力。 这使记住我会话的寿命比常规会话更长。

大量组以前在管理控制台中引起了问题。 现在，通过引入组的分页解决了此问题。

过去，如果存在许多离线会话，则启动服务器可能需要很长时间。 现在已大大缩短了启动时间。

Keycloak 服务器已升级为使用 WildFly 14。

Keycloak Gatekeeper 提供了一个安全代理，可用于保护应用程序和服务，而无需适配器。 它可以与您的应用程序本地安装，也可以作为 OpenShift 或 Kubernetes 上的 sidecar 安装。

非常感谢 gambol99 为 Keycloak 贡献这项工作。

签名 SPI 使插入其他签名算法成为可能。 这支持了其他签名，并且还支持更改签名的生成方式。 例如，使用此功能允许使用 HSM 设备对令牌进行签名。

感谢 tnorimat 为此工作贡献了重要部分。

除了签名 SPI 之外，现在还支持其他签名算法。

Keycloak 现在支持 RS256、RS384、RS512、ES256、ES384、ES512、HS256、HS384 和 HS512。

椭圆曲线数字签名算法 (ES256/384/512) 非常有趣，因为它们提供与 RSA 签名相似的安全属性，但使用的 CPU 明显更少。

HMAC (HS256/384/512) 在您不希望应用程序本身验证签名时也非常有用。 由于这些是对称签名，因此只有 Keycloak 能够验证签名，这要求应用程序使用令牌内省端点来验证令牌。

感谢 tnorimat 为此工作贡献了重要部分。

现在可以指定为 OpenID Connect 客户端颁发的令牌中的受众。 还支持在适配器端验证受众。

Keycloak 服务器已升级为使用 WildFly 13。 这意味着底层依赖项的更新以及配置中的一些更改。 我们现在还支持 WildFly 13 适配器，并且我们升级了 Cross-DC 设置的底层 JDG/Infinispan 服务器版本。 有关更多详细信息，请参见升级指南。

在 Node.js 中提供授权服务支持使得使用 Node.js 适配器进行细粒度的中央授权变得非常容易。

主机名 SPI 引入了一种更灵活的方式来配置 Keycloak 的主机名。 有两个内置提供程序。 第一个是 request，它使用请求标头来确定主机名。 第二个是 fixed，它允许配置固定主机名。 后者确保只能使用有效的主机名，并且还允许内部应用程序通过备用 URL 调用 Keycloak。

有关更多详细信息，请参阅服务器管理指南中的威胁缓解部分。

新添加的客户端身份验证器使用 X509 客户端证书和相互 TLS 来保护来自客户端的连接。 除此之外，Keycloak 服务器还验证客户端证书的 Subject DN 字段。

在此版本中，我们全面改进了策略评估性能，提高了可靠性和吞吐量。 我们所做的主要更改与尝试通过避免不必要的流程并在决策发生后立即收集决策来优化策略评估路径有关。 我们还在每个请求的基础上引入了策略决策缓存，避免了先前评估的策略的冗余决策。

我们还在研究其他缓存层，这些缓存层应该会带来更好的体验。 请参阅 KEYCLOAK-7952。

在以前的版本中，权限始终使用标准 OAuth2 响应从服务器返回，其中包含访问令牌和刷新令牌。 在此版本中，客户端可以使用 response_mode 参数来指定服务器应如何响应授权请求。 此参数接受两个值

keycloak-nodejs-connect（NodeJS 的适配器）现在支持基于服务器做出的决策来保护资源的构造。 新的构造允许用户使用细粒度的权限来保护其资源，如下所示

使用 Google 登录现在支持 hd 参数，以将 Google 登录限制为 Google 上的特定托管域。 当在身份提供商中指定此参数时，将拒绝来自不同域的任何登录。

感谢 brushmate 的贡献。

大多数 HTML 输出已经过 HTML 标记转义，但在某些地方允许使用 HTML 标记。 这些仅限于需要管理员访问权限才能更新值的位置。 即使更新此类字段需要管理员访问权限，我们也添加了额外的防御层，现在正在转义不安全元素，如 <script>。

我们现在支持在 Cordova 的 JavaScript 适配器中使用浏览器选项卡和通用链接。 这实现了多个应用程序之间的 SSO，并提高了安全性。

感谢 gtudan 的贡献。

SAML 适配器现在可以像 OpenID Connect 的内置适配器一样支持多租户。

在以前的版本中，无法使用包含点 (.) 字符的声明名称在令牌中创建声明。 现在可以转义配置中的点字符，因此可以使用带有点字符的声明名称。

从 4.1 版本开始，Spring Boot 启动器将基于 Spring Boot 2 适配器。 如果您使用的是较旧的 Spring Boot 版本，则可以使用 keycloak-legacy-spring-boot-starter。

我们添加了对客户端范围的支持，它取代了客户端模板。 客户端范围是一种更灵活的方法，并且还为 OAuth scope 参数提供了更好的支持。

与客户端范围相关的更改已应用于同意屏幕。 同意屏幕上的列表现在链接到客户端范围，而不是协议映射器和角色。

有关更多详细信息，请参见文档和迁移指南。

我们现在部分实现了规范 OAuth 2.0 相互 TLS 客户端身份验证和证书绑定访问令牌。 更准确地说，我们支持证书绑定访问令牌。 如果您的机密客户端能够使用双向 SSL，则 Keycloak 将能够将客户端证书的哈希添加到为客户端颁发的令牌中。 目前，只有 Keycloak 本身会验证令牌哈希（例如，在 refresh token 请求期间）。 我们计划也添加对适配器的支持。 我们还计划添加对相互 TLS 客户端身份验证的支持。

感谢 tnorimat 的贡献。

现在可以通过常规提供程序部署将主题热部署到 Keycloak。 我们还增加了对主题资源的支持，允许添加额外的模板和资源，而无需创建主题。 这对于需要将额外页面添加到身份验证流程的自定义身份验证器非常有用。

我们还增加了对覆盖特定客户端主题的支持。 如果这不能满足您的需求，那么还有一个新的主题选择器 SPI，允许您实现自定义逻辑来选择主题。

我们增加了对使用 Instagram 登录的支持。 感谢 hguerrero 的贡献。

以前要在管理控制台中按 ID 搜索用户，您必须编辑 URL。 现在可以直接在用户搜索字段中搜索。