Chapter 12. Managing organizations

An organization has the following settings:

Once you create an organization, you can manage the additional settings that are described in the following sections:

When managing an organization, the domain associated with an organization plays an important role in how organization members authenticate to a realm and how their profiles are validated.

One of the key roles of a domain is to help to identify the organizations where a user is a member. By looking at their email address, Red Hat build of Keycloak will match a corresponding organization using the same domain and eventually change the authentication flow based on the organization requirements.

The domain also allows organizations to enforce that users are not allowed to use a domain in their emails other than those associated with an organization. This restriction is especially useful when users, and their identities, are federated from identity providers associated with an organization and you want to force a specific email domain for their email addresses.

To disable an organization, toggle Enabled to Off.

When an organization is disabled, you can still manage it through the management interfaces, but the organization members cannot authenticate to the realm, including authenticating through the identity providers associated with the organization as they are also automatically disabled.

However, the unmanaged members of an organization are still able to authenticate to the realm as they are also realm users, but tokens will not hold metadata about their relationship with an organization that is disabled.

For more details about managed and unmanaged users, see Managed and unmanaged members section.

To delete an organization, click the Delete action for the corresponding organization in the listing page or when editing an organization.

When removing an organization, all data associated with it will be deleted, including any managed member.

Unmanaged users and identity providers remain in the realm, but they are no longer linked to the organization.

For more details about managed and unmanaged users, see Managed and unmanaged members.

When managing members, consider how their relationship with an organization affects the lifecycle of their accounts. Members can join an organization through different flows and each flow indicates the strength of the link between their accounts and the organization.

There are two types of members:

Managed members are those managed by the organization, and they cannot exist outside of their organization. For instance, consider an account created through an identity provider associated with an organization. That account does not belong to a realm as it was federated from the organization. In this case, the single source of truth for the identity is the organization and its lifecycle is controlled by the organization. If you remove the organization or the member, the account is also removed from the realm.

On the other hand, unmanaged members are those that can exist without the organization. For instance, when adding an existing realm user to an organization, the account belongs to the realm first and foremost and eventually linked to an organization. In this case, removing an organization or a member will not remove the account from the realm; the realm is the single-source of truth for the identity.

An existing realm user can join an organization by selecting that user from a list and adding the user to the organization.

Once a user is a member of the organization, that user is able to authenticate to the realm just like a regular user and using any credential supported by the realm.

An administrator can email users to join an organization.

Optionally, you can also provide a value for the First name and Last name fields for a more personalized email message using a greeting message with the first and last names of the person receiving the email.

An invitation is basically an email sent with a link that the person should click to perform the necessary steps to join an organization. These steps depend on whether the person already has an account in the realm or if a new account should be created before joining the organization.

If the email maps to an existing user in a realm, the steps the user will follow are basically about confirming the intention to join the organization.

On the other hand, if no user is associated with the given email address, the steps will involve creating a new account through the realm’s self-registration flow. In this case, the user is forced to provide the same email address used to send the invitation.

An organization might have its own identity provider as the single source of truth for their identities. In this case, users federated from the identity provider are automatically added as a member of the organization.

When users join an organization through an identity provider associated with an organization, they are automatically marked as managed members. In this case, they will go through the broker login flows configured in the realm and join the organization automatically once they successfully authenticate.

Onboarding new members through an identity provider can be done by either automatically redirecting the user to an organization’s identity provider or by selecting the identity provider when at the login page.

In both cases, once the user provides the email, Red Hat build of Keycloak will try to match an organization based on the email domain. In case the email domain matches the organization, and an identity provider is associated with the same domain and the Redirect when email domain matches setting is enabled, the user is automatically redirected to the identity provider. Once the user authenticates at the identity provider and completes the first broker login flow, the user is automatically added as an organization member.

On the other hand, if Redirect when email domain matches is not enabled, but the identity provider is configured not to Hide on login page, the user can select the identity provider and then be redirected to the identity provider to continue the onboarding process.

For more details, see Managing Identity Providers.

You can remove a member from an organization.

From the action menu next to the member you want to remove, click Remove.

When removing a member from an organization, remember that the user may or may not be removed from a realm depending on if that user is managed or unmanaged member, respectively.

For more details, see Managed and unmanaged members.

Users coming from federated providers can also be added as members of an organization. The only exceptions are the users from LDAP providers with import mode disabled. Organization members are added to an internal group that is not synchronized with external providers, so even if the LDAP provider has a group mapper with mode LDAP_ONLY it won’t be possible for the non-imported users to be added as members of an organization because that membership won’t be synced with the LDAP server.

In other words, LDAP users that are not imported can’t join an organization because the membership is not stored in the local DB nor in the LDAP server. So if you want to have LDAP users joining organizations, ensure that the import mode of the LDAP provider is enabled.

An identity provider can be linked to an organization from the Identity providers tab. If identity providers already exist, you see a list of them and options to search, edit, or unlink from the organization.

An identity provider has the following settings:

If the org is linked with multiple identity providers, the organization authenticator prioritizes the provider that matches the email domain of the user for automatic redirection. If none is found, it tries to locate one whose domain is set to Any.

Once linked to an organization, the identity provider can be managed just like any other in a realm by accessing the Identity Providers section in the menu. However, the options herein described are only available when managing the identity provider in the scope of an organization. The only exception is the Hide on login page option that is present here for convenience.

You can edit any of the organization-related settings of a linked identity provider at any time.

When an identity provider is unlinked from an organization, it remains available as a realm-level provider that is no longer ssociated with an organization. To delete the unlinked provider, use the Identity Providers section in the menu.

In addition to identifying the user once the username is provided, the identity-first login is also responsible for:

The identity-first login provides the same capabilities that are provided by the usual login page with the username and password fields. Users can still self-register by clicking the register link or choose any identity or social broker that is not linked to an organization in that realm.

In the case of a user that does not exist, if that user tries to authenticate using an email domain that matches an organization domain, the identity-first login page appears again with a message that the username provided is not valid. At this point, no need exists to ask the user for credentials.

Several options exist to register the user allowing that user to authenticate to the realm and join an organization.

If the realm has the self-registration setting enabled, the user can click the Register link at the identity-first login page and create an account at the realm. After that, the administrator can send an invitation link to the user or manually add the user as a member of an organization. For more details, see Managing members.

If the organization has an identity provider without a domain and the Hide on login page setting is OFF, users can also click the identity provider link at the identity-first login page to automatically create an account and join an organization once they authenticate through the identity provider. For more details, see Managing identity providers.

In a similar situation to the previous section, the organization may have an identity provider set with one of the organization domains. In this situation, the user is redirected to the identity provider if that user’s email matches a specific domain from the organization. Once the flow completes, an account is created and the user joins the organization.

As previously mentioned for new realms, authentication flows are automatically updated with the necessary steps to support organizations and authenticate their members. For existing realms, in addition to enabling organizations to the realm, you also need to manually update your existing (custom) authenticating flows.

Change the browser flow by following these steps:

Once you enable the Organizations setting to the realm and create at least a single organization, you should be able to see the identity-first login page and start using organizations in your realm.

Change the first broker login flow by following these steps:

You should now be able to authenticate using any identity provider associated with an organization and have the user joining the organization as a member as soon as they complete the first browser login flow.

If the flow supports organizations, you can configure some of the steps to change how users authenticate to the realm.

For example, some use cases will require users to authenticate to a realm only if they are a member of any or a specific organization in the realm.

To enable this behavior, you need to enable the Requires user membership setting on the Organization Identity-First Login execution step by clicking on its settings.

If enabled, and after the user provides the username or email in the identity-first login page, the server will try to resolve a organization where the user is a member by looking at any existing membership or based on the semantics of the organization scope, if requested by the client. If not a member of an organization, an error page will be shown.