docs(keycloak): updates from review by keycloak dev (#10581)

Signed-off-by: prmellor <[email protected]>

documentation/modules/oauth/con-kafka-keycloak-authz-models.adoc

@@ -2,38 +2,24 @@
 = Kafka and Keycloak authorization models
 
 [role="_abstract"]
-Kafka and Keycloak Authorization Services use different authorization models.
-
-* Kafka's authorization model uses _resource types_ and _operations_ to describe ACLs for the _user_
-* The Keycloak Authorization Services model has four concepts for defining and granting permissions: 
-** _resources_ 
-** _authorization scopes_
-** _policies_
-** _permissions_
+Kafka and Keycloak use different authorization models.
 
 .Kafka authorization model
+Kafka's authorization model uses _resource types_ and _operations_ to describe ACLs for a user.
 When a Kafka client performs an action on a broker, the broker uses the configured `KeycloakAuthorizer` to check the client's permissions, based on the action and resource type.
 
 Each resource type has a set of available permissions for operations.
 For example, the `Topic` resource type has `Create` and `Write` permissions among others.
 
 Refer to the https://kafka.apache.org/documentation/#security_authz_primitives[Kafka authorization model] in the Kafka documentation for the full list of resources and permissions. 
 
-.Keycloak Authorization Services model
-
-The Keycloak Authorization Services model defines authorized actions. 
-
-Resources:: Resources are matched with permitted actions.
-A resource might be an individual topic, for example, or all topics with names starting with the same prefix.
-A resource definition is associated with a set of available authorization scopes, which represent a set of all actions available on the resource.
-Often, only a subset of these actions is actually permitted.
+.Keycloak authorization model
 
-Authorization scopes:: An authorization scope is a set of all the available actions on a specific resource definition.
-When you define a new resource, you add scopes from the set of all scopes.
+Keycloak's authorization services model has four concepts for defining and granting permissions: 
 
-Policies:: A policy is an authorization rule that uses criteria to match against a list of accounts.
-Policies can match:
-* _Service accounts_ based on client ID or roles
-* _User accounts_ based on username, groups, or roles.
+* Resources 
+* Scopes
+* Policies
+* Permissions
 
-Permissions:: A permission grants a subset of authorization scopes on a specific resource definition to a set of users.
+For information on these concepts, see the guide to {keycloak-authorization-services}.

documentation/modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc

@@ -17,6 +17,7 @@ However, you can also use different OAuth client ids (for example, `my-cluster-k
 ====
 
 The `kafka` client definition must have the *Authorization Enabled* option enabled in the Keycloak Admin Console.
+For information on enabling authorization services, see the guide to {keycloak-authorization-services}.
 
 All permissions exist within the scope of the `kafka` client. 
 If you have different Kafka clusters configured with different OAuth client IDs, they each need a separate set of permissions even though they're part of the same Keycloak realm.

documentation/modules/oauth/proc-oauth-authorization-keycloak-example.adoc

@@ -116,24 +116,24 @@ An affirmative policy means that at least one policy must be satisfied for a cli
 
 . In the Keycloak Admin Console, go to *Groups*, *Users*, *Roles* and *Clients* to view the realm configuration.
 +
-Groups:: `Groups` are used to create user groups and set user permissions. Groups are sets of users with a name assigned. They are used to compartmentalize users into geographical, organizational or departmental units.
-Groups can be linked to an LDAP identity provider. You can make a user a member of a group through a custom LDAP server admin user interface, for example, to grant permissions on Kafka resources.
+Groups:: `Groups` organize users and set permissions. 
+Groups can be linked to an LDAP identity provider and used to compartmentalize users, such as by region or department. 
+Users can be added to groups through a custom LDAP interface to manage permissions for Kafka resources.
+For more information on using KeyCloak's LDAP provider, see the the guide to {keycloak-admin-guide}.
 
-Users:: `Users` are used to create users. For this example, `alice` and `bob` are defined. `alice` is a member of the `ClusterManager` group and `bob` is a member of `ClusterManager-my-cluster` group.
-Users can be stored in an LDAP identity provider.
+Users:: `Users` define individual users. 
+In this example, `alice` (in the `ClusterManager` group) and `bob` (in `ClusterManager-my-cluster`) are created. 
+Users can also be stored in an LDAP identity provider.
 
-Roles:: `Roles` mark users or clients as having certain permissions.
-Roles are a concept analogous to groups. They are usually used to _tag_ users with organizational roles and have the requisite permissions.
-Roles cannot be stored in an LDAP identity provider.
-If LDAP is a requirement, you can use groups instead, and add Keycloak roles to the groups so that when users are assigned a group they also get a corresponding role.
+Roles:: `Roles` assign specific permissions to users or clients. 
+Roles function like tags to give users certain rights. 
+While roles cannot be stored in LDAP, you can add Keycloak roles to groups to combine both roles and permissions.
 
-Clients:: `Clients` can have specific configurations. For this example, `kafka`, `kafka-cli`, `team-a-client`, and `team-b-client` clients are configured.
+Clients:: `Clients` define configurations for Kafka interactions.
 +
-* The `kafka` client is used by Kafka brokers to perform the necessary OAuth 2.0 communication for access token validation.
-This client also contains the authorization services resource definitions, policies, and authorization scopes used to perform authorization on the Kafka brokers.
-The authorization configuration is defined in the `kafka` client from the *Authorization* tab, which becomes visible when *Authorization Enabled* is switched on from the *Settings* tab.
-* The `kafka-cli` client is a public client that is used by the Kafka command line tools when authenticating with username and password to obtain an access token or a refresh token.
-* The `team-a-client` and `team-b-client` clients are confidential clients representing services with partial access to certain Kafka topics.
+* The `kafka` client handles OAuth 2.0 token validation for brokers and contains authorization policies (which require authorization to be enabled).
+* The `kafka-cli` client is used by command line tools to obtain access or refresh tokens.
+* `team-a-client` and `team-b-client` represent services with partial access to specific Kafka topics.
 
 . In the Keycloak Admin Console, go to *Authorization* > *Permissions* to see the granted permissions that use the resources and policies defined for the realm.
 +

documentation/shared/attributes.adoc

@@ -57,6 +57,7 @@
 :keycloak-server-doc: link:https://www.keycloak.org/documentation.html[Keycloak documentation^]
 :keycloak-server-install-doc: link:https://www.keycloak.org/operator/installation[Installing the Keycloak Operator^]
 :keycloak-authorization-services: link:https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Authorization Services^]
+:keycloak-admin-guide: link:https://www.keycloak.org/docs/latest/authorization_services/index.html[Keycloak Server Administration^]
 :OAuthVersion: 0.15.0
 :oauth-demo-keycloak: link:https://github.com/strimzi/strimzi-kafka-oauth/tree/{OAuthVersion}/examples[Using Keycloak as the OAuth 2.0 authorization server^]
 :oauth-demo-hydra: link:https://github.com/strimzi/strimzi-kafka-oauth/tree/{OAuthVersion}/examples/docker#running-with-hydra-using-ssl-and-opaque-tokens[Using Hydra as the OAuth 2.0 authorization server^]