Organizations in Keycloak: Management and Customization of Authentication

Keycloak version 26 introduced several intriguing features that can be effectively utilized in medium and large enterprises. One of these is the “Organizations” feature, which will be the focus of this text. We will discuss how to use and configure it, as well as how it can streamline user management in complex environments.

What are Organizations in Keycloak?​

An Organization in Keycloak represents an entity, such as a client or a business partner. This feature enables:

• Assigning users as members of a specific organization.
• Defining a dedicated administrator for each organization.
• Establishing specific authentication processes for each organization.

By utilizing this feature, Keycloak allows the creation of individualized login processes for different clients within a single system. For instance, users can be identified based on the domain of their email address, which automatically directs them to the appropriate login process.

The Organizations functionality is particularly significant in corporate and inter-organizational environments where user management is complex. Organizations in Keycloak address the challenge of handling diverse login processes and authentication customization. For example:

• Companies providing services to multiple clients can create different login methods and integrations tailored to client systems.
• Organizations composed of multiple business units can independently manage users and their permissions.
• Systems requiring federation with external identity providers can leverage dedicated authentication flows.

Organizations vs. Groups – What are the differences?

In Keycloak 26, the functionality of Organizations and Groups serves different roles, even though both mechanisms are used for user management. Organizations are designed to handle more complex scenarios, such as managing users in the context of various clients or business partners. They focus on authentication flows and identity federation, enabling precise customization of authentication processes to meet the needs of external entities.

On the other hand, Groups are better suited for organizing users within a single application, for example, to assign permissions or define access to resources.

Organization Configuration

For complex authentication systems, the Organizations functionality allows for more precise management of users and their access within specific structures. In the following sections of this article, we will show step-by-step how to configure Organizations in Keycloak, from activating this feature in the realm settings to assigning users to specific groups.

1. Enabling the Organizations Functionality in a Realm To use the Organizations feature, it must be activated within the realm settings:

• Go to Realm Settings > General and enable the Switch Organizations option.
• After activation, a new tab called Organizations will appear in the left-hand menu.

2. Creating a New Organization Go to the Organizations tab, select Add Organization, and fill in the key fields:

• Name: A unique name for the organization displayed in the interface.
• Alias: A unique alias used in URLs (unchangeable after saving).
• Redirect URL: The address where the user will be redirected after registration or accepting an invitation.
• Domains: The domain used to recognize the organization based on the user’s email address.

Automatic Assignment Based on Domain During login, the user provides an email address. Keycloak analyzes its domain and automatically assigns the user to the appropriate organization. This ensures that the user utilizes a dedicated authentication flow. It is worth noting that Keycloak supports wildcards in domain configuration, allowing subdomains (e.g., *.example.com) to be assigned to the same organization.

3. Adding Users to an Organization Users can be assigned to an organization in several ways:

• Existing Users: Add users already present in the realm (Organizations > Members > Add Realm User).
• Invitations: Send an invitation to a new or existing user (Organizations > Members > Add Member > Invite Member).
• Identity Provider: Link an identity provider to an organization to automatically assign users (Organizations > Identity Providers > Link Identity Provider).

4. Viewing Users in an Organization The list of users in an organization is available under Organizations > [Organization Name] > Members. Information about organization membership can be included in tokens as the organization claim. This allows applications to differentiate user permissions.

5. Managing Authentication Flows Organizations in Keycloak allow for the implementation of dedicated authentication flows for users.

• Identity-First Login: The user first provides an email address or username, enabling Keycloak to recognize the organization and apply the dedicated flow.
• Flow Customization: Each organization can have its own authentication flow, allowing the login processes to be tailored to the specific requirements of clients.

By utilizing the Organizations feature, Keycloak enables advanced customization in IAM systems while simplifying user and access management in complex environments.

“The new organization management feature in Keycloak enables the creation and administration of organizational structures, such as departments or teams, significantly streamlining processes like employee onboarding and offboarding, as well as related security issues. For example, during onboarding, a new employee can be assigned to the appropriate organizational unit, which automatically grants them the proper permissions and access to necessary resources, including temporary access (e.g., for temporary employees). Similarly, in the case of offboarding, removing an employee from a given unit immediately revokes their permissions and access to company resources, thereby enhancing data security. This feature makes access management more automated and secure, simplifying HR processes within the organization.”

Ph.D. eng. Andrzej Chybicki CEO Inero Software