Keycloak与Entra ID（OIDC）组同步问题及配置排查

当前配置可能存在的问题 #

• Entra ID组声明返回范围错误：可能配置成返回所有可用组，而非用户实际被分配的组，导致Keycloak拿到全量组数据后同步给用户。
• Keycloak角色映射规则不精准：声明到角色的映射未设置匹配条件，比如未指定仅当组ID匹配特定值时才映射对应角色，导致所有角色都被赋予用户。
• 默认组配置不当：将多个与Entra ID同名的组设为默认组，Keycloak会自动把默认组加入所有登录用户，覆盖了同步的组逻辑。
• 未启用精准组同步：仅配置了角色映射，未开启Keycloak与Entra ID的组同步功能，或同步规则未绑定具体组ID对应关系。

实现组同步的正确步骤 #

1. 修正Entra ID的组声明配置 #

• 进入Entra ID企业应用的令牌配置，编辑组声明：
  • 选择“安全组”作为声明类型，设置“组ID”为返回值（与Keycloak中关联的组ID一致）。
  • 勾选“仅返回已分配给应用程序的组”，确保只返回用户实际所属的组。
  • 确认声明名称（如groups）与Keycloak身份提供者中配置的声明名称一致。

2. 调整Keycloak的身份提供者配置 #

• 精准配置角色映射：
  在OIDC身份提供者的声明映射 → 角色中，为每个Realm角色添加映射规则：
  • 选择“用户属性或声明”作为来源，输入组声明名称（如groups）。
  • 设置匹配条件为“等于”，填入对应的Entra ID组ID，目标选择对应的Realm角色。确保每个规则仅对应一个组ID和角色。
• 启用并配置组同步：
  进入身份提供者的同步选项卡：
  • 开启“同步用户组”，同步模式选择“强制同步”（会移除用户在Keycloak中未出现在Entra ID的组）或“导入”（仅添加新组，保留现有组）。
  • 在组映射中，添加条目：输入Entra ID的组ID，选择Keycloak中对应的目标组，确保一一对应。
• 清理默认组：
  进入Keycloak的组管理，取消多个组的“默认”标记，仅保留必要的通用默认组（如无特殊需求可完全关闭默认组）。

3. 验证与测试 #

• 删除Keycloak中测试用户的所有组，重新登录该用户，检查用户所属组是否与Entra ID中分配的组一致。
• 查看Keycloak服务器日志，确认身份提供者返回的groups声明仅包含用户实际所属的组ID。
• 验证角色权限：用户仅拥有其所属组对应的Realm角色，而非全部角色。

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