KEYCLOAK-16186 Initial rewording (#38)

* KEYCLOAK-16186 Initial rewording

* Post workding feedback

* post visual review changes

* more post feedback changes

* Update default-roles.adoc

Minor correction where you include my incorrect suggestion.

Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

server_admin/topics/groups.adoc

@@ -1,38 +1,50 @@
+
 == Groups
 
-Groups in {project_name} allow you to manage a common set of attributes and role mappings for a set of users.
-Users can be members of zero or more groups.
-Users inherit the attributes and role mappings assigned to each group.  To manage groups go to the `Groups` left menu
-item.
+Groups in {project_name} manage a common set of attributes and role mappings for each user. Users can be members of any number of groups and inherit the attributes and role mappings assigned to each group.
+
+To manage groups, click `Groups` in the left menu.
 
 .Groups
 image:{project_images}/groups.png[]
 
-Groups are hierarchical.
-A group can have many subgroups, but a group can only have one parent.
-Subgroups inherit the attributes and role mappings from the parent.
-This applies to the user as well.
-So, if you have a parent group and a child group and a user that only belongs to the child group, the user inherits the attributes and role mappings of both the parent and child.
-In this example, we have a top level `Sales` group and a child `North America` subgroup.  To add a group, click on the
-parent you want to add a new child to and click `New` button.  Select the `Groups` icon in the tree to make a top-level group.
-Entering in a group name in the `Create Group` screen and hitting `Save` will bring you to the individual group management page.
+Groups are hierarchical. A group can have multiple subgroups but a group can have only one parent. Subgroups inherit the attributes and role mappings from their parent. Users inherit the attributes and role mappings from their parent as well.
 
+If you have a parent group and a child group, and a user that belongs only to the child group, the user in the child group inherits the attributes and role mappings of both the parent group and the child group.
+
+The following example includes a top-level `Sales` group and a child `North America` subgroup.  
+
+To add a group:
+
+. Click the group.
+. Click `New`.
+. Select the `Groups` icon in the tree to make a top-level group.
+. Enter a group name in the `Create Group` screen.
+. Click `Save`. The group management page displays.
++
 .Group
 image:{project_images}/group.png[]
 
-The `Attributes` and `Role Mappings` tab work exactly as the tabs with similar names under a user.  Any attributes and role mappings
-you define will be inherited by the groups and users that are members of this group.
+Attributes and role mappings you define are inherited by the groups and users that are members of the group.
 
-To add a user to a group you need to go all the way back to the user detail page and click on the `Groups` tab there.
+To add a user to a group:
 
+. Click `Users` in the left menu.
+. Click the user that you want to perform a role mapping on. If the user is not displayed, click `View all users`.
+. Click `Groups`.
++
 .User Groups
 image:{project_images}/user-groups.png[]
++
+. Select a group from the `Available Groups` tree.
+. Click `Join`.
 
-Select a group from the `Available Groups` tree and hit the `join` button to add the user to a group.  Vice versa to remove a group.
-Here we've added the user _Jim_ to the _North America_ sales group.  If you go back to the detail page for that group and
-select the `Membership` tab, _Jim_ is now displayed there.
+To remove a group from a user:
+
+. Select the group from the `Group Membership` tree.
+. Click `Leave`.
+
+In this example, the user _jimlincoln_ is in the _North America_ group.  You can see _jimlincoln_ displayed under the `Members` tab for the group.
 
 .Group Membership
 image:{project_images}/group-membership.png[]
-
-

server_admin/topics/groups/default-groups.adoc

@@ -1,12 +1,12 @@
 
 === Default Groups
 
-Default groups allow you to automatically assign group membership whenever any new user is created or imported through
-<<_identity_broker, Identity Brokering>>.
-To specify default groups go to the `Groups` left menu item, and click the `Default Groups` tab.
+To automatically assign group membership to new users, that are created or imported through <<_identity_broker, Identity Brokering>>, you use default groups.
+
+To specify default groups:
+
+. Click `Groups` in the left menu.
+. Click the `Default Groups` tab.
 
 .Default Groups
 image:{project_images}/default-groups.png[]
-
-
-

server_admin/topics/groups/groups-vs-roles.adoc

@@ -2,12 +2,10 @@
 
 === Groups vs. Roles
 
-In the IT world the concepts of Group and Role are often blurred and interchangeable.
-In {project_name}, Groups are just a collection of users that you can apply roles and attributes to in one place.
-Roles define a type of user and applications assign permission and access control to roles.
+Groups and roles have some similarities and differences. In {project_name}, groups are a collection of users to apply roles and attributes. Roles define types of users and applications assign permissions and access control to roles.
 
-Aren't <<_composite-roles,Composite Roles>> also similar to Groups?
-Logically they provide the same exact functionality, but the difference is conceptual.
-Composite roles should be used to apply the permission model to your set of services and applications.
-Groups should focus on collections of users and their roles in your organization.
-Use groups to manage users.  Use composite roles to manage applications and services.
+<<_composite-roles,Composite Roles>> are similar to Groups as they provide the same functionality. The difference between them is conceptual.
+
+Composite roles apply the permission model to a set of services and applications. Use composite roles to manage applications and services.
+
+Groups focus on collections of users and their roles in an organization. Use groups to manage users.  

server_admin/topics/roles.adoc

@@ -1,9 +1,4 @@
 == Roles
+A role typically applies to one type of user. Typical roles in an organization include `Admin`, `user`, `manager`, and `employee`. An application can assign access and permissions to a role and then assign multiple users to that role so the users share the same access and permissions. For example, the Admin Console has roles that give permission to users to access parts of the Admin Console.
 
-Roles identify a type or category of user.  `Admin`, `user`, `manager`, and `employee` are all typical roles that may exist
-in an organization.
-Applications often assign access and permissions to specific roles rather than individual users as dealing
-with users can be too fine grained and hard to manage.  For example, the Admin Console has specific roles which give permission to users
-to access parts of the Admin Console UI and perform certain actions.  There is a global namespace for roles and each client also has its own
-dedicated namespace where roles can be defined.
-
+There is a global namespace for roles and each client also has its own dedicated namespace where roles can be defined. 

server_admin/topics/roles/client-roles.adoc

@@ -1,5 +1,3 @@
 === Client Roles
 
-Client roles are basically a namespace dedicated to a client. Each client gets its own namespace. Client roles are managed under the `Roles` tab under each individual client. You interact with this UI the same way you do for realm-level roles.
-
-
+Client roles are namespaces dedicated to clients. Each client gets its own namespace. Client roles are managed under the `Roles` tab for each client. You interact with this UI the same way you do for realm-level roles.

server_admin/topics/roles/composite.adoc

@@ -2,20 +2,22 @@
 
 === Composite Roles
 
-Any realm or client level role can be turned into a _composite role_.
-A _composite role_ is a role that has one or more additional roles associated with it.
-When a composite role is mapped to the user, the user also gains the roles associated with that composite.  This inheritance
-is recursive so any composite of composites also gets inherited.
+Any realm or client level role can be a _composite role_. A _composite role_ is a role that has one or more additional roles associated with it. When a composite role is mapped to a user, the user also gains the roles associated with that composite.  This inheritance is recursive so users also inherit any composite of composites. However, we recommend that composite roles are not overused.
 
-To turn a regular role into a composite role, go to the role detail page and flip the `Composite Role` switch on.
+To convert a role to a composite role:
+
+. Click `Roles` in the left menu.
+. Click the role to access the roles detail page.
+. Set `Composite Roles` to ON.
 
 .Composite Role
 image:{project_images}/composite-role.png[]
 
-Once you flip this switch the role selection UI will be displayed lower on the page and you'll be able to associate
-realm level and client level roles to the composite you are creating.  In this example, the `employee` realm-level
-role was associated with the `developer` composite role.  Any user with the `developer` role will now also inherit
-the `employee` role too.
+The role selection UI is displayed on the page and you can associate realm level and client level roles to the composite role you are creating.
 
-NOTE: When tokens and SAML assertions are created, any composite will also have its associated roles added to the claims and
-      assertions of the authentication response sent back to the client.
+In this example, the `employee` realm-level role is associated with the `developer` composite role.  Any user with the `developer` role also inherits the `employee` role.
+
+[NOTE]
+====
+When creating tokens and SAML assertions, any composite also has its associated roles added to the claims and assertions of the authentication response sent back to the client.
+====  

server_admin/topics/roles/realm-roles.adoc

@@ -1,17 +1,18 @@
 
 === Realm Roles
-
-Realm-level roles are a global namespace to define your roles. You can see the list of built-in and created roles by clicking the `Roles` left menu item.
+Realm-level roles are a namespace for defining your roles. To see the list of roles, click `Roles` in the left menu.
 
 image:{project_images}/roles.png[]
 
-To create a role, click *Add Role* on this page, enter in the name and description of the role, and click *Save*.
+To create a role:
+
+.Procedure
+. Click *Add Role*.
+. Enter a `Role Name`.
+. Enter a `Description`.
+. Click *Save*.
 
 .Add Role
 image:{project_images}/role.png[]
 
-The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings. The localized
-value is then configured within property files in your theme. See the link:{developerguide_link}[{developerguide_name}] for more information
-on localization.
-
-
+The `description` field can be localizable by specifying a substitution variable with `$\{var-name}` strings. The localized value is configured to your theme within the themes property files. See the vlink:{developerguide_link}[{developerguide_name}] for more details.

server_admin/topics/roles/role-scope-mappings.adoc

@@ -2,30 +2,16 @@
 
 === Role Scope Mappings
 
-When an OIDC access token or SAML assertion is created, all the user role mappings of the user are, by default, added as claims
-within the token or assertion.  Applications use this information to make access decisions on the resources controlled by that
-application.  In {project_name}, access tokens are digitally signed and can actually be re-used by the application
-to invoke on other remotely secured REST services.  This means that if an application gets compromised or there is a rogue
-client registered with the realm, attackers can get access tokens that have a broad range of permissions and your whole
-network is compromised.  This is where _role scope mappings_ becomes important.
+On creation of an OIDC access token or SAML assertion, the user role mappings become claims within the token or assertion.  Applications use these claims to make access decisions on the resources controlled by the application.  {project_name} digitally signs access tokens and applications re-use them to invoke remotely secured REST services.  However, these tokens have an associated risk. An attacker can obtain these tokens and use their permissions to compromise your networks. To prevent this situation, use _Role Scope Mappings_.
 
-_Role Scope Mappings_ is a way to limit the roles that get declared inside an access token.  When a client requests that a user
-be authenticated, the access token they receive back will only contain the role mappings you've explicitly specified
-for the client's scope.  This allows you to limit the permissions each individual access token has rather than giving the
-client access to all of the user's permissions.  By default, each client gets all the role mappings of the user.
-You can view this in the `Scope` tab of each client.
+_Role Scope Mappings_ limit the roles declared inside an access token.  When a client requests a user authentication, the access token they receive contains only the role mappings that are explicitly specified for the client's scope.  The result is that you limit the permissions of each individual access token instead of giving the client access to all the users permissions.  
+
+By default, each client gets all the role mappings of the user. You can view the role mappings in the `Scope` tab of each client.
 
 .Full Scope
 image:{project_images}/full-client-scope.png[]
 
-You can see from the picture that the effective roles of the scope are every declared role in the realm.
-To change this default behavior, you must explicitly turn off the `Full Scope Allowed` switch and declare the specific roles you want in each individual
-client.  Alternatively, you can also use <<_client_scopes, client scopes>>
-to define the same role scope mappings for a whole set of clients.
+By default, the effective roles of scopes are every declared role in the realm. To change this default behavior, set the `Full Scope Allowed` switch to ON and declare the specific roles you want in each client.  You can also use <<_client_scopes, client scopes>> to define the same role scope mappings for a set of clients.
 
 .Partial Scope
 image:{project_images}/client-scope.png[]
-
-
-
-

server_admin/topics/roles/user-role-mappings.adoc

@@ -1,18 +1,21 @@
 
 === User Role Mappings
 
-User role mappings can be assigned individually to each user through the `Role Mappings` tab for that single user.
+You can assign User role mappings to a user through the `Role Mappings` tab for that user.
+
+.Procedure
+. Click `Users` in the left menu.
+. Click the user that you want to perform a role mapping on. If the user is not displayed, click `View all users`.
+. Click the `Role Mappings` tab.
+. Click the role you want to assign to the user in the `Available Roles` box.
+. Click `Add selected`.
 
 .Role Mappings
 image:{project_images}/user-role-mappings.png[]
 
-In the above example, we are about to assign the composite role `developer` that was created in the <<_composite-roles, Composite Roles>>
-chapter.
+In the above example, we are assigning the composite role `developer` that was created in the <<_composite-roles, Composite Roles>> chapter to a user.
 
 .Effective Role Mappings
 image:{project_images}/effective-role-mappings.png[]
 
-Once the `developer` role is assigned, you see that the `employee` role that is associated with the `developer` composite shows up in the `Effective Roles`.
-`Effective Roles` are all roles that are explicitly assigned to the user as well as any roles that are inherited from composites.
-
-
+When the `developer` role is assigned, the `employee` role associated with the `developer` composite is displayed in the `Effective Roles` box. `Effective Roles` are the roles explicitly assigned to users and roles that are inherited from composites.

server_admin/topics/roles/user-role-mappings/default-roles.adoc

@@ -10,10 +10,4 @@ role cannot be removed because it serves as a container for both realm and clien
 .Default Roles
 image:{project_images}/default-roles.png[]
 
-As you can see from the screenshot, there are already a number of _default roles_ set up by default.
-
-
-
-
-
-
+This screenshot shows that some _default roles_ already exist.