Is it possible to switch the LDAP federation in Keycloak to Import Users mode for SCIM or service account based synchronizations?
Question
A third-party tool is connected to Keycloak using a service account.
The tool uses SCIM-like functionality and needs to query endpoints such as users/count in order to synchronize users into the application.
In the default Univention Corporate Server setup, users are not imported into Keycloak. Instead, they are resolved dynamically via LDAP federation against the UCS directory service.
According to the tool vendor, the users/count endpoint has limitations if users are not stored inside the Keycloak database. Even if the vendor worked around this restriction, every synchronization run would still generate a noticeable load on the LDAP service (slapd) of the UCS server hosting Keycloak.
Is the default setting (Import Users = Off) mandatory, or can we safely switch the LDAP federation to Import Users = On without causing issues or disadvantages?
The official documentation mentions this design decision:
https://docs.software-univention.de/keycloak-app/latest/architecture.html#design-decisions
Answer
Yes, switching to import mode is technically possible, but not recommended in UCS environments.
The default decision to keep Import Users = Off mainly follows two architectural principles.
1. Single Source of Truth
The LDAP directory (slapd) remains the authoritative data source.
Changes in LDAP are immediately visible in Keycloak without waiting for synchronization cycles.
2. Avoidance of Data Redundancy
Many UCS environments manage very large user bases. Importing all users would significantly increase the Keycloak database size without always providing real benefit.
When Import Users = On is enabled, the following happens:
-
User objects are copied into the Keycloak database, either
- at first login, or
- via manual or scheduled synchronization.
-
Endpoints such as
users/countthen operate reliably on the internal Keycloak database instead of triggering LDAP lookups.
This typically resolves the vendor’s limitation.
What should be considered before changing the setting?
While the change is valid, it introduces trade-offs.
Synchronization load
Instead of many real-time LDAP queries, the load is shifted to:
- an initial full import, and
- periodic delta or full sync jobs.
In practice, this is often more efficient, but the intervals must be planned carefully.
Password validation
Even with imported users, authentication is still usually delegated to LDAP.
Changing this behavior is technically possible but not recommended in UCS environments, especially due to Kerberos integration.
Data consistency
If a user is deleted or disabled in LDAP, Keycloak only becomes aware of it during the next sync.
This can introduce a short delay before the account is blocked.
Persistence across updates
If modifications are made directly in the Keycloak admin UI, verify whether they survive app updates.
Typically federation provider settings remain, but creating a backup of the configuration is strongly recommended.
Recommended approach
For SCIM or heavy service account synchronization scenarios, the following procedure has proven practical.
1. Test first
Validate the behavior in a staging or test system before touching production.
2. Configure sync intervals wisely
A common pattern is:
- periodic full sync → once per night
- changed users sync → every 30–60 minutes
This usually reduces LDAP pressure significantly compared to live queries on each request.
3. Limit the scope
Define a dedicated Users DN or LDAP filter so that only the users actually required by the external tool are imported.
This keeps both database size and synchronization time under control.
Conclusion
The UCS default (Import Users = Off) is optimized for environments where:
- LDAP immediacy is crucial, and
- minimizing data duplication is preferred.
For special requirements such as SCIM provisioning or vendor integrations depending on database-backed queries, enabling import mode is legitimate and often the better architectural choice.