keycloak 原生不支持按登录非活跃时长自动停用用户，但可通过调用 admin rest api 结合定时任务实现该功能：创建专用管理客户端、获取访问令牌、查询用户最后登录时间并禁用超期账户。
keycloak 原生不支持按登录非活跃时长自动停用用户，但可通过调用 admin rest api 结合定时任务实现该功能：创建专用管理客户端、获取访问令牌、查询用户最后登录时间并禁用超期账户。
在企业级身份管理实践中，出于安全合规要求（如 GDPR、等保 2.0），常需对长期未登录的用户账户执行自动停用（disable）操作——例如，用户连续 50 天未登录即冻结其认证能力，而非直接删除。遗憾的是，Keycloak 官方截至 v24.x 版本仍未内置“基于非活跃期自动停用用户”的功能。社区中长期存在相关需求（如 KEYCLOAK-5865 和 GH#11800），但目前仍需通过外部集成方式自主实现。
✅ 实现原理概览
核心思路是：构建一个可调度的后台服务（如 Cron Job、Spring Boot Scheduler 或独立脚本），周期性调用 Keycloak Admin REST API，识别并禁用满足条件的用户。整个流程包含三步关键操作：
-
配置受信管理客户端（Client）
在目标 Realm 中创建专用客户端（如 user-inactivity-manager），启用 Client Authentication，并为其分配最小必要权限角色：- manage-users（用于更新用户状态）
- view-users（用于读取用户属性及登录事件）
⚠️ 注意：避免使用 admin-cli 客户端或 realm-admin 用户凭据，遵循最小权限原则。
获取管理员访问令牌
使用 client_credentials 流获取具有上述角色权限的 bearer token：
curl -X POST \ "https://keycloak.example.com/auth/realms/master/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "client_id=user-inactivity-manager" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "grant_type=client_credentials"
-
查询 & 禁用非活跃用户
利用 Admin API 查询用户列表，并结合 lastLogin 时间戳（需确保已启用用户会话日志）判断是否超期。Keycloak 用户资源本身不直接暴露 lastLogin 字段，需通过 /admin/realms/{realm}/users/{id}/sessions 或更可靠的方式——查询用户最近一次成功登录事件（LOGIN 类型）：
# 获取用户最近 1 条 LOGIN 事件（按时间倒序） curl -X GET \ "https://keycloak.example.com/auth/admin/realms/myrealm/events?clientId=myapp&type=LOGIN&user=USER_ID&max=1&first=0" \ -H "Authorization: Bearer $TOKEN" \ -H "Accept: application/json"
若事件为空或最新 LOGIN 时间早于当前时间减去阈值（如 50 天），则调用禁用接口：
# 禁用用户：PATCH /admin/realms/{realm}/users/{id}
curl -X PATCH \
"https://keycloak.example.com/auth/admin/realms/myrealm/users/USER_ID" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'? 关键注意事项
- 事件存储依赖：/events 端点仅返回启用了 Events 配置（Realm Settings → Events → Enabled = ON）且未过期的事件；建议同步开启 Admin Events 并设置合理保留周期（如 90 天）。
- 性能优化：对大规模用户（>10k），避免全量遍历 /users。可改用 /users?search= + 分页，或结合自定义用户属性（如 inactivity_check_enabled: true）过滤目标用户。
- 幂等与审计：每次执行前记录操作日志（被禁用用户 ID、原因、时间戳），并在禁用前发送通知（如邮件或 webhook），确保可追溯、可回滚。
- 事件监听补充：虽然无法直接订阅“自动禁用”事件（因属外部操作），但可通过 Keycloak 的 EventListenerProvider 扩展，在 UserDisabledEvent 触发时做后续处理（如同步至 HR 系统）。
✅ 总结
尽管 Keycloak 尚未将“非活跃用户自动停用”作为开箱即用特性提供，但凭借其成熟的 Admin REST API 与灵活的扩展机制，完全可构建健壮、可审计、符合安全策略的自动化治理方案。推荐以容器化定时任务（如 Kubernetes CronJob + Python/Java 脚本）落地，并纳入 CI/CD 流水线统一管理配置与凭证。此举不仅提升系统安全性，也为企业合规建设提供坚实支撑。
