Comprehensive administrative tools for managing users, sessions, and Keycloak sync operations.
ObjKeycloakAdmin provides a powerful CLI for system administrators to manage user accounts, sessions, and Keycloak synchronization. Supports bulk operations, emergency modes, and detailed system statistics.
✅ User management (enable, disable, password reset)
✅ Bulk user operations
✅ Session inspection and management
✅ Force logout capabilities
✅ Sync queue management
✅ Emergency mode toggle
✅ System statistics and reporting
✅ Rich terminal UI with tables and colors
✅ Comprehensive audit logging
Requires additional dependencies:
pip install rich
# List active users
python factory.web/ObjKeycloakAdmin.py users homechoice
# Search for users
python factory.web/ObjKeycloakAdmin.py users homechoice --search "john"
# Include inactive users
python factory.web/ObjKeycloakAdmin.py users homechoice --all
# Limit results
python factory.web/ObjKeycloakAdmin.py users homechoice --limit 50
# Disable user with confirmation
python factory.web/ObjKeycloakAdmin.py disable john.doe homechoice
# Force disable without confirmation
python factory.web/ObjKeycloakAdmin.py disable john.doe homechoice --force
# Include reason
python factory.web/ObjKeycloakAdmin.py disable john.doe homechoice \
--reason "Account suspended due to policy violation" --force
What happens:
# Enable disabled user
python factory.web/ObjKeycloakAdmin.py enable john.doe homechoice
What happens:
# Generate random password (temporary)
python factory.web/ObjKeycloakAdmin.py reset-password john.doe homechoice
# Set specific password
python factory.web/ObjKeycloakAdmin.py reset-password john.doe homechoice \
--password "NewSecureP@ss123"
# Set permanent password (no change required)
python factory.web/ObjKeycloakAdmin.py reset-password john.doe homechoice \
--password "NewSecureP@ss123" --permanent
Output:
Password reset for 'john.doe'
New password: aB9$kL2mN5pQ8rT
User must change password on next login
What happens:
# Logout user from all sessions
python factory.web/ObjKeycloakAdmin.py force-logout john.doe homechoice
Output:
Invalidated 3 session(s) for 'john.doe'
# All active sessions
python factory.web/ObjKeycloakAdmin.py sessions
# Filter by package
python factory.web/ObjKeycloakAdmin.py sessions --package homechoice
# Filter by user
python factory.web/ObjKeycloakAdmin.py sessions --user john.doe
# Filter by session type
python factory.web/ObjKeycloakAdmin.py sessions --type web
Output:
Active Sessions
┌──────────┬──────────┬──────────┬──────┬──────────┬────────────┬──────────┐
│ Session │ User │ Package │ Type │ Auth │ IP Address │ Created │
├──────────┼──────────┼──────────┼──────┼──────────┼────────────┼──────────┤
│ 8a3f9... │ john.doe │ homech.. │ web │ keycloak │ 10.0.1.50 │ 2026-... │
└──────────┴──────────┴──────────┴──────┴──────────┴────────────┴──────────┘
# View all pending syncs
python factory.web/ObjKeycloakAdmin.py sync-queue
# Filter by package
python factory.web/ObjKeycloakAdmin.py sync-queue --package homechoice
# Filter by status
python factory.web/ObjKeycloakAdmin.py sync-queue --status failed
Output:
Keycloak Sync Queue
┌──────────┬─────────┬────────────┬────────┬──────────┬──────────┬──────────┐
│ User │ Package │ Type │ Status │ Priority │ Attempts │ Queued │
├──────────┼─────────┼────────────┼────────┼──────────┼──────────┼──────────┤
│ john.doe │ homec.. │ user_creat │ failed │ 5 │ 3 │ 2026-... │
└──────────┴─────────┴────────────┴────────┴──────────┴──────────┴──────────┘
# Process pending syncs (up to 10 items)
python factory.web/ObjKeycloakAdmin.py sync-queue --process
# Process specific package
python factory.web/ObjKeycloakAdmin.py sync-queue \
--package homechoice --process
Output:
Processing sync queue...
Processed: 10 | Success: 8 | Failed: 2
# Clear failed syncs older than 7 days (default)
python factory.web/ObjKeycloakAdmin.py sync-queue --clear-failed
# Clear for specific package
python factory.web/ObjKeycloakAdmin.py sync-queue \
--package homechoice --clear-failed
# Enable emergency mode (force all users to local auth)
python factory.web/ObjKeycloakAdmin.py emergency --enable \
--reason "Keycloak maintenance"
# Disable emergency mode
python factory.web/ObjKeycloakAdmin.py emergency --disable
What happens when enabled:
Use cases:
# System-wide statistics
python factory.web/ObjKeycloakAdmin.py stats
# Package-specific statistics
python factory.web/ObjKeycloakAdmin.py stats --package homechoice
Output:
System Statistics
Users:
Total: 450
Active: 423
Locked: 5
Active Sessions:
Total: 89
By Type:
web: 65
api: 20
mobile: 4
By Auth Mode:
keycloak: 72
cached: 10
local: 7
Keycloak Status:
Status: ONLINE
Circuit: closed
Mode: normal
Pending Syncs: 3
Cached Tokens: 15
from factory.web.ObjKeycloakAdmin import ObjKeycloakAdmin
# Initialize
admin = ObjKeycloakAdmin()
# List users
users = admin.list_users("homechoice", search="john")
for user in users:
print(f"{user['username']}: {user['email']}")
# Disable user
admin.disable_user(
"john.doe",
"homechoice",
reason="Account suspended"
)
# Reset password
result = admin.reset_password("john.doe", "homechoice")
print(f"New password: {result['password']}")
# Get statistics
stats = admin.get_statistics("homechoice")
print(f"Active users: {stats['users']['active']}")
# Bulk disable users
usernames = ["user1", "user2", "user3"]
result = admin.bulk_disable_users(
usernames,
"homechoice",
reason="Bulk suspension"
)
print(f"Success: {result['success']}")
print(f"Failed: {result['failed']}")
for error in result['errors']:
print(f" {error}")
# List sessions for specific user
sessions = admin.list_active_sessions(
package="homechoice",
username="john.doe"
)
print(f"User has {len(sessions)} active sessions")
# Force logout
count = admin.force_logout("john.doe", "homechoice")
print(f"Invalidated {count} sessions")
# Get pending syncs
items = admin.get_sync_queue(
package="homechoice",
status="pending"
)
print(f"Pending syncs: {len(items)}")
# Process queue
result = admin.process_sync_queue_manual(
package="homechoice",
limit=10
)
print(f"Processed: {result['processed']}")
print(f"Success: {result['success']}")
# Clear old failed syncs
count = admin.clear_failed_syncs(
package="homechoice",
older_than_days=7
)
print(f"Cleared {count} failed syncs")
All administrative actions are logged to sys_user_history with:
disable_user - User account disabledenable_user - User account enabledreset_password - Password resetforce_logout - Sessions invalidatedtoggle_emergency_mode - Emergency mode changedSELECT Action, User, Package, Details, Timestamp
FROM sys_user_history
WHERE Action IN (
'disable_user', 'enable_user',
'reset_password', 'force_logout'
)
ORDER BY Timestamp DESC
LIMIT 100;
Suspend User Account
python factory.web/ObjKeycloakAdmin.py disable john.doe homechoice \
--reason "Policy violation" --force
Reset Forgotten Password
python factory.web/ObjKeycloakAdmin.py reset-password john.doe homechoice
# Send generated password to user via email
Check Active Sessions
python factory.web/ObjKeycloakAdmin.py sessions --package homechoice
User Can't Login - Check Status
# View user details
python factory.web/ObjKeycloakAdmin.py users homechoice --search john.doe
# Check their sessions
python factory.web/ObjKeycloakAdmin.py sessions --user john.doe
# Check sync queue for pending operations
python factory.web/ObjKeycloakAdmin.py sync-queue --package homechoice
Process Stuck Syncs
# View failed syncs
python factory.web/ObjKeycloakAdmin.py sync-queue --status failed
# Retry processing
python factory.web/ObjKeycloakAdmin.py sync-queue --process
# Clear old failed items
python factory.web/ObjKeycloakAdmin.py sync-queue --clear-failed
Keycloak Maintenance Window
# Enable emergency mode
python factory.web/ObjKeycloakAdmin.py emergency --enable \
--reason "Keycloak maintenance 2026-02-07 22:00-23:00 UTC"
# Perform Keycloak maintenance...
# Disable emergency mode
python factory.web/ObjKeycloakAdmin.py emergency --disable
Bulk User Suspension
from factory.web.ObjKeycloakAdmin import ObjKeycloakAdmin
admin = ObjKeycloakAdmin()
# Read usernames from file
with open('users_to_suspend.txt') as f:
usernames = [line.strip() for line in f]
# Bulk disable
result = admin.bulk_disable_users(
usernames,
"homechoice",
reason="End of contract period"
)
print(f"Disabled: {result['success']}/{len(usernames)}")
from factory.web.ObjKeycloakAdmin import ObjKeycloakAdmin
from ObjNotify import ObjNotify
admin = ObjKeycloakAdmin()
stats = admin.get_statistics("homechoice")
# Send daily stats email
notify = ObjNotify()
notify.send_email(
to="ops@example.com",
subject="Daily User Statistics",
body=f"""
Active Users: {stats['users']['active']}
Locked Users: {stats['users']['locked']}
Active Sessions: {stats['sessions']['total']}
Pending Syncs: {stats['keycloak'].get('pending_syncs', 0)}
"""
)
from factory.web.ObjKeycloakAdmin import ObjKeycloakAdmin
from ObjNotify import ObjNotify
admin = ObjKeycloakAdmin()
items = admin.get_sync_queue(status="pending")
if len(items) > 50:
notify = ObjNotify()
notify.send_notification(
title="High Sync Queue Depth",
message=f"{len(items)} pending Keycloak syncs",
severity="warning",
category="keycloak_admin"
)
-- User lookups
CREATE INDEX idx_user_search ON sys_user(User, Email, Name, Package);
-- Session queries
CREATE INDEX idx_session_active ON sys_usersession(IsActive, ExpiresAt, Package);
-- Sync queue
CREATE INDEX idx_sync_status ON sys_keycloak_sync_queue(Status, Package, Priority);
-- Audit trail
CREATE INDEX idx_audit_action ON sys_user_history(Action, Timestamp);
factory.web/ObjUser.py - User authenticationfactory.web/ObjUserSession.py - Session managementfactory.core/ObjKeycloakResilient.py - Keycloak clientfactory.core/ObjKeycloakSyncService.py - Background sync service