如何设置Keycloak的user id为静态值及通过旧ID查询用户邮箱

首先明确核心前提：默认配置下Keycloak的用户实体ID（即access token中标准的sub声明值）是用户创建时生成的永久静态UUID，不会随时间、登录状态自动变更。你遇到的ID定期变动问题，基本都是取值错误或配置偏差导致，对应两个问题的解决方案如下：

如何获取/设置固定不变的用户ID #

• 先排查取值错误：不要把access token中的sid（会话ID，每次登录/刷新token都会变更）、临时会话标识错当成用户ID。标准OIDC流程中，固定使用sub字段作为用户唯一标识即可，这个值和用户实体生命周期绑定，用户不被删除重建就永远不会变。
• 检查用户联邦配置：如果你的用户来自LDAP、第三方身份源同步，进入对应User Federation配置页，关闭「同步时重新生成用户本地ID」的选项，选择固定使用Keycloak本地生成的UUID作为主键，或者绑定身份源中永久不变的唯一字段（比如员工号）作为用户ID映射，避免每次同步触发ID变更。
• 自定义固定用户ID：如果需要使用业务侧指定的ID作为Keycloak用户ID，调用Keycloak Admin API创建用户时，直接在请求体中传入自定义的id字段即可，后续该用户的ID会永久固定为你传入的值，不会自动修改。不要直接修改线上Keycloak数据库中已存在用户的ID字段，会导致用户权限、会话、关联属性全部失效。

如何通过历史旧用户ID查询对应邮箱 #

• 如果你开启了Keycloak的事件日志：进入Realm设置中的Events页面，筛选用户相关的操作日志，旧ID对应的用户创建、信息修改、登录记录中都会留存当时绑定的邮箱信息。
• 如果你有Keycloak数据库的定期备份：直接查询备份中user_entity表，匹配旧ID对应的行，email字段就是该用户当时绑定的邮箱地址。
• 无日志无备份的场景：排查自身业务库的历史数据，查找和旧user id关联存储的操作记录，通常会有用户名、邮箱等冗余信息可以关联匹配；也可以检索Keycloak的服务运行日志，用户登录、触发个人信息变更时的日志通常会同时打印用户ID和邮箱字段。

后续做业务数据统计时，建议在存储user id的同时冗余存储用户名、邮箱这类固定可读标识，就算出现ID配置异常，也能快速通过冗余字段关联到正确用户，避免统计数据失效。

内容的提问来源于stack exchange，提问作者tandathuynh148