Keycloak默认角色、OIDC令牌及角色继承异常的技术咨询

关于default-roles-qms的核心问题 #

1. 具体作用 #

这个默认角色是Keycloak为每个Realm自动生成的基础角色，核心作用包括：

• 绑定Realm级基础权限，允许用户访问Keycloak自带的account客户端（用于查看/修改个人信息）
• 作为新用户的默认角色映射，确保所有用户刚创建时就拥有Realm的基础访问能力
• 承载Realm层面的通用权限，无需为每个用户手动配置基础权限

2. 无法编辑/设置其他角色为默认的原因 #

• 它是Keycloak系统级预定义角色，关联了account客户端的默认权限，属于Realm运行的基础依赖，因此禁止删除或编辑
• Keycloak原生不支持将自定义角色设为Realm默认角色，因为默认角色的逻辑与Realm基础权限深度绑定，自定义角色无法替代其系统级作用

3. 必须存在的原因 #

它是Keycloak内部权限体系的基础，缺失会导致：

• 用户无法访问Keycloak的account管理页面
• OIDC令牌缺失与Realm基础权限相关的字段（如你遇到的aud: account和resource_access）
• 新用户创建后无任何默认权限，认证后无法完成基础操作

移除默认角色后令牌属性缺失的原因 #

当你移除用户的default-roles-qms角色映射后，令牌缺失对应属性的核心原因：

• default-roles-qms直接关联account客户端的访问权限，没有该角色，Keycloak不会将account加入令牌的aud（受众）字段
• resource_access用于承载客户端级角色权限，用户无account权限时，自然不会生成对应的resource_access对象
• 若你的QMS微服务依赖这些字段做授权校验，必须保留用户的default-roles-qms角色映射

新用户意外继承manager角色的解决方法 #

排查与修复步骤 #

1. 检查Realm默认角色配置：进入QMS Realm的「Users」→「Default Roles」，确认仅default-roles-qms在默认角色列表中（Keycloak原生不支持自定义默认角色，大概率是配置失误）
2. 检查用户组映射：若存在绑定manager角色的用户组，且新用户被自动加入该组，就会继承角色。逐个检查所有用户组的「Role Mappings」，移除不必要的角色绑定
3. 检查身份提供者配置：如果使用LDAP等外部身份源，核对同步规则，避免自动为新用户分配manager角色
4. 检查自定义脚本：若存在Realm层面的用户创建钩子脚本，排查是否因逻辑错误导致manager角色被自动添加

将developer设为默认角色的替代方案 #

Keycloak原生不支持替换Realm默认角色，但可通过以下方式实现类似效果：

• 创建一个用户组，将developer角色映射到该组
• 在Realm的「User Federation」或「Authentication」流程中添加自定义动作，让新用户创建时自动加入该组
• 这样新用户会同时拥有default-roles-qms和developer角色，满足你的低优先级需求

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