如何定期同步Keycloak与Entra ID并清理无效用户？

核心方向 #

要解决Keycloak中残留Azure AD已删除用户的问题，核心是定期比对两边的用户列表，清理Keycloak里的无效账号，下面是几种可行的落地方案：

方案1：自定义Keycloak定时任务SPI #

利用Keycloak的SPI扩展机制开发内置定时任务，是最贴合Keycloak生态的方案：

• 开发JobSchedulerProvider SPI实现，配置触发周期（比如每天凌晨跑一次）
• 任务逻辑：
  1. 调用Microsoft Graph API拉取Azure AD中所有有效用户（过滤掉已删除、禁用的账号）
  2. 在Keycloak里筛选出所有关联该Azure AD身份提供商的用户（通过用户的identityProvider属性或IDP关联标识判断）
  3. 比对两个列表，找出Keycloak有但Azure AD没有的用户
  4. 执行清理：直接删除、标记禁用或设置过期时间，根据业务需求选择
• 注意点：
  • 给Keycloak的服务主体配置Azure AD的User.Read.All权限，确保能读取全量用户
  • 处理分页：用户量大时Graph API会分页返回，要循环拉取所有数据
  • 增加异常处理：API调用失败、网络波动时记录日志，支持重试机制

方案2：外部定时脚本（轻量快速） #

不想修改Keycloak代码的话，用外部脚本结合两个平台的API是最快的落地方式：

• 用Python/Shell/Go编写脚本，通过Linux cron、Windows任务计划设置定时执行
• 脚本步骤：
  1. 调用Microsoft Graph API获取Azure AD有效用户列表，提取和Keycloak同步一致的唯一标识（比如userPrincipalName或id）
  2. 调用Keycloak Admin API获取所有关联该Azure AD IDP的用户
  3. 比对生成待清理的用户清单
  4. 调用Keycloak Admin API删除或禁用这些用户
• 优势：开发周期短，无需改动Keycloak核心代码，调试维护灵活
• 注意点：
  • 妥善保管Keycloak Admin账号和Azure AD应用密钥，避免泄露
  • 加入日志记录和告警机制，同步失败时及时通知管理员

方案3：自定义用户存储SPI（深度集成） #

如果对数据一致性要求极高，可以将Keycloak的用户存储直接绑定到Azure AD：

• 实现UserStorageProvider，让Keycloak查询用户时直接从Azure AD获取数据，本地仅做缓存
• 这种模式下不存在本地用户与Azure不同步的问题，但要做好缓存策略，避免频繁调用API影响性能
• 适合对数据一致性要求苛刻的场景，不过开发和维护成本相对较高

方案选择建议 #

• 有Keycloak开发经验：优先选择自定义定时任务SPI，集成度高，符合Keycloak生态
• 追求快速落地：选择外部定时脚本，开发成本低，灵活可控
• 数据一致性要求极高：考虑用户存储SPI，但需提前评估开发与维护成本

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