keycloak 原生不支持基于登录空闲时长自动禁用用户，但可通过调用 admin rest api 结合定时任务（如 cron job 或 spring boot scheduler）实现该功能：获取用户最后登录时间，对比阈值后禁用超期账户，并可将操作记录为管理事件。
keycloak 原生不支持基于登录空闲时长自动禁用用户，但可通过调用 admin rest api 结合定时任务（如 cron job 或 spring boot scheduler）实现该功能：获取用户最后登录时间，对比阈值后禁用超期账户，并可将操作记录为管理事件。
在现代身份认证系统中，定期清理长期未活跃的用户账户是保障安全合规的重要实践。尽管 Keycloak 15.0+ 版本提供了丰富的用户生命周期管理能力（如强制密码过期、临时锁定等），但原生并不支持“X 天未登录即自动禁用账户”这一策略——该需求曾被多次提交至官方 Issue 跟踪（如 KEYCLOAK-5865 和 GH#11800），目前仍需通过外部服务自主实现。
实现原理概览
核心逻辑分为三步：
- 身份认证：创建专用 Admin Client，使用 client_credentials 流获取访问令牌；
- 数据查询与判断：调用 /admin/realms/{realm}/users 接口分页获取用户，并通过 lastLogin 时间戳（单位：毫秒）计算空闲天数；
- 状态更新：对满足条件（如 now - lastLogin > 50 * 24 * 3600 * 1000）的用户，PATCH 其 enabled: false 字段完成禁用。
⚠️ 注意：lastLogin 字段仅在用户成功登录后由 Keycloak 自动更新，且默认不返回于标准用户列表响应中。需显式添加 first、max 参数并启用 briefRepresentation=false，或更可靠地——单独调用 /admin/realms/{realm}/users/{id}/session（需 view-users 权限）或依赖审计日志（见下文补充说明）。实践中推荐结合 Keycloak 的 Events Log（需开启 Admin Events 和 Events 并配置 login 类型）做二次校验。
示例：Python 定时脚本（含错误处理与日志）
import requests
import time
from datetime import datetime, timedelta
# 配置项（建议从环境变量读取）
KEYCLOAK_URL = "https://auth.example.com"
REALM = "my-realm"
CLIENT_ID = "inactivity-manager"
CLIENT_SECRET = "xxxxxx"
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, timeout=10)
resp.raise_for_status()
return resp.json()["access_token"]
def disable_inactive_users():
token = get_admin_token()
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
users_url = f"{KEYCLOAK_URL}/admin/realms/{REALM}/users"
# 分页获取所有用户（关键：必须设置 briefRepresentation=false 才可能含 lastLogin）
params = {"max": 100, "first": 0, "briefRepresentation": "false"}
resp = requests.get(users_url, headers=headers, params=params, timeout=15)
resp.raise_for_status()
users = resp.json()
cutoff_time = int((datetime.now() - timedelta(days=INACTIVITY_THRESHOLD_DAYS)).timestamp() * 1000)
disabled_count = 0
for user in users:
# lastLogin 可能为 None 或缺失，需防御性检查
last_login = user.get("lastLogin")
if last_login and isinstance(last_login, (int, float)) and last_login < cutoff_time:
try:
# PATCH 用户：禁用账户
update_url = f"{KEYCLOAK_URL}/admin/realms/{REALM}/users/{user['id']}"
requests.patch(update_url, headers=headers, json={"enabled": False}, timeout=10)
print(f"✅ Disabled user {user['username']} (last login: {datetime.fromtimestamp(last_login/1000)})")
disabled_count += 1
except Exception as e:
print(f"❌ Failed to disable {user['username']}: {e}")
print(f"? Total disabled: {disabled_count}")
if __name__ == "__main__":
disable_inactive_users()关键注意事项
- ✅ 权限最小化原则：Admin Client 仅需 manage-users（修改用户状态）和 view-users（读取信息）角色，避免授予 realm-admin 全局权限；
- ✅ 事件可观测性：禁用操作本身会触发 USER_UPDATED Admin Event（需在 Realm Settings → Events → Admin Events 中启用），可用于审计追踪；若需更细粒度日志（如“因50天未登录被禁用”），建议在脚本中主动调用 /admin/realms/{realm}/events POST 接口写入自定义事件；
- ⚠️ 性能与分页：用户量大时务必实现全量分页遍历（first + max 循环），避免单次请求超时或内存溢出；
- ⚠️ 时区一致性：lastLogin 为 UTC 时间戳，确保服务端系统时间同步（NTP），避免因本地时区偏差导致误判；
- ? 调度建议：生产环境推荐使用 Kubernetes CronJob、Airflow 或 Quartz 等成熟调度器，而非简单 crontab，以保障高可用与失败重试。
通过上述方案，您即可在 Keycloak 生态中稳健落地用户非活跃自动治理策略，在不侵入核心代码的前提下，兼顾安全性、可维护性与可观测性。
