Keycloak multi-tenancy extensions for SaaS applications

Extending the server
, ,
1

I’ve open sourced a set of Keycloak extensions that are focused on solving several of the common use cases of multi-tenant, SaaS (Software as a Service) applications that Keycloak does not solve out of the box.

I often read questions here and on the mailing list about how to support different “organizations” (or “tenants”) in a single realm. There is no one approach that solves all of the use cases, but this is a solution that has worked well for several customers with public cloud, SaaS applications.

Some of the features:

  • Organizations are “tenants” or “customers” as commonly used. A Realm can have multiple Organizations.
  • Memberships are the relationship of Users to Organizations. Users may be members of multiple Organizations. These relationships can be used in the token via a mapper.
  • Roles are mechanisms of role-based security specific to an Organization, much like Keycloak Realm Roles and Client Roles. In addition to a set of standard roles related to Organization data visibility and management, administrators can create Roles unique to an organization. Users who are Members of Organizations can be granted that Organization’s Roles. These relationships can be used in the token via a mapper.
  • Invitations allow Users and non-Users (by email) to be invited to join an Organization. Invitations can be created by administrators or Organization members with permission. A custom authenticator processes accepting invitations and automatic organization membership.
  • Identity Providers provide a subset of the Keycloak IdP APIs that allows Organization administrators to manage their own IdP.

Please refer to the README in the repo for more information.

A variation of this code has been built, enhanced and used in production for over two years. I made a few changes in the process of preparing the code for open source, so please let me know if you find any problems.

Enjoy!

10 Likes
2

Sounds interesting and promising! Will defentively check it out. Any way this integrates with LDAP Directory Backend Service?

3

Not currently. What is the use case for integration with LDAP?

4

I’m trying to generate the jar file from the source, but I’m facing some difficult things. I had to install keycloak from source to get some missing dependencies, so after that I could compile and generate the jar file.
The problem is when I put the jar on my keycloak test instance, and call some endpoint related to the library.
The response status is 500. I look at keycloak log to see what happened and it asks for some dependencies. So, it seems like the library compilation process it was no ok on maven.
Could you help me please?

5

The build does require you to install the Keycloak source because it uses some testing libraries that they don’t publish to maven central. I am hoping to switch to testcontainers soon, so that we no longer have that problem.

For the dependency errors you are seeing, would you mind posting the full log in a GitHub issue on that repo, so that I can track it there? Thank you!

6

Hello.
I am thinking of using Keycloak groups to achieve multi-tenancy in a single realm.
What are the issues with the method of separating tenants by groups?(scalability, vulnerability, etc.)
What use cases does your solution match?
Thank you.

7

If you use Groups for multi-tenancy in a single realm, you would need a hierarchy of roles per group. E.g.

org1
- roleA
- roleB
org2
- roleA
- roleB

The extension above has the native concept of per-org roles.

8

Thank you for your immediate response.

9

Update for those who would like to try this out without compiling and installing the extension themselves.

This is now bundled as a Docker image. This image contains Keycloak, this and other extensions. Documentation and examples for using it are in the phasetwo-containers repo.

You can also try it for free in the extension publisher’s new keycloak managed service. See the announcement and demo video for more information.

1 Like
10

how can i integrate the keycloak-orgs extension using dependency injection in Spring Boot ?

11

It’s an extensions to Keycloak, not your application. See the README for information on how to use and deploy.

1 Like
12

ah okay thank you so much

14

That’s quite interesting nice work, I’ll definitely give it a try, as I’m currently building a mutli-tenants saas and was looking at oss iam tools such as keycloak to solve my identity/auth. requirements, but after several readings on the topic, it seems like its ootb multi-tenants support is far from ideal, which has made me start looking at other oss iam solutions.

@xgp, one of the main limitation that I’ve read about keycloak multi-tenants support is with the 1 tenant per realm approach recommendation where it seems like after hitting around 400 tenants/realms, keycloak becomes unusable / very slow, I’m sure you’re aware…

(I’m not even evaluating the other keycloak multi-tenants solution/suggestion of 1 realm total and then1 tenant per group mapping, it feels too much hacky to me and also comes with huge limitations, such as I believe not able to map a very specific external org./tenant IDP to the mapped tenant/group in keycloak, which is acting as an identity broker, that is, a very common requirement in the multi-tenants b2b industry…)

Having said all that, I would have a few questions for you re that extension:

Q1- Do you know roughly how many tenants/organizations your extension can support, before keycloak starts to fall on its knees? If you don’t know, perhaps you know a minimum number that you know for sure still works pretty well, from the current production projects that you briefly mentioned above that are using your extension? (else, perhaps it would be interesting to run some kind of quick load/perf. testing about it, similar to what this guy has done here around number of created ‘realms’, but here in the case of this extension around ‘organizations’)

Q2- Can you confirm my below understanding re your explanation:

  • Identity Providers provide a subset of the Keycloak IdP APIs that allows Organization administrators to manage their own IdP.
    Does this allow me to configure an external IDP for a given organization/tenant only? Is this purely a UI/API admin configuration feature addition, or is there anything else I’m missing with this? Everything else is same as with keycloak ootb functionalities around external identities configs? (e.g., same protocols supported saml/oidc, email/domain mapping, idp-initiated supported, etc)

Q3- What is your docker images release strategy? e.g., I see that you released for instance latest keycloak version 20.0.3 (currently) patched with your extension the same day keycloak made the same version available (quite impressive!), going forward do you plan on always trying to keep up with their releases in a matter of days/weeks/months or even sometimes skip versions etc? I’m just trying to see what to expect if I start using your extension and depend on it for years to come what it may looks like… (obviously, no one has a crystal ball I understand that, so perhaps what are your short/mid term goals here…).

Q4- In preparation for the worst to manage expectations ahead of time, prior to selecting this nice extension, I’m wondering what would be a great migration strategy, if this extension ever stops being released/maintained? Would there be an easy way you think to extract all the custom data that this extension introduces (e.g. the new entities and relations to new or existing/ootb entities/models) by api? If yes, then I suppose one strategy could be to get a new realm created for each extracted organization (and then all the rest should follow, e.g. clients, users, roles, etc), would that make some sense to you?

Q5- Is this discourse group the best place to ask you any other potential questions about your extension, or is there any other ways / location that you prefer (…as I am seriously considering using it, especially since it seems to be supporting the current latest keycloak version at time of this writing, e.g. 20.0.3, and through docker) ?

many thanks!

15

What about posting it as a Github issue? As far as I can see in the Github, the maintainer is quite responsive in the Github Issue page.

16

@Frank-D Here is a brief answer to your questions:

Q1: We’ve got customers using it with over 10k orgs.

Q2: The IdP APIs are built as an Admin API to allow organizations to manage their own IdP. The reason it has to be separate from the Keycloak built-in API is that we had to adapt the permissions model so a single organization couldn’t see/manage all the IdPs, only their own. Otherwise, as you say, everything is “ootb”.

Q3: Our goal is to release within a few days after the Keycloak release. Speed will depend on a set of regression tests we have, and if we have to make any code changes.

Q4: Our best answer to that is that the source code is there. If there were a “good” migration strategy to vanilla Keycloak, we probably wouldn’t have built this in the first place.

Q5: For now, GitHub issues for the keycloak-orgs repo is a good place. We are planning to launch something like a public Slack, Discourse or Discord, but we haven’t decided yet.

1 Like
17

Also, per my answer to Q3, we will likely skip versions that come out in rapid-fire succession. 20.0.5 → 21.0.0 → 21.0.1 looks like it will be a good example. So the next version that we will release will probably be 21.0.1 (It looks like there were some pretty severe problems with the 21.0.0 release that need to be patched immediately), and we will skip 20.0.5 and 21.0.0.

1 Like
18

@xgp
About answer for Q1:
Your design is : realm/tenant per organization(so you have 10k reamls) ? Or you have 1 realm and group per organization(10k groups)?

19

Neither. 1 realm with 10k organizations using the extension above.

20

Hi @xgp

May I ask which database you are using…?

21

The extension has been tested with mysql, oracle, postgres, h2 and cockroachdb.