hrms-api-org/scripts/KEYCLOAK_SYNC_README.md

Keycloak Sync Scripts

This directory contains standalone scripts for managing Keycloak users from the CLI. These scripts are useful for maintenance, setup, and troubleshooting Keycloak synchronization.

Prerequisites

• Node.js and TypeScript installed
• Database connection configured in .env
• Keycloak connection configured in .env
• Run with ts-node or compile first

Environment Variables

Ensure these are set in your .env file:

# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database
DB_USER=your_user
DB_PASSWORD=your_password

# Keycloak
KC_URL=https://your-keycloak-url
KC_REALMS=your-realm
KC_SERVICE_ACCOUNT_CLIENT_ID=your-client-id
KC_SERVICE_ACCOUNT_SECRET=your-client-secret

Scripts

1. clear-orphaned-users.ts

Deletes Keycloak users that don't exist in the database (Profile + ProfileEmployee tables). Useful for cleaning up invalid users.

Protected usernames (never deleted): super_admin, admin_issue

# Dry run (preview changes)
ts-node scripts/clear-orphaned-users.ts --dry-run

# Live execution
ts-node scripts/clear-orphaned-users.ts

Output:

• Total users in Keycloak
• Total users in Database
• Orphaned users found
• Deleted/Skipped/Failed counts

2. ensure-users.ts

Checks and creates Keycloak users for all profiles. Includes role assignment (USER role) automatically.

# Dry run (preview changes)
ts-node scripts/ensure-users.ts --dry-run

# Live execution
ts-node scripts/ensure-users.ts

# Test with limited profiles (for testing)
ts-node scripts/ensure-users.ts --dry-run --limit=10

Output:

• Total profiles processed
• Created users (new Keycloak accounts)
• Verified users (already exists)
• Skipped profiles (no citizenId)
• Failed count

3. sync-all.ts

Syncs all attributes to Keycloak for users with existing Keycloak IDs.

Attributes synced:

• profileId
• orgRootDnaId
• orgChild1DnaId
• orgChild2DnaId
• orgChild3DnaId
• orgChild4DnaId
• empType
• prefix

# Dry run (preview changes)
ts-node scripts/sync-all.ts --dry-run

# Live execution
ts-node scripts/sync-all.ts

# Test with limited profiles
ts-node scripts/sync-all.ts --dry-run --limit=10

# Adjust concurrency (default: 5)
ts-node scripts/sync-all.ts --concurrency=10

Output:

• Total profiles with Keycloak IDs
• Success/Failed counts
• Error details for failures

Recommended Execution Order

For initial setup or full resynchronization:

1. clear-orphaned-users - Clean up invalid users first

   npx ts-node scripts/clear-orphaned-users.ts
   

2. ensure-users - Create missing users and assign roles

   npx ts-node scripts/ensure-users.ts
   

3. sync-all - Sync all attributes to Keycloak

   npx ts-node scripts/sync-all.ts
   

Tips

• Always run with --dry-run first to preview changes
• Use --limit=N for testing before running on full dataset
• Scripts process both Profile (ข้าราชการ) and ProfileEmployee (ลูกจ้าง) tables
• Only active profiles (isLeave: false) are processed by ensure-users
• The USER role is automatically assigned to new/verified users

Troubleshooting

Database connection error:

• Check .env database variables
• Ensure database server is running

Keycloak connection error:

• Check KC_URL, KC_REALMS in .env
• Verify service account credentials
• Check network connectivity to Keycloak

USER role not found:

• Log in to Keycloak admin console
• Create a USER role in your realm
• Ensure service account has manage-users and view-users permissions