Adding organization section (#29796)

Closes #28731

Signed-off-by: Pedro Igor <pigor.craveiro@gmail.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

docs/documentation/release_notes/topics/25_0_0.adoc

@@ -231,3 +231,17 @@ For more details, see the link:{upgradingguide_link}[{upgradingguide_name}].
 = Support for PostgreSQL 16
 
 The supported and tested databases now include PostgreSQL 16.
+
+= Introducing support for Customer Identity and Access Management (CIAM) and Multi-tenancy
+
+In this release, we are delivering Keycloak Organizations as a technology preview feature.
+
+This feature provides a realm with some core CIAM capabilities, which will serve as the baseline for more capabilities
+in the future to address Business-to-Business (B2B) and Business-to-Business-to-Customers (B2B2C) use cases.
+
+In terms of functionality, the feature is completed. However, we still have work to do to make it fully supported in the next major release.
+This remaining work is mainly about preparing the feature for production deployments with a focus on scalability. Also, depending
+on the feedback we get until the next major release, we might eventually accept additional capabilities and add more value to
+the feature, without compromising its roadmap.
+
+For more details, see link:{adminguide_link}#_managing_organizations_[{adminguide_name}].

docs/documentation/server_admin/topics.adoc

@@ -59,6 +59,9 @@ include::topics/admin-console-permissions/per-realm.adoc[]
 ifeval::[{project_community}==true]
 include::topics/admin-console-permissions/fine-grain.adoc[]
 endif::[]
+ifeval::[{project_community}==true]
+include::topics/assembly-managing-organizations.adoc[]
+endif::[]
 include::topics/assembly-managing-clients.adoc[]
 include::topics/vault.adoc[]
 include::topics/events.adoc[]

docs/documentation/server_admin/topics/assembly-managing-organizations.adoc

@@ -0,0 +1,16 @@
+[id="assembly-managing-organizations_{context}"]
+[[_managing_organizations_]]
+==  Managing organizations
+
+:tech_feature_name: Organizations
+:tech_feature_id: organization
+include::./templates/techpreview.adoc[]
+
+include::organizations/intro.adoc[leveloffset=+2]
+include::organizations/managing-organization.adoc[leveloffset=+2]
+include::organizations/managing-attributes.adoc[leveloffset=+2]
+include::organizations/managing-members.adoc[leveloffset=+2]
+include::organizations/managing-identity-providers.adoc[leveloffset=+2]
+include::organizations/authenticating-members.adoc[leveloffset=+2]
+include::organizations/mapping-organization-claims.adoc[leveloffset=+2]
+

docs/documentation/server_admin/topics/organizations/authenticating-members.adoc

@@ -0,0 +1,98 @@
+[id="authenticating-members_{context}"]
+
+=  Authenticating members
+[role="_abstract"]
+When you enable organizations for a realm, user authentication is changed. If the user is recognized to be 
+authenticating in the context of an organization, the authentication flow changes on a per-organization basis.
+
+When a realm is created, the authentication flows are automatically updated to enable specific steps to authenticate and onboard organization members. The authentication flows updated are:
+
+* *browser*
+
+* *first broker login*
+
+The main change to the *browser* flow is that it defaults to an identity-first login so that users are identified before prompting for their credentials.
+Concerning the first broker login flow, the main change is automatically adding the users as organization members once they authenticate through the identity provider associated with an organization and successfully complete the flow.
+
+The choice to use an identity-first login or not depends on the existence of an organization in a realm.
+If no organizations exist, the user follows the usual steps to authenticate using the username and password,
+or any other step configured in the browser flow. Otherwise, the user is asked first for a username or email to continue authenticating to a realm.
+
+The identity-first login main goal is to identify the user:
+
+* Is the user an existing or a new user?
+* Is the user a member of any organization within a realm?
+* If an organization member, is the user linked to any identity provider associated with the organization?
+
+Depending on the outcome when identifying the user, the authentication flow changes to either proceed with authentication
+by asking for the user's credentials or eventually redirect the user automatically to authenticate within the organization security
+boundaries through an identity provider.
+
+== Understanding the identity-first login
+
+In addition to identifying the user once the username is provided, the identity-first login is also responsible to:
+
+* Match an email domain to an organization
+* Decide if the authentication flow should continue or not if an account already exists for the username provided
+* Decide how the user should be authenticated depending on how the domains and the identity providers are configured to an organization
+* Seamlessly authenticate users through an identity provider associated with an organization if the email domain matches the domain set to the identity provider
+
+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_,Managing members>>.
+
+If the organization has an identity provider without a domain and the *Show on login page* setting is *ON*, 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_provider_,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.
+
+== Configuring existing authentication flows
+
+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:
+
+.Procedure
+. Duplicate the current flow bound to the *Browser flow* binding type to avoid breaking the flow you are currently using
+. Click *Add sub-flow* and give it a name such as *My Organization*
+. Move the newly added *My Organization* sub-flow to execute right after the *Identity Provider Redirector* execution step.
+The main point here is that the sub-flow should happen before any other sub-flow or execution step that authenticates the
+user using whatever credentials you support in your realm. Once added, change the *Requirement* to *Alternative*.
+. Click *Add sub-flow* in the *My Organization* sub-flow and give it a name such as *My Organization - Conditional*. Once added, change the *Requirement* to *Conditional*.
+. Click *Add condition* in the *My Organization - Conditional* sub-flow and select *Condition - user configured*. Once added, change the *Requirement* to *Required*.
+. Click *Add step* in the *My Organization - Conditional* sub-flow and select the *Organization Identity-First Login
+* execution step. Once added, change the *Requirement* to *Alternative*.
+. Bind the authentication flow to the *Browser* binding type.
+
+Once you enable the <<_enabling_organization_,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:
+
+.Procedure
+. Duplicate the current flow bound to the *First broker login flow* bind type to avoid breaking the flow you are currently using
+. Click *Add sub-flow* and give it a name such as `Organization Member - Conditional`. Once added, change the *Requirement* to *Conditional*.
+. Click *Add condition* in the *Organization Member - Conditional* sub-flow and select *Condition - user configured*. Once added, change the *Requirement* to *Required*.
+. Click *Add step* in the *Organization Member - Conditional* sub-flow and select the *Organization Member Onboard* execution step. Once added, change the *Requirement* to *Required*.
+. Bind the authentication flow to the *First broker login* binding type.
+
+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.

docs/documentation/server_admin/topics/organizations/intro.adoc

@@ -0,0 +1,21 @@
+[role="_abstract"]
+When integrating with a third party like a customer or business partner, you might want to manage their identities
+separately from others and build a unified and secure experience throughout your business ecosystem when they interact
+with a realm.
+
+In a realm, an *organization* represents these third parties so that a realm or an organization administrator can manage
+the entire lifecycle of its members and how they authenticate and authorize to a realm, on a per-organization basis.
+
+The organization is the entry point to start using the IAM capabilities of {project_name} to also address Business-to-Business (B2B) use cases.
+It enables multi-tenancy within a realm so that users can have access to protected resources from a realm but with a more restricted
+and controlled context. The organization they belong to.
+
+{project_name} Organizations is a feature that enables support for organizations in {project_name}. For now, it provides
+some of the core capabilities needed to manage organizations such as:
+
+* Manage members
+* Onboard organization members using invitation links
+* Onboard organization members by federating their identities through identity brokering
+* Identity-first login and organization-specific steps when authenticating in the scope of an organization
+* Propagate organization-specific claims to applications through tokens for authorization purposes
+

docs/documentation/server_admin/topics/organizations/managing-attributes.adoc

@@ -0,0 +1,13 @@
+[id="managing-organization-attributes_{context}"]
+
+[[_managing_attributes_]]
+=  Managing attributes
+[role="_abstract"]
+An administrator can store additional metadata about an organization using attributes.
+An organization attribute is a key/value pair that can hold multiple string values.
+
+For that, click the *Attributes* tab and set any attribute you want by providing a key and a value.
+
+To provide multiple values for the same attribute, and key, just add another attribute with the same key but with a
+different value.
+

docs/documentation/server_admin/topics/organizations/managing-identity-providers.adoc

@@ -0,0 +1,42 @@
+[id="managing-organization-identity-providers_{context}"]
+
+[[_managing_identity_provider_]]
+=  Managing identity providers
+[role="_abstract"]
+An organization might have its own identity provider as the single source of truth for their identities. In this case,
+you want to configure the organization to authenticate users using the organization's identity provider, federate their
+identities, and finally add them as a member of the organization.
+
+An organization can have one or more identity providers associated with it so that they can authenticate their users from
+different sources and enforce different constraints on each of them.
+
+Before you can link an identity provider to an organization, you create an organization at the realm level from the *Identity Providers*
+section in the menu. You can link any of the built-in social and identity providers available in the realm to an organization.
+
+An identity provider can be linked to an organization from the *Identity providers* tab.
+
+.Procedure
+
+. Click *Link identity provider*.
+. Select an *Identity provider*
+. Click *Save*
++
+
+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:
+
+Identity provider::
+The identity provider you want to link to the organization. An identity provider can only be linked to a single organization.
+
+Domain::
+The domain from the organization that you want to link with the identity provider.
+
+Show on login page::
+If this identity provider should be shown in login pages when the user is authenticating in the scope of the organization.
+
+Redirect when email domain matches::
+If members should be automatically redirected to the identity provider when their email domain matches the domain set to the identity provider.
+
+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.

docs/documentation/server_admin/topics/organizations/managing-members.adoc

@@ -0,0 +1,117 @@
+[id="managing-organization-members_{context}"]
+
+[[_managing_members_]]
+=  Managing members
+[role="_abstract"]
+An organization member is basically a realm user but with a link to a single organization. They are logically separated
+from other users in a realm so that you know exactly which users belong to an organization.
+
+There are different ways to add, or onboard, a member to an organization:
+
+* Adding an existing realm user as a member
+* Through an identity provider associated with an organization
+* Sending an invitation to create a new account
+* Sending an invitation to an existing user to join an organization
+
+Once a member of an organization, that user's account can be managed just like any regular account in a realm by accessing the *Users* section
+in the menu.
+
+However, you can narrow the users to only those associated with an organization by accessing the *Members* tab
+when managing an organization. In this tab, you have a list of all the organization members and actions to add new members and to edit and remove
+existing ones.
+
+[[_managed_unmanaged_members_]]
+== 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*
+* *Unmanaged*
+
+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.
+
+== Adding an existing realm user as a member
+
+An existing realm user can join an organization by selecting that user from a list and adding the user to the organization.
+
+.Procedure
+
+. Click *Add member*.
+. Click *Add realm user*.
+. Select one or more users and click *Add* to add them 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.
+
+== Inviting users
+
+An administrator can email users to join an organization.
+
+.Procedure
+
+. Click *Add member*.
+. Click *Invite member*.
+. Provide an email address
+. Click *Send*
+
+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.
+Make sure to enable the *User registration* setting in the *Login* tab at the *Realm settings* to use this type of invitation.
+
+[[_onboard_member_identity_provider_]]
+== Onboarding members using an Identity Provider
+
+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, {project_name} 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 to
+*Show 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_provider_,Managing Identity Providers>>.
+
+== Removing a member
+
+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_unmanaged_members_,Managed and unmanaged members>>.

docs/documentation/server_admin/topics/organizations/managing-organization.adoc

@@ -0,0 +1,82 @@
+[id="managing-organization_{context}"]
+
+[[_enabling_organization_]]
+=  Enabling Organizations
+
+To use organizations, you enable the feature for the current realm.
+
+.Procedure
+
+. Click *Realm Settings* in the menu.
+
+. Toggle *Organizations* to *On*.
+
+Once the feature is enabled, you are able to manage organizations through the *Organizations* section available from the
+menu.
+
+=  Managing an organization
+[role="_abstract"]
+
+From the *Organizations* section, you can manage all the organizations in your realm.
+
+.Procedure
+
+. Click *Create Organization*.
+
+If organizations already exist, you see a list of organizations and options to search, edit, or delete an organization.
+
+An organization has the following settings:
+
+Name::
+A user-friendly name for the organization. The name is unique within a realm.
+
+Domains::
+A set of one or more domains that belongs to this organization. A domain cannot be shared by different organizations
+within a realm.
+
+Description::
+A free-text field to describe the organization.
+
+Once you create an organization, you can manage the additional settings that are described in the following sections:
+
+* <<_managing_attributes_,Manage attributes>>
+* <<_managing_members_,Manage members>>
+* <<_managing_identity_provider_,Manage identity providers>>
+
+== Understanding organization domains
+
+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, {project_name} 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.
+
+==  Disabling an organization
+
+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_unmanaged_members_,Managed and unmanaged members>> section.
+
+== Remove an organization
+
+To remove an organization, you can 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_unmanaged_members_,Managed and unmanaged members>>.

docs/documentation/server_admin/topics/organizations/mapping-organization-claims.adoc

@@ -0,0 +1,23 @@
+[id="mapping-organization-claims_{context}"]
+
+=  Mapping organization claims
+[role="_abstract"]
+When authenticating in the context of an organization, the access token is automatically updated with specific claims
+about the organization where the user is a member.
+
+To map organization-specific claims into tokens, a client needs to request the *organization* scope when sending
+authorization requests to the server.
+
+As a result, the token will contain a claim as follows:
+
+```json
+"organization": {
+  "acme": {}
+}
+```
+
+The organization claim can be used by clients (for example, from ID Tokens) and resource servers (for example, from access tokens)
+to authorize access to protected resources based on the organization where the user is a member.
+
+The organization scope is a built-in optional client scope at the realm.  Therefore, this scope is added to any client created
+in the realm, by default.