have you considred keycloak extension https://github.com/p2-inc/keycloak-orgs ?

Great write up @alice-wondered ! Couple of questions:

Allow users to be a member of one and only one tenant

Why only one? The approach we took in our orgs extension was specifically to allow a User to be members of multiple tenants, which is a common use case in SaaS applications. E.g. a Tenant might have employee users with @acme.com emails and contractors with @gmail/hotmail/yahoo/etc.com emails. The contractors would likely be members of multiple tenants. At least that's the example given by multiple customers that drove us to implement it this way.

Usernames should be unique within a tenant

Given this is already true for a Realm, isn't this redundant?

Tenants should be able to have groups

Does this mean that a Tenant can have a Group that is specific/unique to that Tenant, or that Groups can be used by Tenants, and assigned to members as a tuple? In our modeling of organization roles, we tried both approaches. One where each Tenant can have a unique set of Groups, that only their members can be associated with. The other where we use standard Groups, but the users are associated with those Groups only in the context of their Tenant (e.g. implemented as a different claim).

Allow users to be a member of one and only one tenant

I also think this is too strict, as I see use cases outlined by @xgp in practice. A rule that might work could be that a user has only one "home" tenant that effectively owns the account (e.g., that manages the credentials). Still, allow explicit (directed) tenant trust relationships that will enable users from tenant1 to sign in to tenant2. This could work similarly to identity brokering across realm boundaries, where a "proxy" user is created in the target tenant to grant access to tenant-specific applications.

A feature that should IMHO be considered from the start is the ability to configure settings, policies, or clients across all (or a subset) of the tenants.
One solution could be to declare a tenant as a "template" tenant, which provides default configurations for a set of tenants. A tenant could refer to one optional "template" tenant. If a tenant-level configuration item is not present on the tenant directly, the respective configuration from the template is used if configured. I don't want to introduce tenant template hierarchies, so tenant templates don't allow the configuration of another realm as a template.
There could be multiple tenant templates within one realm. This allows for sharing configuration across (sub-sets of) tenants in a flexible way.

Another often requested feature request I get in practice is the ability to express tenant-specific password policies.

Thanks for the feedback! I'm going to try and answer everything and hopefully keep the discussion going!

Why only one tenant?

The goal that we were trying to accomplish by setting this restriction wasn't to lock down users into only accessing the resources of a single tenant. Instead, we're trying to focus on who has authority over an account and ensure that this is enforced at all times.

For instance, a user that belongs to the 'Acme-A' tenant would be subject to the authority of that tenant's admins and the policies they set up (2fa, password policies, account deletion, so on).

It is definitely true that some users, like contractors, will need to be able to work within multiple tenants. The enforcement of a user 'belonging' to one and only one tenant should not be a bound on authorization. Google Drive is a great showcase, in my opinion, of how this behavior works. Members of the Acme-A google workspace can still invite users from any other google workspace (or individual account) to access resources within their drive. This allows control over access without requiring authority over the account itself.

This may not be desire-able in all cases, as then you wouldn't be able to enforce tenant policies over the account in question and it could cause potential security issues. Because of that, another function that we have in mind leads into the next question

Why specify that usernames should be unique within a tenant?

The goal would be to change the username uniqueness constraint slightly so that they have to be unique within any Realm,Tenant combination. This would enable multiple user123 accounts to exist in a realm, but only if they are all within different tenants. You would then be able to uniquely identify accounts based on their user id as well as some readable name; for example user123@acme-a.

This would enable the ability to map a single email address login to multiple usernames, all of which could be the same but belong to different tenants. By signing into keycloak with your email, you would then be prompted to select the specific tenant that you want to login as. An extension could also be made to allow account switching, easily allowing a contractor to switch between different tenants depending on the client they're working with.

This would give the appearance of having only 'one' account that is jumping between tenants. But under the hood each account would be subject to the authority of the tenant that it belongs to.

@thomasdarimont I think this is really similar to the idea that you proposed of having a 'home' tenant. Though in this case because each account is distinctly different I suppose the major difference is that there is no proxy and that each tenant would still have authority over the account in question.

Tenant Groups

In regards to having groups on tenants, the idea is to enable the same permission composition that is available to realms on tenants. Ultimately I think it would be a good idea to have group information mappable to claims for the tenant as well, as that could inform decisions for things like authorization or even UI configurations.

I don't think that we would do too much with groups here other than specify that groups can't be moved across tenants (or from a realm into a tenant, or backwards) and that users can only belong to groups that are either within their realm or their tenant. There would also be a bit of work to make sure that moving groups to different parents enforces these boundaries as well.

This would effectively allow an admin within a tenant to make groups for their users (and I guess the implicit feature that goes along with this is tenant specific roles) and organize users how they please within groups.

I see this feature being extremely helpful for mapping LDAP/AD information into a tenant in the future.

@thomasdarimont completely agree on considering settings, policies, and clients. The authorization behavior within keycloak is extremely flexible so this shouldn't be much of a concern outside of building out the boiler-plate needed for allowing that behavior. Settings and clients will take a bit more thought, but there are a few different ways forward. Tenants should definitely have an attributes field similar to how groups work (as well as other resources) now. That should at least allow some amount of basic configuration to take place just to keep track of meta-data. However, as you mentioned, things like password policies and 2FA enforcement that is tenant specific is often highly requested.

While we're focusing first and foremost on establishing the authority of a tenant over a user, I do agree that these are things that need to be able to be added. Having discrete tenant service provider interfaces should help in crafting that behavior. If the SPIs go in the direction of how UserStorageProvider works, we could even craft different capability interfaces for tenants that are all implemented by default in keycloak but allow for pre-existing solutions that users may have to be adapted to use keycloak (or even fully custom tenant behavior for any reason the user may desire)

Hi @pedroigor Thanks for the thoughtful evaluation. I think you understand it well. Regarding the specific points:

Current requirements addressed:

• ✅ Ability to create an organization within a realm
• ✅ Ability to bind an organization to a valid domain
• ✅ Ability to bind an organization to a single broker so that users from it are federated and bound automatically with an organization We have experimented with allowing multiple brokers per organization, but it is not released yet.
• ✅ Ability to invite users to join an organization
• ✅ Ability for a single persona to authenticate to multiple organizations
• ✅ Ability to map organization metadata into tokens
• ✅ Ability to create organization-specific roles and assign these roles to users within the organization
• ✅ Ability to authenticate users from organizations so that they can access realm-level clients and resource servers.
• ✅ Ability to manage an organization by its members and depending on the administrative roles available from the organization

Future/Unimplemented:

• Ability to create service accounts within an organization to support M2M authentication and authorization We're working on this right now, but haven't come up with an implemetation strategy yet. Client Credentials Grant / machine-to-machine auth in organizations p2-inc/keycloak-orgs#163
• Ability to manage groups within an organization so that its members can be organized in departments or in any other form that makes sense. Including role assignments at the group level. Currently under discussion [Discussion] Organization tiering (permissions) p2-inc/keycloak-orgs#148
• Ability to set authentication policies on a per-organization basis Haven't had this request yet

Please let me know if I can help as you try it out. Also, I'll be giving a presentation on the orgs extension next week at @dasniko 's Keycloak Dev Day in Frankfurt in case you'll be there (in person or virtually). I'll also try to post the video here afterwards.

@xgp Thanks. I guess those are the top-level requirements you want/need from upstream and perhaps what makes sense to deliver first. If so, I would like your help (and from others) to get more details about each requirement so that we can start thinking about how to start implementing it upstream.

I would like to start creating some epics/issues for each of those requirements.

Please let me know if I can help as you try it out. Also, I'll be giving a presentation on the orgs extension next week at @dasniko 's Keycloak Dev Day in Frankfurt in case you'll be there (in person or virtually). I'll also try to post the video here afterwards.

Too far away ... But it would be nice to watch the video. Please link it here.

@xgp are you able to share the video? thank you.

@lsmith77 I don't have a copy of it. @dasniko has said he will post it to his Youtube channel once he has time to edit it.

It's now published: https://youtu.be/DNq51wWw3F4

Sure @pedroigor .

Keep in mind that one of our primary restrictions was the we could not modify Keycloak functionality, and that we were restricted by only what was available to extensions. Per my comment above, I think this effort is a great opportunity to revisit the extension points and implement multi-tenancy as an extension.

Realms

For this, we investigated creating a mechanism for external Realm "templates" that would allow us to easily create different "types" of "child" Realms, and make the associations within another "parent" realm that they would be brokers to. We encountered a few problems:

• Scalability beyond ~400 Realms in a single instance
• Fine-grained authz didn't allow the specific permission combinations we wanted, and there were many problems in the Admin UI representing certain sets of realm-management role combinations
• Our execution of creating a new "child" Realm required an external application (kind of like keycloak-config-cli), and was cumbersome to use
• Using the Keycloak Admin UI was intimidating/confusing to Organization admins. This was the takeaway of our user testing.

Our conclusion was that it was far from "free", it came with significant scalability and complexity costs, and ultimately wouldn't work in the existing Admin UI

Groups

We considered this more seriously, as we had already done a prototype for a customer using Groups. We tried 2 approaches

1. We modeled Organizations and Organization-specific Roles as Groups, using a naming convention.
2. We created a Group and a Client for each Organization. Organization-specific Roles were created as Client Roles and mapped with child groups 1-1.

We encountered the following problems:

• Huge proliferation of Clients, Client Roles and Groups. Because everything was by convention rather than enforced in the application, it was brittle and prone to problems in case of changes (or a curious user started messing around).
• Making changes to "roles" required applying a template to all Groups and Clients (e.g. if I wanted to add a manage-photos role, I have to add it to all Groups (as in 1) or all Groups and Clients (as in 2).
• Neither approach allowed us to do delegated authz for things like Identity Provider (our primary goal) or Clients. I.e. there was still no ability for an Organization to "own" an IdP/Client/other entity.
• As in the Realm approach above, it was dependent on an external application to apply changes.

When you say "advanced groups", are you talking about this proposal? I think that's basically an description of our orgs extension, using changing Groups in Keycloak as the implementation strategy. I don't really have an opinion on the value of doing that over making a first-class Organization entity, other than that overloading probably makes sense to us (developers familiar with Keycloak), but will produce confusion among others. I see it from the perspective of "let's change as little as possible", but forgetting that this is actually a significant change, and how we communicate it (through design of the feature, as well as documentation) is paramount. One side note is that a non-insignificant reason we chose to create a first-class Organization entity was that other companies (e.g. Auth0 and nascent companies like Zitadel and WorkOS) were using the same terminology and features at the time. Developers will more easily understand and adopt something that is familiar.

I can't speak for anyone else but I personally find this really useful as input for the design/solution discussion, so thank you for the write up!

@pedroigor I have one question about the implementation. In our current solution each organization has the ability to choose the authentication methods (email/password, google, microsoft, saml ..). we do plan to offering organization specific login screens using custom domains. but we wonder if your solution plan includes this ability.

at the same time if a user is a member of 2 organizations with the same email, we would ideally then have some way to force the user to use the organization preferred login method before gaining access.

I guess the flow would be as follows:

• User requests access to organization A
  • User opens organization A's login screen
  • User is presented with the specific login methods defined by organization A
  • User logs in and gains access to the organization A
• User uses the organization switcher to switch to organization B
  • Organization B requires different login methods
  • User is send to organization B's login screen

So what we would hope to see supported:

• Ability to define allowed login methods on a per organization basis
• Ability to identify login method used in the access token (afaik already available today)
• Ability to check login allowed methods on a per organization basis
• Ability to force re-authentication using the allowed login methods by an organization (ideally in parallel with previous logins to allow easy back and forth switching).

This would still require the application to check if the correct authentication method is used before granting access to the organizations data.

The question we now face is if we should push back our timeline to instead adopt the keycloak internal solution from the get-go. This is of course as much of a technical as it is a business decision that we will have to take. It of course also depends in part on the migration path from phaseTwo over to this keycloak internal solution.

From my reading, phaseTwo code isn't being adopted but design input is collected from @xgp and it appears that the path taken will be very similar from an API point of view.

We are not considering a migration plan for those using the P2 extension. But both share the same core requirements where these requirements are being gathered from this discussion and use cases at Red Hat.

We are focusing on B2B use cases and that is why I asked about what you meant by "SaaS" in your previous comment. SaaS involves more things than what we are planning for Keycloak Organization and we are not delivering the possibility of using Keycloak as an (S)IaaS (not yet).

Our main goal with Keycloak Organization is to leverage the existing (IAM) capabilities we have to solve B2B use cases. That means solving all the core requirements herein discussed and those you mentioned above:

• Ability to define allowed login methods on a per-organization basis
• Ability to check login allowed methods on a per organization basis

We are considering this capability. It is related to what is being discussed (so far, I think only internally within core-clients team) around authentication policies. In a nutshell, you should be able to specify how organization members authenticate to an organization (using mechanisms other than the identity broker bound with an organization) so that you can enforce different factors and steps during authentication.

What else do you have in mind about this one?

• Ability to identify login method used in the access token (afaik already available today)

Yes, we just leverage what we have today. Not only amr but also acr.

• Ability to force re-authentication using the allowed login methods by an organization (ideally in parallel with previous logins to allow easy back and forth switching).

We have this requirement from use cases at Red Hat. And this one is a bit more hairy considering how we handle browser sessions today. I guess you mean here something like Google where you can switch between accounts, right?

This one should not be part of a v1 of Keycloak Organization.

Out of curiosity, some of the requirements above are not available yet from P2 extension, are they?

@lsmith77 One last thing, and about themes. Did you mention the possibility of having customizations to login themes on a per-organization basis?

This is a tricky one and how much we can do depends on how far we want to allow customization to themes. There is a very thin border-line between SaaS and B2B, I think, where the latter does not imply the same level of customization when you are doing SaaS.

wdyt?

@pedroigor ok thank you. I guess once the solution is released work on a migration path can begin from the p2 community. that being said, we will likely plan our solution in such a way, that we could re-create the organization setup in keycloak from our own app specific database which would ease a possible migration.

You mentioned that you want to support org specific login methods and the ability to force users to re-authenticate based on those requirements. Doesn't this then mean that users will then need to authenticate against a specific organization? Which in turn would mean it is all the more relevant to offer organization specific login screens.

The way we had planned to deal with this with p2, where afaik you do not authenticate against a specific organization (though organizations can setup their own providers), was allow users to select the organization. we would then introspect the authentication token to determine what login method was used and if the login method is not acceptable to the chosen organization force them to authenticate with an acceptable login method.

You mentioned that you want to support org specific login methods and the ability to force users to re-authenticate based on those requirements. Doesn't this then mean that users will then need to authenticate against a specific organization? Which in turn would mean it is all the more relevant to offer organization specific login screens.

Not necessarily as authentication and themes are distinct aspects. I see your point and I can see some level of theme customization on a per-organization basis. However, how much we want to customize will proportionally add complexity to the feature. The main reason is that organizations are not managing Keycloak installations and deploying their own themes so we need to come up with something else, from the administration console or organization self-service, to allow organization administrators to customize the L&F.

The way we had planned to deal with this with p2, where afaik you do not authenticate against a specific organization (though organizations can setup their own providers), was allow users to select the organization. we would then introspect the authentication token to determine what login method was used and if the login method is not acceptable to the chosen organization force them to authenticate with an acceptable login method.

Selecting an organization is something we need more discussion. In the first version, realms must be set with an identifier-first login flow so that Keycloak can easily map the user's email domain to an organization. As a result, it will automatically redirect the user to the identity provider associated with it. See #28273 and feel free to comment there.

We are leveraging groups behind the scenes to assign members to an organization. By doing that, having the same users in two distinct organizations is a matter of a user joining a group.

Would that mean, that creating an organization also create a group behind the scenes?

As mentioned before, as we have organizations backed by a group, assigning a realm/tier role to an organization could automatically grant these roles to all its members.

Yes, tier idea is based on the current group logic where assigning a role on the group assign it to all members. Idea would be the same for organizations.

Not sure exactly what you mean by configure SSO but the @keycloak/core-clients team is designing authentication policies. Based on this feature you'll be able to manage the different authentication aspects of a realm. Like authentication flows but without all the burden of managing flows and steps.
Keycloak Organization will leverage that to deliver authentication policies on a per-organization basis.

Sorry I was referring to the capacity to create / assign organizations specific SSO. So, when I try to login with my company email which use a specific SSO, I'm redirected to authenticate there.
Then, from a KC Administrator, there is multiple SSO, but from an organization POV (self-managing) I can see my SSO and configure it.

I'm not sure if it's covered by what you mentioned same as for "Organization level password policies or 2FA enforcement.". If it's the case, let me know.

Perhaps "also delete associated users if the organization is deleted" is a matter of who "owns" the user?

If the user is "owned" by the organization then deleting an organization (group) could legitimately also delete the users. Think of using the organization as a tenant for a SaaS app who no longer wants to use our service.

On the other hand, if users, who are "owned" by the realm and assigned to one or more organizations, then it's just like a group assignment with more complex rules.

There is also another mixed use case where users might have an "owning" / "home organization" and have some sort of relationship with other organizations (org1 can manage users from org2 and org3).

Is this also already covered by the current implementation?

The first two cases we are covering now by #29029.

The second one is not yet supported as we don't allow an account to join multiple organizations. We are re-evaluating this decision though and perhaps we can try to include this capability in the first release. The argument for not doing it now is that we already have high-priority tasks that are related to the core capabilities and adding support for multiple accounts should not be a hard task once the core capabilities are set in stone.

Wdyt?

Would that mean, that creating an organization also create a group behind the scenes?

@MGLL Yes, this is an implementation detail though and administrators should not worry about these groups and how they linked to organizations.

Sorry I was referring to the capacity to create / assign organizations specific SSO. So, when I try to login with my company email which use a specific SSO, I'm redirected to authenticate there.
Then, from a KC Administrator, there is multiple SSO, but from an organization POV (self-managing) I can see my SSO and configure it.

Yes, we are working on it so that you can have multiple brokers associated with an organization where each broker might be associated with a specific domain (from the domains associated with the organization). When a user authenticates, the user is either automatically redirected to the identity provider that matches the email domain or is presented with a list of brokers to choose.

The second one is not yet supported as we don't allow an account to join multiple organizations. We are re-evaluating this decision though and perhaps we can try to include this capability in the first release.

@pedroigor What is the status of re-evaluating this decision? Such a feature would come in handy for our use cases.

@xgp Do you have something similar in the extension? How are you handling these different types of members or there isn't a distinction at all?

the entire organization concept is optional. so users can be members in 0 to n organizations.

semi-related: when logging in you can set an “active organization” on the access token, either way you can map the list of organizations of the user into the access token.

Feedback I could provide is that indeed organization is optional. So, in the realm, a user can have 0 or n organizations.

On my side, the use case is that deleting an organization shouldn't delete users attached to it.
If you want to go in this path, I recommend making this configurable in realm settings and let KC administrators decide if it should also delete users or not.

If you want to go in this path, I recommend making this configurable in realm settings and let KC administrators decide if it should also delete users or not.

But why you would want to keep users federated from the identity provider linked to the organization when the organization is removed? Going a bit further, how we handle users federated from the identity provider when it is removed from the organization?

Ah sorry, missed the federated from the identity provider part. In that case, yes it makes sense.

how we handle users federated from the identity provider when it is removed from the organization?

I guess the same way, remove the user?
As it is in a federated context, I guess we should remove the deleted user.

@sventorben Yes, please see #30180 for all the capabilities we have identified for this feature. As well as which ones are implemented or being addressed.