keycloak 原生不支持基于登录空闲时长自动禁用用户，但可通过调用 admin rest api 结合定时任务实现该功能：获取用户最后登录时间、比对阈值、调用 api 禁用超期账户，并可集成事件监听机制。
keycloak 原生不支持基于登录空闲时长自动禁用用户，但可通过调用 admin rest api 结合定时任务实现该功能：获取用户最后登录时间、比对阈值、调用 api 禁用超期账户，并可集成事件监听机制。
在企业级身份管理实践中，定期清理长期未活跃的账户是安全合规（如 ISO 27001、GDPR）的重要要求。Keycloak 当前（截至 v24.x）未内置“空闲 N 天后自动禁用用户”功能，官方相关需求（如 KEYCLOAK-5865 和 GH #11800）仍处于社区讨论或待实现状态。因此，需通过外部自动化服务自主实现。
实现原理概览
核心逻辑为周期性执行以下步骤：
- 调用 Keycloak Admin REST API 获取指定 Realm 下所有启用用户；
- 查询每个用户的 lastLogin 时间戳（需启用 User Session Stats 或依赖 events 表，见下文说明）；
- 计算距今空闲天数，与预设阈值（如 50 天）比较；
- 对超期用户调用 PUT /admin/realms/{realm}/users/{id}，将 enabled 字段设为 false；
- （可选）触发自定义审计事件或记录日志，供后续监控与溯源。
⚠️ 注意：Keycloak 默认 不持久化 lastLogin 到用户实体。lastLogin 仅存在于内存中的用户会话（Session）中，会话过期即丢失。因此生产环境推荐两种可靠方案：
- ✅ 启用 User Session Stats（推荐）：在 Keycloak 管理控制台 → Realm Settings → Events → Config → 启用 User Session Stats（需 Keycloak ≥ 19.0.3），并确保 events 存储已配置（如使用数据库存储事件）。此时可通过 /admin/realms/{realm}/users/{id}/sessions 接口获取最近会话，取最新 startTime 作为近似 lastLogin。
- ✅ 结合审计事件表（Events DB）：若已开启 Admin Events 或 User Events 并写入数据库，可直接查询 event_entity 表中类型为 LOGIN 的最新记录。
示例：Python 定时禁用脚本（基于 Admin API）
import requests
import os
from datetime import datetime, timedelta
# 配置参数（建议从环境变量读取）
KEYCLOAK_URL = os.getenv("KEYCLOAK_URL", "http://localhost:8080")
REALM = os.getenv("KEYCLOAK_REALM", "myrealm")
CLIENT_ID = os.getenv("KEYCLOAK_CLIENT_ID", "admin-cli")
CLIENT_SECRET = os.getenv("INACTIVITY_THRESHOLD_DAYS", "50")
def get_admin_token():
token_url = f"{KEYCLOAK_URL}/realms/master/protocol/openid-connect/token"
data = {
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"grant_type": "client_credentials"
}
resp = requests.post(token_url, data=data)
resp.raise_for_status()
return resp.json()["access_token"]
def disable_inactive_users(threshold_days=50):
token = get_admin_token()
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
# Step 1: 获取所有启用用户（分页处理）
users_url = f"{KEYCLOAK_URL}/admin/realms/{REALM}/users?enabled=true&max=1000"
users_resp = requests.get(users_url, headers=headers)
users_resp.raise_for_status()
users = users_resp.json()
cutoff_time = datetime.now() - timedelta(days=threshold_days)
for user in users:
# Step 2: 获取该用户最近一次会话（需已启用 User Session Stats）
sessions_url = f"{KEYCLOAK_URL}/admin/realms/{REALM}/users/{user['id']}/sessions"
sess_resp = requests.get(sessions_url, headers=headers)
if sess_resp.status_code == 200 and sess_resp.json():
latest_session = max(sess_resp.json(), key=lambda s: s.get("startTime", 0))
last_login_ts = int(latest_session["startTime"]) / 1000 # ms → sec
last_login = datetime.fromtimestamp(last_login_ts)
if last_login < cutoff_time:
# Step 3: 禁用用户
disable_url = f"{KEYCLOAK_URL}/admin/realms/{REALM}/users/{user['id']}"
requests.put(disable_url, headers=headers, json={"enabled": False})
print(f"Disabled user {user['username']} (last login: {last_login.date()})")
if __name__ == "__main__":
disable_inactive_users(threshold_days=50)部署与运维建议
- 定时调度：使用 cron（Linux）、Windows Task Scheduler 或 Kubernetes CronJob 每日执行一次；
- 权限最小化：专用服务客户端仅授予 view-users 和 manage-users 角色，避免过度授权；
- 错误处理与告警：脚本中应加入重试机制、HTTP 错误码判断（如 401 Token 过期）、失败用户日志记录，并对接邮件/PagerDuty 告警；
- 事件可观测性：禁用操作本身不会自动产生 USER_DISABLED 事件；如需审计，可在脚本中手动调用 POST /admin/realms/{realm}/events 发送自定义事件；
- 灰度与回滚：首次上线建议先以 dry-run 模式运行（仅打印将被禁用的用户），确认逻辑无误后再启用真实操作。
通过上述方案，你可在 Keycloak 生态中稳健落地用户生命周期安全管理策略，兼顾安全性、可维护性与合规性要求。
