What Is Bulk User Import Performance Tuning in Keycloak?
A complete, no-code walkthrough of how Keycloak imports large numbers of users, where the slowdowns come from, and how to tune the process safely.
Picture a small town hall trying to register ten thousand new residents in a single afternoon, using one clerk, one form, and one filing cabinet. The clerk could technically process every single form, one at a time, but the line would stretch around the block, and the filing cabinet would jam long before lunch. Now imagine instead opening five service windows, pre-sorting the forms into batches, and using a filing system designed for high-volume intake. Same ten thousand residents, dramatically different afternoon. Bulk user import performance tuning in Keycloak is exactly this second scenario — reshaping how a large batch of users gets loaded so the “town hall” doesn’t grind to a halt.
1Core Concepts
Before tuning anything, it helps to understand what “importing users” actually means inside Keycloak, and why doing it at scale is a different problem than doing it one user at a time.
What counts as a bulk user import?
A bulk import is the process of creating a large number of user accounts in a Keycloak realm at once — often thousands or even millions of records — typically as part of migrating from a legacy identity system, onboarding an acquired company’s workforce, or seeding a new environment. This is fundamentally different from the everyday trickle of individual sign-ups, and it stresses different parts of the system.
Creating one user is like mailing a single letter — quick, simple, no special equipment needed. Bulk importing users is like running a mail-merge for a hundred thousand letters at once. The task is conceptually the same, but doing it efficiently requires an entirely different approach: batching, parallel printers, and a mailroom process built for volume rather than a single trip to the post box.
Why bulk import behaves differently than normal usage
Under everyday conditions, Keycloak handles user creation as isolated, independent events spread out over time. A bulk import instead concentrates an enormous number of write operations into a short window, which can expose bottlenecks — in the database, in password hashing, in indexing — that simply never surface during normal day-to-day traffic.
Bulk Import
Creating a large batch of user accounts in a short time window, rather than one at a time over time.
Throughput
How many user records can be successfully created per unit of time.
Batching
Grouping many individual records into chunks processed together, rather than one by one.
Password Hashing Cost
The computational effort spent securely hashing each user’s password during creation.
Connection Pool
The set of reusable database connections Keycloak draws from during import operations.
Backpressure
A system’s way of signaling “slow down” when it’s being overwhelmed with more work than it can currently handle.
A perfectly healthy Keycloak deployment, tuned nicely for normal login traffic, can still struggle badly during a bulk import if nobody adjusts settings specifically for that burst of concentrated write activity. Bulk import tuning is a distinct discipline from everyday performance tuning.
2Architecture and Components
Understanding which pieces of the stack actually get exercised during a bulk import points directly at where tuning matters.
Admin REST API / Import Tooling
The interface through which user records are submitted for creation, whether via API calls or a realm import file.
Password Hashing Provider
The module responsible for turning each plaintext password into a securely stored hash.
Underlying Database
The relational store where every new user record, along with credentials and attributes, is ultimately written.
Connection Pool
The pool of database connections Keycloak instances share while writing new records.
Caching Layer
Keycloak’s internal caches, which can be affected by a sudden flood of new user entities.
Cluster Nodes
Multiple Keycloak instances that may share the load of an import, and must stay coordinated while doing so.
Where the real bottleneck usually lives
Across most large-scale imports, the database and the password hashing step tend to be the two biggest limiting factors — the database because every single user write ultimately lands there, and password hashing because secure hashing algorithms are deliberately, intentionally slow to compute, as a defense against attackers guessing passwords quickly.
Import strategy shapes the bottleneck
Whether users are imported through repeated API calls or through a single realm import file changes which component feels the most pressure — API-driven imports stress the request-handling and hashing path directly, while file-based imports stress the parsing and database-write path in a more concentrated burst.
3Internal Working
Walking through what actually happens, step by step, as each user record moves from source data to a stored account.
Step one: receiving the record
Whether submitted through the Admin REST API or read from a realm import file, each user record first needs to be parsed and validated — checking that required fields are present, that the username isn’t already taken, and that the data is well-formed before anything is written.
Step two: hashing the password
For each user with a password being set during import, Keycloak runs that password through its configured hashing algorithm. This step is deliberately computationally expensive by design — a security feature, not a bug — which means it scales linearly with the sheer number of users being imported, and often becomes the single largest contributor to overall import time.
Password hashing during import is like a security team hand-stamping every single passport with a tamper-resistant seal. Doing it for one passport takes a moment; doing it for ten thousand takes proportionally longer, no matter how efficient the stamping machine is, because each stamp is deliberately designed to take real effort.
Step three: writing to the database
Once validated and hashed, the user record is written to the underlying database, along with any associated attributes, role mappings, or group memberships. Under bulk conditions, this step benefits enormously from writing in batches rather than issuing one isolated database transaction per single user.
Step four: cache and cluster propagation
In a clustered Keycloak deployment, newly created users may also need to be reflected across the cluster’s shared state or caches. A poorly tuned cache configuration can turn what should be a smooth import into a source of unexpected cluster-wide chatter and slowdown.
Throwing more Keycloak instances at a bulk import doesn’t automatically make it faster. If the underlying database is the actual bottleneck, adding more Keycloak nodes just means more instances competing for the same limited database capacity.
4Data Flow and Lifecycle
Seeing the whole pipeline end-to-end clarifies exactly where tuning levers can be applied.
sequenceDiagram
participant Source as Source Data (file/API calls)
participant KC as Keycloak Instance
participant Hash as Password Hashing
participant DB as Database
Source->>KC: Submit user record(s) in batches
KC->>KC: Validate record (uniqueness, required fields)
KC->>Hash: Hash password (if provided)
Hash-->>KC: Return hashed credential
KC->>DB: Write user record + credential in a batched transaction
DB-->>KC: Acknowledge write
KC-->>Source: Report success/failure for the batch
The lifecycle of a bulk import operation
A well-run bulk import is planned and executed in distinct phases, not treated as a single all-or-nothing event.
Planned
Volume, timing, and expected load are estimated before the import begins.
Staged in a Test Environment
A smaller or full-scale rehearsal is run against a non-production environment first.
Executed in Batches
The actual import runs in controlled, sized chunks rather than one giant single request.
Monitored Live
Progress, error rates, and system health are watched throughout, not just checked at the end.
Verified
Record counts and spot-checks confirm the import completed accurately after the fact.
Batches that are too small waste time on repeated overhead per request; batches that are too large risk timeouts, memory pressure, or one bad record spoiling an enormous transaction. Finding the right batch size is one of the highest-leverage tuning decisions in the whole process.
5Advantages, Disadvantages, and Trade-offs
Tuning a bulk import is fundamentally about trade-offs between speed, safety, and system stability.
Advantages of Deliberate Tuning
- Dramatically reduces total import time for large user volumes
- Prevents the import process from degrading normal production traffic
- Reduces risk of partial failures caused by timeouts or resource exhaustion
- Makes very large migrations (millions of users) practically achievable at all
- Improves confidence and repeatability for future imports
Disadvantages / Trade-offs
- Requires upfront planning and testing effort before the “real” import
- Aggressive parallelism can strain the database if not carefully bounded
- Overly large batches risk bigger, harder-to-diagnose failures if something goes wrong
- Tuning choices are often environment-specific and don’t always transfer directly
6Security
The pressure to go fast during a bulk import should never come at the cost of security fundamentals.
Never weaken password hashing to gain speed
It can be tempting, when hashing is the bottleneck, to reach for a weaker or faster hashing configuration purely to speed up the import. This trades away real security for a one-time convenience, and the weakened setting can easily be forgotten and left in place afterward, quietly reducing protection for every account going forward.
Temporarily lowering password hashing strength “just for the migration” and forgetting to restore it afterward. If hashing needs to be faster during import, prefer scaling out the work itself (more controlled parallelism) over weakening the hash.
Protecting sensitive data in transit and at rest
Source files containing plaintext passwords or personal data — common during migrations from legacy systems — deserve the same handling discipline as any other sensitive dataset: encrypted storage, restricted access, and deletion once the import is verified complete.
Auditing the import itself
Because a bulk import creates a large number of accounts at once, it’s worth logging who initiated the import, when, and a summary of what was created, so the event is traceable later during any security review.
Keep Hashing Strength
Never lower password hashing security purely to speed up an import.
Protect Source Files
Treat any file containing user credentials or personal data as sensitive at every stage.
Log the Event
Record who ran the import and a summary of what changed, for later auditing.
Clean Up Afterward
Securely delete temporary source files once the import is verified successful.
7Monitoring, Logging, and Metrics
A bulk import deserves real-time visibility, since problems left unnoticed for even a few minutes can compound quickly at scale.
Signals worth tracking during the import
Useful signals include the live throughput of successfully created records, the rate of failed or rejected records (which can indicate a data quality problem in the source), database connection pool saturation, and general system resource usage like memory and CPU on the Keycloak instances doing the work.
Watching for a “long tail” of slow batches
If throughput steadily degrades as the import progresses rather than staying steady, that’s often a sign of a resource — like a connection pool or an index — becoming a growing bottleneck as data volume increases, worth investigating before the next large import.
8Design Patterns and Anti-patterns
Some habits make large imports predictable and safe; others turn a routine migration into an incident.
Problem
A team runs the entire user dataset as one single, unbatched import directly against production, with no prior test run.
Why It’s Harmful
Any failure partway through can leave the system in an unclear, partially-imported state, and there’s no earlier signal that would have revealed bottlenecks before they affected live infrastructure.
Correct Approach
Break the import into sized batches, rehearse against a staging environment first, and only then run the production import with monitoring in place.
Problem
Parallelism is cranked up aggressively across many concurrent import workers without checking the database’s actual capacity.
Why It’s Harmful
The database can become saturated, causing timeouts and failures that ironically make the overall import slower and less reliable than a more measured, appropriately-parallel approach.
Correct Approach
Scale parallelism gradually, watching database load as the leading indicator, rather than assuming “more workers” is always strictly faster.
A healthier pattern: staged rollout with checkpoints
Running the import in clearly defined stages — a small test batch, a medium batch, then the full volume — with a deliberate pause to check metrics between each stage, catches problems while they’re still small and cheap to fix.
9Best Practices and Common Mistakes
A short, practical checklist for teams planning a large-scale user import into Keycloak.
Rehearse first
Always run a realistic test import in a non-production environment before the real one.
Size batches deliberately
Tune batch size based on observed performance, not a guess or a default left unchanged.
Monitor live
Watch throughput, errors, and database load throughout the run, not just at the end.
Plan for retries
Design the process so a failed batch can be safely retried without duplicating successful records.
Scheduling a large bulk import during peak production traffic hours, letting it compete for the same database and system resources that live user logins depend on.
10Real-World and Industry Examples
Bulk user import tuning shows up wherever an organization’s user base changes shape all at once, rather than gradually.
Mergers and acquisitions
When one company acquires another, migrating the acquired company’s entire workforce into a shared identity platform is a classic bulk import scenario, often under real business time pressure.
Legacy identity system replacement
Organizations retiring an older identity provider frequently need to migrate their entire existing user base into Keycloak in one coordinated cutover, making import performance directly tied to the length of a planned downtime window.
Large-scale event or seasonal onboarding
Education platforms onboarding an entire new academic year’s students, or seasonal services onboarding a large temporary workforce, both represent recurring bulk import scenarios where tuning lessons from one cycle directly benefit the next.
11Frequently Asked Questions
Secure hashing algorithms are intentionally computationally expensive as a defense against attackers, so that cost scales directly with the number of users being imported.
Not necessarily. If the database is the actual bottleneck, more Keycloak instances just create more competition for the same limited database capacity.
Very large batches risk timeouts, memory pressure, and bigger, harder-to-diagnose failures if a single bad record causes an entire large batch to fail.
Generally it’s safer to schedule it outside peak traffic hours, so it doesn’t compete with live user logins for the same system and database resources.
No. Weakening hashing strength trades away real, ongoing account security for a one-time convenience, and the change can easily be forgotten and left in place.
By designing the process so failed batches can be identified and retried without duplicating already-successful records, rather than treating the whole import as all-or-nothing.
12Summary and Key Takeaways
Bulk user import performance tuning is the discipline of reshaping how Keycloak absorbs a large, concentrated burst of new user creation — through batching, careful parallelism, and attention to the two usual suspects, password hashing and database capacity. Done well, it turns what could be a slow, fragile migration into a predictable, monitored, and repeatable operation. Done poorly, it risks turning a routine onboarding event into a production incident. The core discipline is the same one behind most performance work: measure first, rehearse in a safe environment, and never trade away security fundamentals for speed.
Key Takeaways
- Bulk import is a different regime than normal usage — it concentrates write load in a way everyday traffic never does.
- Password hashing and the database are the usual bottlenecks — tuning effort should start there.
- Batching is one of the highest-leverage levers — too small wastes overhead, too large risks fragile failures.
- More Keycloak instances isn’t automatically faster — check where the real bottleneck sits first.
- Never weaken hashing strength for speed — that trade quietly undermines account security going forward.
- Rehearse before the real thing — a staged, monitored test run catches problems while they’re cheap to fix.
- Design for safe retries — a failed batch should be recoverable without duplicating successful records.