When a development team needs to clone a Keycloak realm on the same instance —for example, to create a myrealm-dev environment from myrealm— they run into a classic error: violation of unique key constraints. Exporting the realm from the admin console and importing it back triggers a message like 'ERROR: duplicate key value violates unique constraint'. The root cause is that the export is not a simple configuration file: it is a snapshot of database rows, where every role, client, user, and authentication flow retains its internal UUID. Renaming the realm in the JSON changes the visible name, but the hundreds of UUIDs referencing those objects remain the same. The import attempts to insert records with existing IDs, causing the conflict. This behavior is a known limitation of Keycloak: the exporter was designed to move realms between different instances, not to duplicate them in the same database.
The manual fix, while theoretically possible, is tedious and risky. Opening the exported JSON, locating each UUID and replacing it with a new one can work for small realms with few clients. But in a real realm with custom roles, multiple clients, an identity provider, and full authentication flows, the UUIDs easily exceed a hundred. A single mistake when updating a reference —such as a role's containerId or a client's serviceAccountClientId— does not fail at import time but manifests as a login issue that goes unnoticed until a user cannot sign in. That risk is why an automated tool becomes essential.
Solutions like keycloak-realm-clone exist, a command-line utility written in Node.js that automates the UUID remapping. By running it with the export file and the new realm name, the tool scans every UUID-shaped value, generates a one-to-one mapping from old to new IDs, and rewrites all internal references to maintain consistency. It also handles realm name replacement in fields like redirectUris, baseUrl, and adminUrl, and cleans secrets that come as '**********' so Keycloak generates fresh ones upon import. Some fields like clientId or alias are left untouched because they contain logical identifiers that should not be modified. The result is a JSON file ready to import without conflicts, preserving all relationships between objects.
This cloning technique is especially relevant for companies that deploy multiple development, testing, and production environments with Keycloak as an identity manager. Custom software development often requires rapid realm replication to isolate changes without affecting the production environment. At Q2BSTUDIO, as a software and technology company, we tackle these challenges with a comprehensive approach that combines infrastructure automation, cloud services on AWS and Azure, and artificial intelligence integration to optimize processes. For example, when a client needs to clone a Keycloak realm for a new project, we not only provide the cloning tool but also adapt the configuration to their cloud architecture, ensuring authentication flows and security policies remain consistent.
Proper identity management goes beyond simple login. In scenarios where AI agents interact with secured APIs, or when Business Intelligence dashboards with Power BI consume data from multiple sources, authentication and authorization must be robust and scalable. A failure in realm cloning can compromise the integrity of those systems. That is why at Q2BSTUDIO we also offer cybersecurity and pentesting services to verify that Keycloak configurations do not introduce vulnerabilities, and we advise on adopting BI solutions with Power BI that rely on a reliable authentication layer.
Once the cloned JSON file is ready, the import process requires a few additional manual steps. After uploading the file to the Keycloak admin console, the secrets of confidential clients have been removed; you need to open the credentials tab of each client and copy the newly generated secret for the consuming applications. The same applies to external identity provider credentials or LDAP bind passwords, which have been cleared and must be re-entered. SMTP and theme settings are preserved, but you should review them for the new realm, especially if you want to customize the user experience. These steps are critical to avoid connected services —such as AI assistants or automation platforms— losing their ability to authenticate.
From a technology company's perspective, cloning Keycloak realms is a common operation in the development lifecycle. But doing it manually or with ad-hoc scripts carries a high risk of silent errors. Automation with specialized tools drastically reduces time and uncertainty. At Q2BSTUDIO we integrate these practices into our DevOps and process automation workflows, offering our clients a traceable and repeatable process. Furthermore, we combine identity management with artificial intelligence to detect anomalous patterns in authentication attempts, improving the overall cybersecurity posture of the organization.
In summary, cloning a Keycloak realm on the same instance is a technical problem that has an automated solution, but it requires understanding the implications of internal identifiers and cross-references. For companies looking to scale their development environments without compromising security or operability, having a technology partner like Q2BSTUDIO makes a difference. Our experience in custom software development, cloud, AI, cybersecurity, and BI allows us to offer complete solutions ranging from realm cloning to full digital identity architecture. If your team faces this challenge, do not hesitate to contact us for a personalized consultation.
