如何配置Keycloak使JWT的sub Claim填充用户名而非默认用户ID？

我之前也碰到过一模一样的问题！直接新增Username映射器确实会生成重复的sub声明——因为Keycloak默认已经内置了一个基于用户ID的sub映射，两个映射器同时生效就会导致JWT出现重复键值对，自然无效。正确的做法是修改默认的sub映射器，而不是新增一个，具体步骤如下：

步骤1：进入目标客户端的映射器配置 #

• 登录Keycloak管理控制台，找到你的目标Realm（领域）
• 点击左侧菜单的Clients（客户端），选中需要配置的客户端
• 切换到Mappers（映射器）标签页

步骤2：定位默认的sub映射器 #

在映射器列表里，你会看到一个名为sub的内置映射器（类型为User Property），它的作用是把用户的id字段映射到sub声明里。

步骤3：修改默认sub映射器的属性 #

点击这个sub映射器进入编辑页面：

• 把Property（属性）字段从id修改为username
• 保持其他配置不变：Token Claim Name依然是sub，Claim JSON Type选择String，同时勾选Add to ID token和Add to access token
• 点击Save保存修改

步骤4：验证结果 #

现在重新获取JWT，你会发现sub的值已经替换为用户名，且不会出现重复的sub声明，完全符合你的期望格式：

{ "jti": "b1384883-9b59-4788-b09f-98b40b7e3c3b", ... "sub": "m123456", "preferred_username": "m123456" }

额外提醒 #

• 如果你使用的是Keycloak 17+的Quarkus版本，操作路径完全一致，没有版本差异
• 确保你的用户username字段是全局唯一的，毕竟sub作为JWT的核心标识符，需要保证唯一性

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