docs(refactor): updates to the oauth doc following review (strimzi#10143

)

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

documentation/assemblies/oauth/assembly-managing-policies-permissions-keycloak.adoc

@@ -1,23 +1,15 @@
-ifdef::context[:parent-context: {context}]
+// This assembly is included in the following assemblies:
+//
+// assembly-oauth-security.adoc
 
-[id="assembly-managing-policies-permissions-keycloak_{context}"]
-= Managing policies and permissions in Keycloak Authorization Services
-
-:context: authz-model
+[id="assembly-managing-policies-permissions-keycloak-{context}"]
+= Setting up permissions in Keycloak
 
 [role="_abstract"]
-This section describes the authorization models used by Keycloak Authorization Services and Kafka, and defines the important concepts in each model.
-
-To grant permissions to access Kafka, you can map Keycloak Authorization Services objects to Kafka resources by creating an _OAuth client specification_ in Keycloak.
-Kafka permissions are granted to user accounts or service accounts using Keycloak Authorization Services rules.
-
-xref:ref-example-permissions-for-kafka-operations_{context}[Examples] are shown of the different user permissions required for common Kafka operations, such as creating and listing topics.
+When using Keycloak as the OAuth 2.0 authorization server, Kafka permissions are granted to user accounts or service accounts using authorization permissions.
+To grant permissions to access Kafka, create an _OAuth client specification_ in Keycloak that maps the authorization models of Keycloak Authorization Services and Kafka.
 
 include::../../modules/oauth/con-kafka-keycloak-authz-models.adoc[leveloffset=+1]
-
 include::../../modules/oauth/con-mapping-keycloak-authz-services-to-kafka-model.adoc[leveloffset=+1]
-
 include::../../modules/oauth/ref-example-permissions-for-kafka-operations.adoc[leveloffset=+1]
-
-ifdef::parent-context[:context: {parent-context}]
-ifndef::parent-context[:!context:]
+include::../../modules/oauth/proc-oauth-authorization-keycloak-example.adoc[leveloffset=+1]

documentation/assemblies/oauth/assembly-oauth-authentication.adoc

@@ -1,34 +1,23 @@
 // This assembly is included in the following assemblies:
 //
-// assembly-deployment-configuration.adoc
+// assembly-oauth-security.adoc
 
 [id='assembly-oauth-authentication_{context}']
 = Using OAuth 2.0 token-based authentication
 
 [role="_abstract"]
-Strimzi supports the use of link:https://oauth.net/2/[OAuth 2.0 authentication^] using the _OAUTHBEARER_ and _PLAIN_ mechanisms.
-Using OAuth 2.0 authentication, application clients can access resources on application servers (called _resource servers_) without exposing account credentials.
-
-The application client passes an access token as a means of authenticating, which application servers can also use to determine the level of access to grant.
-The authorization server handles the granting of access and inquiries about access.
-
-In the context of Strimzi:
-
-* Kafka brokers act as OAuth 2.0 resource servers
-* Kafka clients act as OAuth 2.0 application clients
-
+Strimzi supports the use of link:https://oauth.net/2/[OAuth 2.0^] for token-based authentication.
+An OAuth 2.0 authorization server handles the granting of access and inquiries about access.
 Kafka clients authenticate to Kafka brokers.
-The brokers and clients communicate with the OAuth 2.0 authorization server, as necessary, to obtain or validate access tokens.
+Brokers and clients communicate with the authorization server, as necessary, to obtain or validate access tokens.
 
-For a deployment of Strimzi, OAuth 2.0 integration provides:
+For a deployment of Strimzi, OAuth 2.0 integration provides the following support:
 
-* Server-side OAuth 2.0 support for Kafka brokers
-* Client-side OAuth 2.0 support for Kafka MirrorMaker, Kafka Connect, and the Kafka Bridge
+* Server-side OAuth 2.0 authentication for Kafka brokers
+* Client-side OAuth 2.0 authentication for Kafka MirrorMaker, Kafka Connect, and the Kafka Bridge
 
-include::../../modules/oauth/con-oauth-authentication-flow.adoc[leveloffset=+1]
 include::../../modules/oauth/con-oauth-authentication-broker.adoc[leveloffset=+1]
-include::../../modules/oauth/con-oauth-reauthentication.adoc[leveloffset=+1]
 include::../../modules/oauth/con-oauth-authentication-client.adoc[leveloffset=+1]
 include::../../modules/oauth/con-oauth-authentication-client-options.adoc[leveloffset=+1]
-include::../../modules/oauth/con-oauth-config.adoc[leveloffset=+1]
-include::../../modules/oauth/con-oauth-server-examples.adoc[leveloffset=+1]
+include::../../modules/oauth/con-oauth-reauthentication.adoc[leveloffset=+1]
+include::../../modules/oauth/con-oauth-config.adoc[leveloffset=+1]

documentation/assemblies/oauth/assembly-oauth-authorization.adoc

@@ -1,12 +1,21 @@
 // This assembly is included in the following assemblies:
 //
-// assembly-deployment-configuration.adoc
+// assembly-oauth-security.adoc
 
 [id='assembly-oauth-authorization_{context}']
 = Using OAuth 2.0 token-based authorization
 
-include::../../modules/oauth/con-oauth-authorization-intro.adoc[leveloffset=+1]
-include::../../modules/oauth/con-oauth-authorization-mechanism.adoc[leveloffset=+1]
+[role="_abstract"]
+Strimzi supports the use of OAuth 2.0 token-based authorization through {keycloak-authorization-services},
+which lets you manage security policies and permissions centrally.
+
+Security policies and permissions defined in Keycloak grant access to Kafka resources.
+Users and clients are matched against policies that permit access to perform specific actions on Kafka brokers.
+
+Kafka allows all users full access to brokers by default, but also provides the `AclAuthorizer` and `StandardAuthorizer` plugins to configure authorization based on Access Control Lists (ACLs).
+The ACL rules managed by these plugins are used to grant or deny access to resources based on _username_, and these rules are stored within the Kafka cluster itself.
+
+However, OAuth 2.0 token-based authorization with Keycloak offers far greater flexibility on how you wish to implement access control to Kafka brokers.
+In addition, you can configure your Kafka brokers to use OAuth 2.0 authorization and ACLs.
+
 include::../../modules/oauth/proc-oauth-authorization-broker-config.adoc[leveloffset=+1]
-include::assembly-managing-policies-permissions-keycloak.adoc[leveloffset=+1]
-include::../../modules/oauth/proc-oauth-authorization-keycloak-example.adoc[leveloffset=+1]

documentation/assemblies/security/assembly-oauth-security.adoc → documentation/assemblies/oauth/assembly-oauth-security.adoc

@@ -8,8 +8,22 @@ Kafka brokers and clients both need to be configured to use OAuth 2.0.
 OAuth 2.0 enables standardized token-based authentication and authorization between applications, using a central authorization server to issue tokens that grant limited access to resources.
 You can define specific scopes for fine-grained access control.
 Scopes correspond to different levels of access to Kafka topics or operations within the cluster.  
+
 OAuth 2.0 also supports single sign-on and integration with identity providers. 
 
-//oauth options
+ifdef::Section[]
+For more information on using OAUth 2.0, see the link:https://github.com/strimzi/strimzi-kafka-oauth[Strimzi OAuth 2.0 for Apache Kafka project^].
+endif::Section[]
+
+//setting up oauth server
+include::../../modules/oauth/proc-oauth-server-config.adoc[leveloffset=+1]
+
+//oauth authentication
 include::../oauth/assembly-oauth-authentication.adoc[leveloffset=+1]
-include::../oauth/assembly-oauth-authorization.adoc[leveloffset=+1]
+
+//oauth authorization
+include::../oauth/assembly-oauth-authorization.adoc[leveloffset=+1]
+
+//keycloak authorization
+include::../oauth/assembly-managing-policies-permissions-keycloak.adoc[leveloffset=+1]
+

documentation/deploying/deploying.adoc

@@ -37,7 +37,7 @@ include::assemblies/deploying/assembly-deploy-client-access.adoc[leveloffset=+1]
 //Securing the deployment
 include::assemblies/security/assembly-securing-access.adoc[leveloffset=+1]
 //using OAuth
-include::assemblies/security/assembly-oauth-security.adoc[leveloffset=+1]
+include::assemblies/oauth/assembly-oauth-security.adoc[leveloffset=+1]
 //managing tls certificates
 include::assemblies/security/assembly-security.adoc[leveloffset=+1]
 //security context for all pods

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

@@ -1,61 +1,29 @@
 [id="con-kafka-keycloak-authz-models_{context}"]
-= Kafka and Keycloak authorization models overview
+= Kafka and Keycloak authorization models
 
 [role="_abstract"]
-
 Kafka and Keycloak Authorization Services use different authorization models.
 
-[discrete]
-== Kafka authorization model
+* 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's authorization model uses _resource types_. 
+.Kafka authorization model
 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.
 
-Kafka uses five resource types to control access: `Topic`, `Group`, `Cluster`, `TransactionalId`, and `DelegationToken`.
-Each resource type has a set of available permissions.
-
-*Topic*
-
-* `Create`
-* `Write`
-* `Read`
-* `Delete`
-* `Describe`
-* `DescribeConfigs`
-* `Alter`
-* `AlterConfigs`
-
-*Group*
-
-* `Read`
-* `Describe`
-* `Delete`
-
-*Cluster*
+Each resource type has a set of available permissions for operations.
+For example, the `Topic` resource type has `Create` and `Write` permissions among others.
 
-*  `Create`
-*  `Describe`
-*  `Alter`
-*  `DescribeConfigs`
-*  `AlterConfigs`
-*  `IdempotentWrite`
-*  `ClusterAction`
+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. 
 
-*TransactionalId*
+.Keycloak Authorization Services model
 
-*  `Describe`
-*  `Write`
+The Keycloak Authorization Services model defines authorized actions. 
 
-*DelegationToken*
-
-* `Describe`
-
-[discrete]
-== Keycloak Authorization Services model
-
-The Keycloak Authorization Services model has four concepts for defining and granting permissions: _resources_, _authorization scopes_, _policies_, and _permissions_.
-
-Resources:: A resource is a set of resource definitions that are used to match resources with permitted 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.
@@ -69,7 +37,3 @@ Policies can match:
 * _User accounts_ based on username, groups, or roles.
 
 Permissions:: A permission grants a subset of authorization scopes on a specific resource definition to a set of users.
-
-[role="_additional-resources"]
-.Additional resources
-* link:https://kafka.apache.org/documentation/#security_authz_primitives[Kafka authorization model]

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

@@ -1,13 +1,12 @@
 [id="con-mapping-keycloak-authz-services-to-kafka-model_{context}"]
-= Map Keycloak Authorization Services to the Kafka authorization model
+= Mapping authorization models
 
 [role="_abstract"]
+The Kafka authorization model is used as a basis for defining the Keycloak roles and resources that control access to Kafka.
 
-The Kafka authorization model is used as a basis for defining the Keycloak roles and resources that will control access to Kafka.
-
-To grant Kafka permissions to user accounts or service accounts, you first create an _OAuth client specification_ in Keycloak for the Kafka broker.
+To grant Kafka permissions to user accounts or service accounts, you first create an _OAuth client specification_ in Keycloak for the Kafka cluster.
 You then specify Keycloak Authorization Services rules on the client.
-Typically, the client id of the OAuth client that represents the broker is `kafka`.
+Typically, the client ID of the OAuth client that represents the Kafka cluster is `kafka`.
 The xref:proc-oauth-authorization-keycloak-example_str[example configuration files] provided with Strimzi use `kafka` as the OAuth client id.
 
 [NOTE]
@@ -19,40 +18,43 @@ 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.
 
-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.
+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.
 
 When the Kafka client uses OAUTHBEARER authentication, the Keycloak authorizer (`KeycloakAuthorizer`) uses the access token of the current session to retrieve a list of grants from the Keycloak server.
-To retrieve the grants, the authorizer evaluates the Keycloak Authorization Services policies and permissions.
+To grant permissions, the authorizer evaluates the grants list (received and cached) from Keycloak Authorization Services based on the access token owner's policies and permissions.
 
-.Authorization scopes for Kafka permissions
+.Uploading authorization scopes for Kafka permissions
 
 An initial Keycloak configuration usually involves uploading authorization scopes to create a list of all possible actions that can be performed on each Kafka resource type.
 This step is performed once only, before defining any permissions.
 You can add authorization scopes manually instead of uploading them.
 
-Authorization scopes must contain all the possible Kafka permissions regardless of the resource type:
+Authorization scopes should contain the following Kafka permissions regardless of the resource type:
 
 * `Create`
 * `Write`
 * `Read`
 * `Delete`
 * `Describe`
 * `Alter`
-* `DescribeConfig`
-* `AlterConfig`
+* `DescribeConfigs`
+* `AlterConfigs`
 * `ClusterAction`
 * `IdempotentWrite`
 
-[NOTE]
-====
 If you're certain you won't need a permission (for example, `IdempotentWrite`), you can omit it from the list of authorization scopes.
 However, that permission won't be available to target on Kafka resources.
+
+[NOTE]
+====
+The `All` permission is not supported.
 ====
 
 .Resource patterns for permissions checks
 
 Resource patterns are used for pattern matching against the targeted resources when performing permission checks.
-The general pattern format is `__RESOURCE-TYPE:PATTERN-NAME__`.
+The general pattern format is `<resource_type>:<pattern_name>`.
 
 The resource types mirror the Kafka authorization model.
 The pattern allows for two matching options:
@@ -69,7 +71,7 @@ Group:orders-*
 Cluster:*
 ----
 
-Additionally, the general pattern format can be prefixed by `kafka-cluster:__CLUSTER-NAME__` followed by a comma, where _CLUSTER-NAME_ refers to the `metadata.name` in the Kafka custom resource.
+Additionally, the general pattern format can be prefixed by `kafka-cluster:<cluster_name>` followed by a comma, where `<cluster_name>` refers to the `metadata.name` in the Kafka custom resource.
 
 .Example patterns for resources with cluster prefix
 [source]
@@ -93,7 +95,6 @@ Targeting can refer to:
 * Specific user or service accounts
 * Realm roles or client roles
 * User groups
-* JavaScript rules to match a client IP address
 
 A policy is given a unique name and can be reused to target multiple permissions to multiple resources.
 
@@ -103,8 +104,3 @@ Use fine-grained permissions to pull together the policies, resources, and autho
 
 The name of each permission should clearly define which permissions it grants to which users.
 For example, `Dev Team B can read from topics starting with x`.
-
-[role="_additional-resources"]
-.Additional resources
-
-* For more information about how to configure permissions through Keycloak Authorization Services, see xref:proc-oauth-authorization-keycloak-example_str[].