KEYCLOAK-15771 Updates based on peer editing agreements on clients topics and making corrections to roles and groups chapter.

server_admin/topics/clients/con-client-scopes.adoc

@@ -1,4 +1,4 @@
-[id="client_scopes_{context}"]
+[id="con-client-scopes_{context}"]
 
 [[_client_scopes]]
 === Client Scopes
@@ -72,9 +72,10 @@ This setting is applicable only for OpenID Connect clients. Optional client scop
 ===== Example
 For this example, assume the client has *profile* and *email* linked as default client scopes, and *phone* and *address* linked as optional client scopes. The client uses the value of the scope parameter when sending a request to the OpenID Connect authorization endpoint.
 
-***
+[source,bash,subs=+attributes]
+----
 scope=openid phone
-***
+----
 
 The scope parameter contains the string, with the scope values divided by spaces. The value *openid* is the meta-value used for all OpenID Connect requests. The token will contain mappers and role scope mappings from the default client scopes *profile* and *email* as well as *phone*, an optional client scope requested by the scope parameter.
 

server_admin/topics/clients/con-protocol-mappers.adoc

@@ -29,7 +29,7 @@ image:{project_images}/mapper-config.png[]
 
 Details on each option can be viewed by hovering over its tooltip.
 
-Use OIDC mappers to control where the claim gets placed. You opt to include or exclude the claim from the _id_ and _access_ tokens by adjusting the *Add to ID token* and *Add to access token* switches.
+You can use most OIDC mappers to control where the claim gets placed. You opt to include or exclude the claim from the _id_ and _access_ tokens by adjusting the *Add to ID token* and *Add to access token* switches.
 
 include::proc-creating-mappers.adoc[]
 

server_admin/topics/clients/oidc/con-confidential-client-credentials.adoc

@@ -15,8 +15,6 @@ The *Client Authenticator* drop-down list specifies the type of credential to us
 
 This choice is the default setting. The secret is automatically generated for you and the clicking *Regenerate Secret*  recreates the secret if necessary.
 
-*Signed JWT*
-
 .Signed JWT
 image:{project_images}/client-credentials-jwt.png[]
 

server_admin/topics/clients/oidc/proc-using-a-service-account.adoc

@@ -1,3 +1,4 @@
+[id="proc-using-service-account_{context}"]
 
 [[_service_accounts]]
 ==== Using a Service Account
@@ -63,3 +64,9 @@ Pragma: no-cache
 ----
 
 The retrieved access token can be refreshed or logged out by an out-of-bound request.
+
+[role="_additional-resources"]
+.Additional resources
+For more details, see <<_client_credentials_grant,Client Credentials Grant>>.
+
+

server_admin/topics/clients/saml/proc-creating-saml-client.adoc

@@ -42,7 +42,7 @@ the name, set up a replacement string value. For example, a string value such as
 
 *Sign Documents*:: When set to ON, {project_name} signs the document using the realms private key.
 
-*Optimize REDIRECT signing key lookup*:: When set to ON, the SP messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. 
+*Optimize REDIRECT signing key lookup*:: When set to ON, the SAML protocol messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys. 
 +
 This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature. 
 +

server_admin/topics/roles-groups.adoc

@@ -1,8 +1,8 @@
 == Assigning permissions and access using roles and groups
 
-Roles and groups have a similar purpose, which is to give users access and permissions to use applications. Groups are a collection of users to which you apply roles and attributes. Roles define specific applications permissions and access control. Groups are an optional capability.
+Roles and groups have a similar purpose, which is to give users access and permissions to use applications. Groups are a collection of users to which you apply roles and attributes. Roles define specific applications permissions and access control.
 
-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.
+A role typically applies to one type of user. For example, an organization may include `admin`, `user`, `manager`, and `employee` roles. An application can assign access and permissions to a role and then assign multiple users to that role so the users have the same access and permissions. For example, the Admin Console has roles that give permission to users to access different parts of the Admin Console.
 
 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-groups/con-comparing-groups-roles.adoc

@@ -2,10 +2,8 @@
 
 ==== Groups compared to Roles
 [role="_abstract"]
-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.
+Groups and roles have some similarities and differences. In {project_name}, groups are a collection of users to which you apply roles and attributes. Roles define types of users and applications assign permissions and access control to roles.
 
-<<_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.
+<<_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-groups/con-default-roles.adoc

@@ -3,8 +3,7 @@
 [[_default_roles]]
 ==== Default Roles
 [role="_abstract"]
-Use default roles to automatically assign user role mappings when any user is newly created or imported through
-<<_identity_broker, Identity Brokering>>.
+Use default roles to automatically assign user role mappings when a user is created or imported through <<_identity_broker, Identity Brokering>>.
 To specify default roles, click *Roles* in the menu and click the *Default Roles* tab.
 
 .Default Roles

server_admin/topics/roles-groups/proc-assigning-role-mappings.adoc

@@ -14,7 +14,7 @@ You can assign User role mappings to a user through the *Role Mappings* tab for
 .Role Mappings
 image:{project_images}/user-role-mappings.png[]
 
-In the above example, we are assigning the composite role *developer* that was created in the <<_composite-roles, Composite Roles>> chapter to a user.
+In the preceding example, we are assigning the composite role *developer* to a user. That role was created in the <<_composite-roles, Composite Roles>> topic.
 
 .Effective Role Mappings
 image:{project_images}/effective-role-mappings.png[]

server_admin/topics/roles-groups/proc-converting-composite-roles.adoc

@@ -4,13 +4,13 @@
 
 === Composite Roles
 [role="_abstract"]
-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.
+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 gains the roles associated with the composite role.  This inheritance is recursive so users also inherit any composite of composites. However, we recommend that composite roles are not overused.
 
 To convert a role to a composite role:
 
 . Click *Roles* in the menu.
 . Click the role to access the roles detail page.
-. Set *Composite Roles* to ON.
+. Toggle *Composite Roles* to ON.
 
 .Composite Role
 image:{project_images}/composite-role.png[]

server_admin/topics/roles-groups/proc-creating-realm-roles.adoc

@@ -17,4 +17,4 @@ To create a role:
 .Add Role
 image:{project_images}/role.png[]
 
-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.
+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 link:{developerguide_link}[{developerguide_name}] for more details.

server_admin/topics/roles-groups/proc-managing-groups.adoc

@@ -20,7 +20,9 @@ To add a 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.
+. Click *Save*.
++
+The group management page is displayed.
 +
 .Group
 image:{project_images}/group.png[]

server_admin/topics/roles-groups/proc-specifying-default-groups.adoc

@@ -2,7 +2,7 @@
 
 ==== Default Groups
 [role="_abstract"]
-To automatically assign group membership to new users, that are created or imported through <<_identity_broker, Identity Brokering>>, you use default groups.
+To automatically assign group membership to any users who is created or who is imported through <<_identity_broker, Identity Brokering>>, you use default groups.
 
 To specify default groups:
 

server_admin/topics/sso-protocols/saml-vs-oidc.adoc

@@ -1,9 +1,9 @@
 
-=== OpenID Connect vs. SAML
+=== OpenID Connect compared to SAML
 
 Choosing between OpenID Connect and SAML is not just a matter of using a newer protocol (OIDC) instead of the older more mature protocol (SAML).
 
-In most cases {project_name} recommends using OIDC.
+For most purposes, {project_name} recommends using OIDC.
 
 SAML tends to be a bit more verbose than OIDC.