Keycloak SCIM provisioning: when HR-driven user and group sync is worth building
This page covers how to decide whether syncing users and groups from an HR system or identity governance tool into Keycloak is worth building, and what that build involves. It is written for teams where an external system is the source of truth and Keycloak must reflect joiners, movers and leavers without someone editing accounts by hand. The first decision is not technical. Confirm which system owns each identity fact, and whether Keycloak should hold a copy of those facts or only act on them when a user signs in.
The documented facts available for this page do not confirm that Keycloak provides a native SCIM endpoint. Before you plan any work, confirm SCIM support for the exact Keycloak version you run, using the official documentation for that release and a test against a non-production instance. If the endpoint is absent or does not cover what you need, you have other paths: build a custom sync job against Keycloak's Administration REST API, place an identity governance tool with a SCIM or other connector between the HR source and Keycloak, or use user federation if the source of truth already sits in LDAP or Active Directory, which the Keycloak server administration guide documents.
In plain terms, the scope has four parts. Users covers creating accounts, updating them and disabling them. Groups covers membership, which matters because group membership often drives which applications and roles a person receives. Attributes covers the mapping from HR fields such as employee ID, department or manager to the attributes in Keycloak's user profile, and it requires an agreed list of which fields Keycloak will overwrite. Deprovisioning covers what happens when someone leaves: whether the account is disabled or deleted, how existing sessions and tokens are ended, and how records that administrators created by hand are handled. Each part needs a named owner and a test case before build starts.
Sync is usually worth building when many applications depend on group claims, when joiner and leaver volume is high enough that manual steps create gaps, or when audit requires evidence that access was removed on time. It is usually not worth building for a small, stable user population or where an existing identity governance tool already performs these steps. Ask a partner or your own team to answer these questions in writing: who maintains the attribute mapping, what happens when the HR feed is wrong or incomplete, which service account holds the required permissions and how its credentials are rotated, and how a failed sync is detected and retried.
Which provisioning path fits your Keycloak setup
This table compares four ways to provision users and groups into Keycloak: a native SCIM endpoint, a community extension, direct Administration REST API calls, and an identity governance platform. Read each row against your Keycloak version, your source system, and who will maintain any custom code. The main takeaway is that a native endpoint is the lowest-maintenance path only if your version provides one, so confirm that first.
| Path | What it needs and who maintains it | What to confirm | When it fits |
|---|---|---|---|
| Native SCIM endpoint | A SCIM endpoint shipped with your Keycloak version, maintained through the Keycloak project and its release cycle. | Whether your exact version provides it, its status, supported attributes, and how group membership is handled. | Your version provides it and the HR or governance source sends standard SCIM requests. |
| Community or third-party SCIM extension | An extension installed into Keycloak, maintained by its authors or a vendor rather than the Keycloak project. | Maintenance activity, license terms, compatibility with your Keycloak version, and who provides support. | No suitable native endpoint exists and you accept an external dependency that you must patch and test. |
| Keycloak Administration REST API with a service account | A service account with narrowly scoped admin roles, plus an integration you build and run. | Which admin roles the account needs, token lifetime, secret storage, and how user and group changes are logged. | Your integration team can own custom code and the service account can be tightly controlled and monitored. |
| midPoint through a connector | midPoint with ConnId connectors and PostgreSQL. Evolveum maintains midPoint; connector status varies. | Whether a Keycloak-side connector exists and its status, since documented connectors do not list Keycloak. | You need HR-driven lifecycle, approvals, or access certification beyond provisioning alone. |
Which service account permissions Keycloak SCIM provisioning needs
Whichever path you choose, the system that calls Keycloak's SCIM API authenticates as a confidential client that uses a service account. The realm-management roles assigned to that service account's user decide what the caller can create, update, disable or delete. Treat the service account as the main control point for provisioning. Before you build anything, ask the team that owns each source system (the HR platform or the identity governance tool) which operations it must perform, then map those operations to the roles Keycloak requires. Keep this mapping in writing, because it becomes the basis of your access review for the integration.
Grant least privilege. Assign only the user and group management roles that the chosen path needs. A path that only creates users and maintains group membership does not need roles that manage clients, realm settings or identity providers. Avoid broad administrative roles, even for convenience during testing. Use one client per environment, so development, test and production each have their own client ID, secret and role assignments. A leaked development secret then cannot reach production data. Confirm the exact role names and their scope in the administration documentation for the Keycloak release you run, because role names and the operations they cover can change between releases.
Store the client secret in a secrets manager or the calling system's own vault, with access limited to the people and processes that run the integration. Do not place it in configuration files, source repositories, tickets or chat messages. Plan rotation before go-live: define who generates the new secret, how the calling system receives it, and how Keycloak and the caller switch over without a provisioning gap. Rehearse this in a non-production realm, record the owner and the date of each rotation, and document what happens if a rotation fails partway through. Revoke the old secret once the new one is confirmed to work.
Keep the Administration REST API on a separate hostname or context path from public frontend URLs, as Keycloak's production guide directs. Use TLS for all communication, and configure the reverse proxy with path restrictions so that administration endpoints are not reachable through the public sign-in hostname. Limit which networks can reach the administration hostname to the systems that actually call SCIM. To verify this, request an administration path through the public hostname and confirm that it is refused, then confirm that the provisioning caller reaches the API through the intended route. Repeat these checks after every proxy or network change.
How SCIM attributes map to the Keycloak user profile
This table compares common SCIM core attributes with the Keycloak user profile fields they are expected to populate. It is an illustrative mapping: the actual result depends on the provisioning path you choose and how your realm's user profile is configured. Confirm each row against your Keycloak version, and check email uniqueness, username rules and required attributes before go-live.
| SCIM attribute | Keycloak field | Checks before go-live |
|---|---|---|
| userName | Username | Confirm the username rules in your user profile and how case is handled for uniqueness. |
| name.givenName | First name | Confirm whether the field is required in the user profile for your realm. |
| name.familyName | Last name | Confirm whether the field is required, since some sign-in flows may depend on it. |
| emails (primary value) | Confirm email uniqueness settings and decide how duplicate addresses from HR data are handled. | |
| active | Enabled | Confirm how deactivation affects existing sessions and tokens in your version. |
| externalId | Custom attribute (illustrative) | Confirm where your path stores it and that a declared attribute exists for it, with uniqueness per source system. |
| Group membership | Group membership | Confirm whether groups must exist before provisioning and how nested groups are handled. |
| Enterprise extension attributes (for example, cost center) | Declared user profile attribute | Declare each attribute in the user profile first, then test that values persist after a sync. |
How to set up Keycloak provisioning step by step
This sequence takes a Keycloak SCIM provisioning setup from a confirmed source system and version to a tested, reversible production cutover. Each step closes with a check, so the identity team knows what has been proven before moving on. The result is a documented provisioning path with a rollback plan that operations can run.
Confirm the provisioning path and version
Identify whether provisioning comes directly from an HR system, through an identity governance tool such as midPoint, or from a custom integration calling the SCIM API. Record the exact Keycloak version you will run in production and read the SCIM documentation for that version before building anything. Confirm that your test environment runs the same version. The step is done when the identity team has a written note naming the source system, the integration component and the Keycloak version, and that note has been approved.
Define the source of truth and join key
Decide which system owns each user attribute and each group membership so Keycloak never receives conflicting writes for the same field. Choose a stable join key, such as an externalId issued by the HR system, and confirm it is unique, never reused and present for every person in scope. Document what happens when a record lacks the key or when two records share one. The step is done when a sample extract from the source shows the key populated for every test identity and no duplicate values.
Create a dedicated test realm
Create a non-production realm used only for provisioning tests, separate from any realm that serves application sign-in. Keep its login flows, user profile settings and group setup close to production so test results carry over. Do not connect production clients to it. The step is done when the realm exists, contains no production clients and appears in the admin console as its own realm, with the identity team confirming the naming convention that production will follow.
Create the service client with minimal roles
Create a confidential client for the provisioning integration, enable its service account and assign only the realm management roles that the SCIM operations in your Keycloak version require. Avoid granting broad administrative roles across the realm. Store the client secret in your secrets manager and set a rotation owner. The step is done when a client credentials token request succeeds, a read of test users succeeds, and an operation outside the granted roles is refused.
Configure user profile and group structure
Map each source attribute to a user profile attribute in a written mapping sheet, marking which attributes are required and adding any custom attributes to the user profile before the first sync. Build the group hierarchy the source expects, using consistent names and clear ownership. Confirm how group membership will be set and removed. The step is done when an export of the user profile and group tree matches the mapping sheet, with every attribute present and typed as planned.
Run a sync and check metrics
Run provisioning against the test realm using a small, known group of test identities. Include people you will later create, change, disable and move between groups. Record the run start time and keep the run log. Enable metrics with --metrics-enabled=true and read the Prometheus-format output at /metrics on the management interface during the run to watch request and error figures. The step is done when every test identity exists with the expected attributes and the log shows no unexplained errors.
Verify create, update, disable and membership results
Make controlled changes in the source system: create a user, change an attribute, disable a person and move someone into a different group. After each change, confirm the resulting state in Keycloak. Record expected and actual results in a table with one row per test case. Repeat the cases if the source system sends changes in batches or on a schedule. The step is done when every row in the table matches, and the identity team has reviewed any mismatch and its cause.
Test deprovisioning and rollback before cutover
Test removal and disable paths, then confirm that a disabled user cannot sign in, that existing sessions are handled as your policy requires, and that group memberships are removed when expected. Export the test realm before each run so you have a known restore point. Rehearse the rollback: name who approves it, which records revert and how the export is restored. The step is done when a rollback rehearsal in the test realm returns the exported state, and the approved plan is ready for the production cutover.
Security risks in Keycloak SCIM provisioning to design for
Provisioning changes who can sign in, so the SCIM channel carries as much risk as the identity provider itself. The six risks below share one root: an automated caller holds standing access that someone must scope, protect, and check. Each card names the control to design for and how to verify it in your environment.
Over-privileged service accounts
The service account that the HR connector or governance tool authenticates with should hold only the roles needed to manage users and groups in the realms it provisions. Broad roles such as realm administration let a compromised connector change credentials, client settings, or other administrators. Verify by listing the account's assigned roles, running a representative create, update, and deactivate sequence, and confirming that out-of-scope operations return an error.
Leaked client secrets
The confidential client used for SCIM calls authenticates with a secret, and that secret often ends up in connector configuration, CI variables, or tickets. Store it in a secrets manager, inject it at runtime, and define a rotation procedure that the provisioning tool supports without an outage. Verify by searching configuration repositories and pipeline logs for the secret value, and by confirming that the old secret fails immediately after rotation.
Administration REST API on public hostnames
Keycloak's production guide calls for the admin console and Administration REST API to sit on a different hostname or context path from public frontend URLs. SCIM traffic should reach Keycloak through a route that is not on the public frontend hostname, and the reverse proxy should allow only the paths your provisioning source needs. Verify from outside your private network that administrative paths return no usable response, and that the proxy rejects paths you did not allow.
Unverified deprovisioning that leaves active accounts
A leaver whose account stays active after the HR system marks them inactive is an access gap that a provisioning request log may not flag. Confirm that deactivation and deletion requests from the source reach Keycloak, that disabled users cannot start new sessions, and how existing sessions and offline tokens are handled in your version. Verify with a scheduled reconciliation that compares active Keycloak accounts against the source of record and reports every mismatch.
Unauthenticated or unencrypted transport
Every hop in the provisioning path should use TLS: the connector to the Keycloak endpoint, Keycloak to its database, and any mail Keycloak sends. Keycloak 26.8 enforces SMTP StartTLS without plaintext fallback, which is a useful reference point for the other hops. Verify with a protocol scan or packet capture on each link, by sending a request with no token to confirm it is refused, and by confirming the connector rejects certificates it cannot validate.
Audit gaps for automated changes
Changes made by a provisioning account can look identical to administrator edits unless the account is named and its actions are recorded. Decide which admin and user events you capture, where they are stored, how long they are kept, and how they reach your SIEM. Verify by running a test create, role change, and deactivation through the connector, then tracing each one back to the service account in your log store.
Running Keycloak SCIM sync after go-live
After go-live, SCIM provisioning becomes an operating duty, not a project deliverable. Someone must own the sync jobs, watch their errors, and act on failed create, update and deactivate requests before they turn into access problems. Decide who receives those alerts, where failed requests are recorded, and how long a failure may sit unresolved. Keycloak exposes Prometheus-format metrics at /metrics on its management interface when started with --metrics-enabled=true, which gives you request and cache data to alert on. Metrics show that calls failed, but not whether the right HR record was applied, so pair them with periodic checks against the source system's own logs.
Reconciliation is the control that catches what error monitoring misses. On a schedule you set, compare the users and groups in Keycloak with the source of truth, whether that is the HR system or the identity governance tool feeding SCIM. Look for accounts that exist in one system but not the other, group memberships that differ, and attributes that drifted. Drift often comes from administrators editing users or groups in the admin console, which the provisioning flow never sees. Agree in advance which system wins for each attribute, and record every correction so auditors can trace who changed what.
Duplicate and conflicting usernames need a written rule before they occur. Choose which attribute is the stable identifier, such as an employee number or a corporate email address, and decide what happens when a name change, a rehire or two people with the same derived username arrive in the same window. Confirm how the SCIM endpoint responds to a uniqueness conflict in your version, and test that response in staging. Assign one owner to resolve conflicts, and log each resolution so a reassigned username does not inherit the previous person's group memberships.
Provisioning changes must survive Keycloak upgrades, and the upgrade process is where they are most likely to break. Keycloak's plan includes four minor releases a year, and since Keycloak 26.0 breaking changes in a minor release are opt-in, so read the upgrade notes for every release you adopt. The 26.8 notes, for example, cover SMTP StartTLS, backchannel logout token validation and login failure storage, so confirm whether any of them touch your environment. The Keycloak Operator documentation strongly recommends manual approval mode for operator updates. Database schema migration runs automatically at startup by default, so decide whether your team applies it manually, as the upgrading guide suggests for large deployments. After each upgrade, re-test provisioning in staging: create, update, deactivate, group add and remove, and a username conflict, then keep the results as evidence.
Limits to confirm before you commit to a provisioning design
Each card names a limit that depends on your Keycloak release, your identity source and your infrastructure. Confirm them in a proof of concept before you write the provisioning design, because a change in any one of them can alter the attribute mapping, the leaver rules or the sync schedule.
Operations exposed by your Keycloak version
Confirm that the Keycloak release you plan to run exposes the user and group create, read, update and delete operations your identity source will call. Check this against the exact release you will deploy in production, and test a full sync cycle in staging. The current release is 26.8.1, and minor releases arrive several times a year, so plan a validation step for every upgrade.
User profile attribute coverage
List every SCIM attribute your HR or governance source sends, then map each one to a user profile attribute in Keycloak. Confirm which attributes are built in, which need custom user profile definitions, and which validation and required rules apply. A value the profile rejects can fail the whole record, so check how unmapped attributes are handled and whether email, username and an external identifier are stable enough to serve as matching keys.
Group nesting and role assignment
Decide how source-system group hierarchies translate into Keycloak groups, which groups stay flat and which are nested, and whether membership grants realm roles, client roles or both. Test a nested group that inherits a role from its parent, and confirm that the SCIM group resource can express every membership change your source emits. Write the mapping table before you configure any sync, because an unclear mapping can leave users with access they should not hold.
Disable versus delete on leavers
Confirm what a SCIM deactivate or delete request does in your Keycloak version. Disabling keeps the account, its event history and its group memberships for audit and rehire, while deletion removes them and can break references in audit records and downstream applications. Agree the retention rule with your compliance owner, document which action the source sends for each leaver type, and test that a disabled user is refused at sign-in and that existing sessions end as expected.
Support status of extensions and connectors
Identify every component outside the Keycloak core that sits in the sync path, such as a custom SCIM extension, a provisioning connector or a community-maintained package. For each one, confirm who maintains it, which Keycloak and source versions it supports, and whether a vendor or community commitment covers security fixes. If your governance tool is midPoint, its connector catalog labels entries from supported to experimental, so check the label on the SCIM2 connector you plan to use.
Database and high availability architecture
Confirm the production database and the high availability design before you set the sync schedule. Keycloak supports several production databases, including PostgreSQL 14 to 18, and documents three high availability architectures, with both supported multi-site designs requiring a synchronously replicated database. Provisioning writes many records in bursts, so ask how your chosen architecture handles concurrent writes and whether your database team can support synchronous replication across the sites you plan to run.
Questions buyers ask about Keycloak SCIM provisioning
Does Keycloak include native SCIM support in my version?
Confirm this in the documentation for the exact version you plan to run before you scope any work. Check the server administration guide and the release notes for that version, and do not assume that a newer release includes a SCIM API. The current release is 26.8.1, published October 13, 2026, but the release number alone does not tell you which endpoints, operations or attributes your build exposes. If support is absent or partial, the work shifts toward a custom extension or an external provisioning component, which changes the effort, the testing and the upgrade plan. The software is licensed under Apache 2.0, so your costs sit in design, build, testing, hosting and operations. Ask any partner to state in writing which version and which SCIM operations the quote relies on.
What drives the cost of Keycloak SCIM provisioning work?
The main drivers are the number of source systems sending users and groups, the number of attributes that must map into the user profile, and how much custom transformation logic sits between the source and Keycloak. Testing and deprovisioning rules are often the largest share of the effort. Every leaver case, group removal, error path and rehire scenario needs a defined expected result and a test. One-time costs include discovery, mapping design, build, test and go-live. Recurring costs include your staff time for reviewing failed events, handling Keycloak upgrades and maintaining mappings when HR fields change. The partner is paid for design, build, test and handover, and you carry internal review time. Ask the quote to separate these lines so you can see which costs fall to your team.
How long does Keycloak SCIM provisioning take to implement?
The duration depends on scope, and this page does not give a figure that applies to every environment. The drivers are the number of source systems, attribute complexity, the number of group and role mapping decisions, and how many environments (test, staging and production) the change must pass through. Schedule risk usually comes from HR data quality, approval cycles and access requests for the service account, rather than from the SCIM calls themselves. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Ask for a phased plan with milestones, and ask which dependencies sit with your HR and identity teams so you can plan their time alongside the build.
What do HR and identity teams need to provide for provisioning?
HR needs to confirm which system is the authoritative source for joiners, movers and leavers, which fields are authoritative, and how employment status and effective dates are recorded. The identity team needs to decide the user profile schema, the group naming convention, the mapping from roles or departments to groups, and the deprovisioning policy, including whether leavers are disabled or deleted and how quickly that happens. Both teams should name an owner for exceptions, such as contractors and shared accounts. You will also need sample records, a non-production realm for testing, and a sign-off process for mapping changes. Decisions made late in the build are the most common cause of rework, so agree these before mapping work begins.
Can our internal team implement Keycloak SCIM provisioning alone?
Yes, if your team already runs Keycloak in production, has an engineer who understands the SCIM protocol and the Keycloak user profile, and can staff testing and ongoing operations. It becomes harder when the source is an HR system with inconsistent data, when group membership must follow a role model, or when you need evidence that leavers lost access within a defined process. Before deciding, answer three questions: who owns the service account and its credentials, who reviews failed provisioning events each week, and who performs the next Keycloak upgrade and retests provisioning afterward. If any of those answers is unclear, a fixed-scope engagement can cover design and handover while your team builds the operating routine.
What should a fixed-scope quote for SCIM provisioning list?
A written quote should list the Keycloak version and target environments, each source system and the objects it sends (users, groups or both), and an attribute mapping table with any transformations. It should name the service account and the permissions it needs, the group and role logic, and the deprovisioning rules, including timing and exceptions. It should describe error handling, reconciliation between the source and Keycloak, and the test plan with its cases. Also include documentation, handover, what you must provide, what is excluded, and whether post-go-live support is covered or sold as a separate retainer. DeployOpen does not publish a price list, and a quote follows from the written scope, so a clear scope is what makes two quotes comparable.
Which service account permissions does Keycloak SCIM provisioning need?
Grant the service account only the realm management roles that the chosen operations require, and scope those roles to the target realm. Confirm the exact role names and the operations they allow against the administration REST documentation for your Keycloak version, since this page does not list them. Avoid granting administrator console roles or realm-wide administrative rights unless a documented operation needs them. Separate the account used for production from the one used for testing, store its credentials in a secrets manager, and set a rotation schedule. Test the account with the smallest permission set first, then add permissions only when a specific operation fails and the need is documented.
What breaks most often in Keycloak SCIM provisioning?
The most frequent failures are attribute mismatches, such as missing required fields, date or phone formats that differ from the profile, and values that exceed the length the profile allows. Matching keys cause the next group of problems: a changed email address or a username collision can create duplicate accounts or update the wrong one. Group membership drifts when two sources disagree about who belongs to a group. Deprovisioning can disable an account without ending its active sessions or tokens, which you must check against your session settings. Upgrades can also change behavior, so retest after each one. Ask for a reconciliation report that compares the source and Keycloak on a schedule, so drift is visible before users notice it.
How DeployOpen scopes and delivers Keycloak provisioning
DeployOpen plans, implements, tests, documents and supports Keycloak in infrastructure you control, and SCIM provisioning is treated as part of that same delivery. Each engagement starts from a written, fixed scope that sets out the source systems, attribute mappings and group rules before any build begins.
How we scope
- Inventory the HR or identity governance source and the user and group data it will send to Keycloak.
- Agree which SCIM attributes map to Keycloak user profile fields and which attributes stay out of scope.
- Define the service account permissions needed to create, update and deactivate users and manage group membership.
How we build
- Configure the Keycloak user profile and group structure to match the agreed attribute map.
- Build the provisioning flow and test create, update, deactivate and group membership changes end to end.
- Run negative tests for rejected requests, duplicate users and attribute conflicts in a non-production realm.
How we hand over
- Document the attribute mapping, service account scope and group rules in a runbook your team owns.
- Walk your operators through provisioning logs, known failure cases and how to rerun a failed sync.
- Keep provisioning configuration in version control so changes to mappings can be reviewed before they ship.
How we support
- Offer ongoing support, upgrades and testing as a retainer after handover, scoped in writing.
- Review provisioning behavior after each Keycloak upgrade, since minor releases can change defaults and behavior.
- Agree in the written scope which issues the retainer covers and how they are escalated to DeployOpen.
