keycloak-orgs puts tenants, roles and invitations inside one Keycloak realm

One realm, many tenants, and two rejected alternatives

The framing in the readme is blunt about the alternatives. If you search for multi-tenant Keycloak you will find several opinionated approaches, each promising, and each with their own trade-offs, and this project represents one such approach. It was built initially for a multi-tenant, public cloud SaaS application and has since been adopted, in the form of the Phase Two cloud offering, by several other companies for the same purpose. The two approaches the authors tried and decided against are named explicitly, and one realm for each tenant, and using existing Keycloak groups to model organizations, roles and memberships. The stated reason is that each of these approaches had trade-offs of scale or frailty they found undesirable or unacceptable, which is a specific and useful claim. The alternative they chose is to make organizations, and their invitations, roles and memberships first-class entities in Keycloak rather than a convention layered on top of the group model.

Four definitions that carry the whole model

The Definitions section sets out the vocabulary, and it is the part to read before the extension list. Organizations are tenants or customers as commonly used, and a realm can have multiple organizations. Memberships are the relationship of users to organizations, and a user may be a member of several. Roles are mechanisms of role-based security specific to an organization, much like Keycloak realm roles and client roles, with a set of standard roles covering organization data visibility and management, plus the ability for administrators to create roles unique to one organization, which members of that organization can then be granted. Invitations allow users and non-users to be invited to join an organization, and can be created by administrators or by organization members with the relevant permission. The fourth definition, domains, is the one that is easy to miss, since email domains are used to automatically select the organization identity provider through the optional authenticators, with a facility to validate customer domain ownership using DNS records.

The extension list maps to a multi-tenant application's data model

The contents listing is effectively a feature inventory for a multi-tenant product, and it is grouped by the kind of Keycloak concept each extension touches. There is a data section covering models, entities, resources and mappers, which is the persistence layer, and an events section for the things the extensions emit. Authentication covers invitations, IdP discovery and conditional attributes, which together handle the awkward part of tenancy, deciding which identity provider and which attributes apply to a user who belongs to several organizations. Then there is import and export of organizations, a global organization settings concept, organizations shared IDPs, and SCIM which is marked experimental. The readme also points at a separate document about Keycloak's upcoming organizations feature, with an exclamation mark calling it out, and a note that the extensions are used in the Phase Two cloud offering and released here as part of a commitment to making its core extensions open source.

Building from source is one Maven command, and formatting is enforced

The build and test instructions are short and the enforcement is the interesting part. You check out the project and run mvn clean install, which builds the source, runs all the unit and integration tests, and produces a jar in the target directory. The build enforces Google Java formatting standards via Spotless, and the format plugin was recently switched, with Spotless replacing the previously used fmt-maven-plugin, so mvn spotless:check verifies formatting and mvn spotless:apply fixes it.

mvn spotless:check

mvn spotless:apply

For teams that want the rule applied without thinking about it, there is a provided git pre-push hook.

mvn spotless:install-git-pre-push-hook

When you push, the hook runs spotless:check, and if violations are found it automatically runs spotless:apply, aborts the push, and lets you review and commit the formatted files before retrying. There is also a Cypress test suite, documented separately under cypress-tests, which is the part of the setup that matters most for a Keycloak extension, because an extension that breaks a login flow in a browser is not a slow failure but a broken one.

A Docker image is the path of least resistance for a first run

The quick start section points at a Docker image hosted on quay.io under the phasetwo organization, with the documentation and examples for using it in a separate phasetwo-containers repository, and the most recent version of the extension included in the image. That is a sensible default because a Keycloak extension has to be built into the server distribution rather than dropped in as a plugin, and the readme makes that point in the installation section, noting that the maven build only produces a jar. So the deployment shape is a container image that already contains the extension, which removes the need to understand the Keycloak build system before you can see the feature working. The hosting is also the fastest route to a working multi-tenant setup, and the readme positions it as an alternative to running Keycloak yourself, with a 30-day free trial mentioned for the hosted offering.

IdP discovery is the feature that makes shared tenants work

Two of the authentication features deserve separate attention because they are where multi-tenancy usually breaks. IdP discovery is the mechanism behind the domains definition, since email domains are used to automatically select the organization identity provider using the optional authenticators, and validating customer domain ownership through DNS records is how an organization proves it controls the domain it claims. Conditional attributes then applies those selections to what a user sees. For a SaaS product where each customer brings their own identity provider, this is the difference between one login page and a per-customer redirect. The organizations shared IDPs feature in the contents listing extends the same idea to a different case, where several organizations point at one provider. A notable constraint is that the readme also says to consult the license for information regarding use and to look at the license in the COPYING file, which is a different arrangement from the MIT or Apache terms that most Keycloak extensions carry.

SCIM is experimental, and the upstream feature note is a real risk

Two caveats in the readme deserve to be read before anything is built on this. The first is that SCIM is marked experimental in the contents listing, and SCIM is the provisioning standard that enterprises ask for when a vendor wants to push users from an identity provider into an application, so the feature you are most likely to be asked for is also the one the project flags as unfinished. The second is the note about Keycloak's upcoming organizations feature, which the readme points at with a documentation file of its own. That is a direct statement that the platform vendor is working on the same concept upstream. If that ships with a comparable model, the argument for running a custom extension weakens considerably, and if it ships with a different model, an application built against this extension may need rework either way. The project also links a Keycloak DevDay 2024 presentation about the extension, which is the best available explanation of the design decisions.

Where keycloak-orgs is the wrong choice

The first wrong case is a single-tenant application, where a realm is already the boundary you want and a whole tenancy layer is a cost with no payoff. The second is a team that wants the standard Keycloak model rather than an extension of it, since the alternative the project itself rejected, using groups for organizations, roles and memberships, is available in every Keycloak and needs no custom build, and for many applications the scale and fragility objections do not apply. The third is a team that cannot accept a custom licence, and the readme points to a COPYING file rather than reproducing the terms, so a procurement review has something to read but not something to assume. The fourth is a deployment that cannot use a custom Keycloak build, since the extension has to be inside the server, which is a different and heavier release process than adding a plugin. The fifth is anyone planning around the SCIM story, since that part is experimental and the import and export of organizations is the part you would most want to be reliable.

Editorial conclusion

Platform teams building a multi-tenant SaaS on Keycloak, who want tenancy modelled as a domain concept rather than as realms or groups, are the people this extension set is for, and the fact that it is the code running the Phase Two hosted offering means it has been exercised in production by someone other than its authors. It is the wrong choice for a single-tenant application, where a realm is a perfectly good boundary, and it is the wrong choice for a team unwilling to run a custom Keycloak build, since the readme notes that the maven build only produces a jar and that an installation step follows. Check three things before you commit: the note in the docs about Keycloak's upcoming organizations feature, which the readme flags with an exclamation mark and which could change the shape of this extension, which provider you use for your user federation, since the IdP discovery and conditional attributes features assume more than one identity provider is in play, and the licence, which the readme points to a COPYING file rather than summarising. The last push was on 2026-10-16, the repository publishes no GitHub releases, and the artifact is published to Maven Central under the io.phasetwo.keycloak group id.

Frequently asked questions

Official sources

1. Issues
2. p2-inc/keycloak-orgs on GitHub
3. Project website
4. README