2.6. 其它更改

org.keycloak.representations.idm.UserRepresentation s.keycloak.representations.account.UserRepresentation representation 类都已更改，以便 root 用户属性（如用户名、电子邮件、firstName、lastName 和 locale）在获取或将表示有效负载发送到 Admin 和 Account API 时具有一致的表示。

用户名、mail、firstName、lastName 和 locale 属性被移到一个新的 org.keycloak.representations.idm.AbstractUserRepresentation 基础类。

另外，getAttributes 方法只代表自定义属性，因此您不应该期望此方法返回的映射中的任何 root 属性。当为给定用户更新或获取任何自定义属性时，此方法主要针对客户端。

为了解析包括 root 属性的所有属性，添加了一个新的 getRawAttributes 方法，以便生成的映射也包含 root 属性。但是，此方法不能从表示有效负载中获得，它的目标是在管理用户配置文件时供服务器使用。

选项 https-client-auth 已被视为运行时选项，但 Quarkus 不支持它。选项需要改为在构建时进行处理。

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

之前的代码在启动时导致集群中资源消耗高，在生产环境中分析非常困难，并可能导致在加载过程中重启节点时出现复杂的故障场景。因此，它被改为后续会话加载。

对于离线会话，这个和之前版本的 Keycloak 默认是根据需要加载这些会话，与尝试并行加载它们相比，这个会话可以更好地扩展。使用此默认设置的设置不受加载策略更改离线会话的影响。启用离线会话预加载的设置应该迁移到禁用 offline-session 预加载的设置。

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

vendor_cache_manager_keycloak_cache_sessions_statistics_approximate_entries_in_memory{cache="sessions",node="..."}

vendor_statistics_approximate_entries_in_memory{cache="sessions",cache_manager="keycloak",node="..."}

要恢复安装的更改，请使用自定义 Infinispan XML 配置并更改配置，如下所示：

<metrics names-as-tags="false" />

在这个版本中，Red Hat build of Keycloak 支持按用户属性值的存储和搜索，其比 255 个字符长，这之前是一个限制。

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

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

此更改在表 USER_ATTRIBUTE 和 FED_USER_ATTRIBUTE 上添加新的索引。如果这些表包含 300000 项，Red Hat build of Keycloak 会在自动模式迁移过程中默认跳过索引创建，而是在迁移过程中在控制台上记录 SQL 语句，以便在红帽构建 Keycloak 的启动后手动应用。有关如何配置不同的限制的详情，请参阅 升级指南。

PUT /admin/realms/{realm}/users/{id}/send-verify-email

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

Perform the following action(s): Verify Email

Confirm validity of e-mail address email@example.org.

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

将引入一个名为 lifespan 的新参数，以允许覆盖默认的寿命值(12 小时)。

如果您更喜欢之前的行为，请使用 execute-actions-email API，如下所示：

PUT /admin/realms/{realm}/users/{id}/execute-actions-email

["VERIFY_EMAIL"]

在本发行版本中，我们调整了密码散列默认为与密码 存储 的 OWASP 建议 匹配。

作为此更改的一部分，默认密码散列提供程序已从 pbkdf2-sha256 改为 pbkdf2-sha512。另外，基于 pbkdf2 的密码哈希算法的默认哈希迭代数量更改，如下所示：

如果域没有使用 hashAlgorithm 和 hashIterations 明确配置密码策略，则新配置将根据登录或创建或更新用户密码时生效。

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

现在，当用户被 brute 强制保护程序暂时锁定时，新的事件 USER_DISABLED_BY_TEMPORARY_LOCKOUT。ID KC-SERVICES0053 的日志已被删除，因为新事件以结构化的形式提供信息。

由于它是成功事件，新事件默认记录在 DEBUG 级别。使用设置 spi-events-listener-jboss-logging-success-level，如 Server Administration Guide 中的 Event listener 章节 所述，来更改所有成功事件的日志级别。

要触发自定义操作或自定义日志条目，请编写自定义事件监听程序，如 Server Developer Guide 中的 Event Listener SPI 所述。

如果您要直接从红帽构建的 Keycloak JS 加载 Keycloak JS，则可以安全地忽略本节。如果您要从 NPM 软件包加载 Keycloak JS，并使用如 Webpack、Vite 等捆绑包程序，您可能需要对代码进行一些更改。Keycloak JS 软件包现在使用 package.json 文件中的 exports 字段。这意味着您可能需要更改导入：

// Before
import Keycloak from 'keycloak-js/dist/keycloak.js';
import AuthZ from 'keycloak-js/dist/keycloak-authz.js';

// After
import Keycloak from 'keycloak-js';
import AuthZ from 'keycloak-js/authz';

红帽构建的 Keycloak 用来为内部令牌签名（由红帽构建的 Keycloak 本身使用的 JWT，如刷新或操作令牌）已从 HS256 改为更安全的 HS512。现在为域添加了名为 hmac-generated-hs512 的新密钥提供程序。请注意，在迁移的域中，旧的 hmac-generated 供应商和旧的 HS256 密钥会被维护，并仍然验证升级前发布的令牌。当不存在更多旧令牌时，可以手动删除 HS256 提供程序。https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/24.0/html-single/server_administration_guide/#rotating-keys

在容器中运行时，JVM 选项 -Xms 和 -Xmx 被 -XX:InitialRAMPercentage 和 -XX:MaxRAMPercentage 替代。红帽构建的 Keycloak 而不是静态最大堆大小设置，指定容器内存总量的 70%。

由于堆大小根据容器内存总量动态计算，您应该始终为容器设置内存限值。

如需了解更多详细信息，请参阅 指定不同的内存设置。

RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 规格添加 该参数 在 OAuth 2.0/OpenID Connect Authentication Response 中用于实现安全授权响应。

在过去的版本中，我们没有这个参数，但现在红帽构建的 Keycloak 会默认添加这个参数。

但是，一些 OpenID Connect / OAuth2 适配器，特别是较旧的红帽构建的 Keycloak 适配器，这个新参数可能会出现问题。

例如，参数在成功向客户端应用程序进行身份验证后始终存在于浏览器 URL 中。在这些情况下，禁用向身份验证响应添加 iss 参数可能很有用。这可以为红帽构建的 Keycloak 管理控制台中的特定客户端完成，在带有 OpenID Connect Compatibility Modes 的小节中的客户端详情中，如 第 4.1 节 “与旧适配器兼容” 所述。专用 Exclude Issuer From Authentication Response 开关存在，可以打开以防止将 iss 参数添加到身份验证响应中。

JPA 在搜索时允许通配符 % 和 _，而 LDAP 等其他供应商只允许 X。因为 * 是 LDAP 中的自然通配符字符，它在所有位置工作，而 JPA 则仅在搜索字符串的开头和结尾工作。从这个版本开始，唯一的通配符字符是 *，它在搜索字符串中的所有位置都一致地工作。对于 JPA，特定供应商（如 % 和 _ ）中的所有特殊字符都会被转义。对于确切搜索，带有添加的引号，如 "w*ord"，行为与之前版本中的行为相同。

在此版本之前，域(User Realm Role)和客户端(User Client Role)协议映射器在禁用 Multivalued 设置时映射了一个字符串fied JSON 数组。

但是，Multivalued 设置指示声明应映射为列表，如果禁用，则只有来自相同值列表中的单个值。

在这个发行版本中，当角色和客户端映射器标记为单值时，角色和客户端映射器现在从用户的有效角色映射到单个值(多值 禁用)。

在这个版本中，我们需要引入隐藏/显示密码输入的切换。

一般情况下，所有 <input type="password" name="password" /& gt; 现在被封装在一个 div 中。input 元素后跟一个按钮，用于切换密码输入的可见性。

旧代码示例：

<input type="password" id="password" name="password" autocomplete="current-password" style="display:none;"/>

新代码示例：

<div class="${properties.kcInputGroup!}">
    <input type="password" id="password" name="password" autocomplete="current-password" style="display:none;"/>
    <button class="pf-c-button pf-m-control" type="button" aria-label="${msg('showPassword')}"
            aria-controls="password" data-password-toggle
            data-label-show="${msg('showPassword')}" data-label-hide="${msg('hidePassword')}">
        <i class="fa fa-eye" aria-hidden="true"></i>
    </button>
</div>

kc.sh 不再使用额外的 shell 评估参数，环境变量 JAVA_OPTS_APPEND 和 JAVA_ADD_OPENS，因此继续使用双转义/仲裁将导致参数被误解。例如，而不是

bin/kc.sh start --db postgres --db-username keycloak --db-url "\"jdbc:postgresql://localhost:5432/keycloak?ssl=false&connectTimeout=30\"" --db-password keycloak --hostname localhost

使用单个转义：

bin/kc.sh start --db postgres --db-username keycloak --db-url "jdbc:postgresql://localhost:5432/keycloak?ssl=false&connectTimeout=30" --db-password keycloak --hostname localhost

此更改还意味着您无法使用带带所有参数的单个值来调用 kc.sh。例如，您无法再使用

bin/kc.sh "start --help"

它必须是单独的参数

bin/kc.sh start --help

同样地而不是，

bin/kc.sh build "--db postgres"

它必须是单独的参数

bin/kc.sh build --db postgres

Dockerfile 运行命令中还需要使用各个参数。

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

Stream<GroupModel> getTopLevelGroupsStream(RealmModel realm,
                                           String search,
                                           Boolean exact,
                                           Integer firstResult,
                                           Integer maxResults)

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

依赖 RESTEasy Classic 不再是一个选项，因为它不再可用。依赖于 RESTEasy Classic 和相关软件包部分的 SPI 和相关软件包部分需要迁移。

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

在将重定向 URI 与客户端指定有效重定向进行比较时，1.8.0 为主机名和方案引入了小写。不幸的是，它并不在所有协议中完全工作，例如，主机对于 http 来说较低，但不适用于 https。因为 OAuth 2.0 安全最佳实践 建议使用准确字符串匹配比较 URI，Red Hat build of Keycloak 遵循建议，且在有效重定向中会按照具体情况进行比较，即使主机名和方案也是如此。

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

虽然它在配置客户端时引入了更多步骤和详细程度，但新行为可以启用更安全的部署，因为基于模式的检查经常造成安全问题。不仅是由于它们的实施方式，也只是配置它们的方式。

版本 23.0.0 在 Groups 资源上引入了一个新的端点 getSubGroups ("children")，其中参数 briefRepresentation 表示检索子组的完整表示。现在，这个含义已被修改来返回简短表示。

jboss-logging 消息值现已加引号（默认为 " 字符"），而 sanitized 以防止任何换行符。供应商中有两个新选项(spi-events-listener-jboss-logging-sanitize 和 spi-events-listener-jboss-logging-quotes)，允许您自定义新行为。例如，为了避免清理和引用，可以以这种方式启动服务器：

./kc.sh start --spi-events-listener-jboss-logging-sanitize=false --spi-events-listener-jboss-logging-quotes=none ...

有关选项的更多信息，请参阅 所有供应商配置。