Update organizations documentation in the server admin guide

Closes #33199

Signed-off-by: Stefan Guilhen <sguilhen@redhat.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

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

@@ -2,10 +2,6 @@
 [[_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]

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

@@ -2,7 +2,7 @@
 
 =  Authenticating members
 [role="_abstract"]
-When you enable organizations for a realm, user authentication is changed. If the user is recognized to be 
+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:
@@ -30,21 +30,27 @@ 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:
+In addition to identifying the user once the username is provided, the identity-first login is also responsible for:
 
-* Match an email domain to an organization
+* Matching an email domain to an organization.
-* Decide if the authentication flow should continue or not if an account already exists for the username provided
+* Deciding 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
+* Deciding 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
+* Seamlessly authenticating 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.
 
+.Identity-first login page
+image:images/organizations-identity-first-login.png[alt="Identity-first login page"]
+
 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.
 
+.Identity-first when user does not exist
+image:images/organizations-identity-first-error.png[alt="Identity-first login error"]
+
 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
@@ -52,7 +58,7 @@ 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
+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_provider_,Managing identity providers>>.
@@ -81,6 +87,9 @@ user using whatever credentials you support in your realm. Once added, change th
 * execution step. Once added, change the *Requirement* to *Alternative*.
 . Bind the authentication flow to the *Browser* binding type.
 
+.Organizations browser flow
+image:images/organizations-browser-flow.png[alt="Organizations browser flow"]
+
 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.
@@ -94,5 +103,9 @@ Change the *first broker login* flow by following these steps:
 . 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.
 
+.Organizations first broker flow
+image:images/organizations-first-broker-flow.png[alt="Organizations first broker flow"]
+
+
 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/managing-attributes.adoc

@@ -3,11 +3,13 @@
 [[_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.
+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
+To provide multiple values for the same attribute, and key, just add another attribute with the same key but with a different value.
-different value.
+
+.Managing organization attributes
+image:images/organizations-manage-attributes.png[alt="Managing organization attributes"]
 

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

@@ -3,6 +3,7 @@
 [[_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.
@@ -13,16 +14,22 @@ 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.
+== Linking an identity provider to an organization
+
+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.
+
+.Organization identity providers
+image:images/organizations-identity-providers.png[alt="Organization identity providers"]
 
 .Procedure
 
-. Click *Link identity provider*.
+. Click *Link identity provider*
 . Select an *Identity provider*
+. Set the appropriate settings
 . Click *Save*
-+
 
-If identity providers already exist, you see a list of them and options to search, edit, or unlink from the organization.
+.Linking identity provider
+image:images/organizations-link-identity-provider.png[alt="Linking identity provider"]
 
 An identity provider has the following settings:
 
@@ -32,11 +39,44 @@ The identity provider you want to link to the organization. An identity provider
 Domain::
 The domain from the organization that you want to link with the identity provider.
 
-Show on login page::
+Hide on login page::
-If this identity provider should be shown in login pages when the user is authenticating in the scope of the organization.
+If this identity provider should be hidden 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.
+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
-However, the options herein described are only available when managing the identity provider in the scope of an organization.
+ *Hide on login page* option that is present here for convenience.
+
+== Editing a linked identity provider
+
+You can edit any of the organization-related settings of a linked identity provider at any time. 
+.Procedure
+
+. In the menu, click *Organizations* and go to the *Identity providers* tab.
+. Locate the *identity provider* in the list.
++
+You can use the search option for this step.
+. Click the action button (three dots) at the end of the line.
+. Click *Edit*.
+. Make the necessary changes.
+. Click *Save*.
+
+.Editing linked identity provider
+image:images/organizations-edit-identity-provider.png[alt="Editing linked identity provider"]
+
+== Unlinking an identity provider from an organization
+
+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.
+
+.Procedure
+
+. In the menu, click *Organizations* and go to the *Identity providers* tab.
+. Locate the *identity provider* in the list.
++
+You can use the search capabilities for this step.
+. Click the action button (three dots) at the end of the line.
+. Click *Unlink provider*.
+
+.Unlinking identity provider
+image:images/organizations-unlink-identity-provider.png[alt="Unlinking identity provider"]

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

@@ -3,6 +3,7 @@
 [[_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.
 
@@ -13,12 +14,12 @@ There are different ways to add, or onboard, a member to 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
+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.
-in the menu.
 
-However, you can narrow the users to only those associated with an organization by accessing the *Members* tab
+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.
-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.
+.Managing organization members
+image:images/organizations-manage-members.png[alt="Managing organization members"]
 
 [[_managed_unmanaged_members_]]
 == Managed and unmanaged members
@@ -52,6 +53,9 @@ An existing realm user can join an organization by selecting that user from a li
 . Click *Add realm user*.
 . Select one or more users and click *Add* to add them to the organization.
 
+.Adding a realm user
+image:images/organizations-add-realm-user.png[alt="Adding a realm user"]
+
 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.
 
@@ -66,6 +70,9 @@ An administrator can email users to join an organization.
 . Provide an email address
 . Click *Send*
 
+.Inviting members
+image:images/organizations-invite-member.png[alt="Inviting members"]
+
 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.
 
@@ -99,8 +106,8 @@ the email domain matches the organization, and an identity provider is associate
 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
+On the other hand, if *Redirect when email domain matches* is not enabled, but the identity provider is configured not to
-*Show on login page*, the user can select the identity provider and then be redirected to the identity provider to continue
+*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_provider_,Managing Identity Providers>>.

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

@@ -1,9 +1,9 @@
 [id="managing-organization_{context}"]
 
 [[_enabling_organization_]]
-=  Enabling Organizations
+= Enabling organizations in {project_name}
 
-To use organizations, you enable the feature for the current realm.
+To use organizations, you have to enable the feature for the current realm.
 
 .Procedure
 
@@ -11,19 +11,27 @@ To use organizations, you enable the feature for the current realm.
 
 . Toggle *Organizations* to *On*.
 
-Once the feature is enabled, you are able to manage organizations through the *Organizations* section available from the
+.Enabling Organizations
-menu.
+image:images/organizations-enabling-orgs.png[alt="Enabling Organizations"]
 
-=  Managing an organization
+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.
 
+.Managing organizations
+image:images/organizations-management-screen.png[alt="Managing organizations"]
+
+== Creating an organization
+
 .Procedure
 
 . Click *Create Organization*.
 
-If organizations already exist, you see a list of organizations and options to search, edit, or delete an organization.
+.Creating organization
+image:images/organizations-create-org.png[alt="Creating organization"]
 
 An organization has the following settings:
 
@@ -31,12 +39,11 @@ Name::
 A user-friendly name for the organization. The name is unique within a realm.
 
 Alias::
-An alias for this organization, used to reference the organization internally. The alias is unique within a realm.
+
-If not set, the value is the same as the organization name. The alias cannot change afterwards.
+An alias for this organization, used to reference the organization internally. The alias is unique within a realm and must be URL-friendly, so characters not usually allowed in URLs will not be allowed in the alias. If not set, {project_name} will attempt to use the name as the alias. If the name is not URL-friendly, you will get an error and will be asked to specify an alias. Once defined, the alias cannot be changed afterwards.
 
 Domains::
-A set of one or more domains that belongs to this organization. A domain cannot be shared by different organizations
+A set of one or more domains that belongs to this organization. A domain cannot be shared by different organizations within a realm.
-within a realm.
 
 Description::
 A free-text field to describe the organization.
@@ -52,35 +59,33 @@ Once you create an organization, you can manage the additional settings that are
 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
+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.
-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
+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.
-identity providers associated with an organization and you want to force a specific email domain for their email addresses.
 
-==  Disabling an organization
+== 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
+.Disabling organization
-cannot authenticate to the realm, including authenticating through the identity providers associated with the
+image:images/organizations-disable-org.png[alt="Disabling organization"]
-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
+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.
-tokens will not hold metadata about their relationship with an organization that is 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
+== Deleting an organization
 
-To remove an organization, you can click the *Delete* action for the corresponding organization in the listing page or
+To delete an organization, click the *Delete* action for the corresponding organization in the listing page or when editing an organization.
-when editing an organization.
+
+.Deleting organization
+image:images/organizations-delete-org.png[alt="Deleting 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
+Unmanaged users and identity providers remain in the realm, but they are no longer linked to the organization.
-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

@@ -3,22 +3,30 @@
 =  Mapping organization claims
 [role="_abstract"]
 To map organization-specific claims into tokens, a client needs to request the *organization* scope when sending
-authorization requests to the server. When authenticating in the context of an organization, clients can request the `organization` scope to map to tokens information
+authorization requests to the server. When authenticating in the context of an organization, clients can request the `organization` scope to map information
-about the organizations the user is a member.
+about the organizations where the user is a member.
 
 As a result, the token will contain a claim as follows:
 
 ```json
 "organization": {
-  "acme": {}
+  "testcorp": {
+    "attr1": [
+      "value1"
+    ]
+  }
 }
 ```
 
 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
+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. It also defines the `Organization Membership` mapper that controls how the organization membership information is mapped to the tokens.
-in the realm, by default.
+
+By default, the organization attributes are not included in the organization claim. To include the attributes in the claim, edit the mapper and enable *Add organization attributes*.
+
+.Including attributes in the organization claim
+image:images/organizations-add-org-attrs-in-claim.png[alt="Including attributes in the organization claim"]
 
 The `organization` scope is requested using different formats: