docs(acls): describes handling of special users (#11118)

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

documentation/assemblies/security/assembly-securing-kafka-clients.adoc

@@ -19,4 +19,5 @@ For more information on configuring a `KafkaUser` resource to access Kafka broke
 include::../../modules/security/con-securing-client-labels.adoc[leveloffset=+1]
 include::../../modules/security/con-securing-client-authentication.adoc[leveloffset=+1]
 include::../../modules/security/con-securing-client-authorization.adoc[leveloffset=+1]
+include::../../modules/security/con-securing-client-acls.adoc[leveloffset=+1]
 include::../../modules/security/con-configuring-client-quotas.adoc[leveloffset=+1]

documentation/modules/security/con-securing-client-acls.adoc

@@ -0,0 +1,49 @@
+// Module included in the following assemblies:
+//
+// assembly-securing-kafka-clients.adoc
+
+[id='con-securing-client-acls-{context}']
+= Defining ACL rules
+
+The `simple` authorization mechanism uses ACL rules to manage access to Kafka brokers.
+Enabling `simple` authorization for a Kafka cluster means access is denied unless explicit ACL rules are configured in the `KafkaUser` resource.
+ACL rules define access rights for users, which you specify using the `acls` property.
+
+.Example user with ACL rules configuration
+[source,yaml,subs="+attributes"]
+----
+apiVersion: {KafkaUserApiVersion}
+kind: KafkaUser
+metadata:
+  name: my-user
+  labels:
+    strimzi.io/cluster: my-cluster
+spec:
+  authentication:
+    type: tls
+  authorization:
+    type: simple
+    acls:
+      - resource: # <1>
+          type: topic
+          name: my-topic
+          patternType: literal
+        operations: # <2>
+          - Describe
+          - Read
+      - resource:
+          type: group
+          name: my-group
+          patternType: literal
+        operations:
+          - Read
+----
+<1> Defines the Kafka resource type to which the ACL rules apply, such as `topic` or `group`, the name of the resource, and how the name is matched by `patternType`.
+<2> Specifies the operations, such as `Describe`, `Read`, that the user is allowed to perform on the resource.
+
+The User Operator manages ACLs for standard Kafka users but cannot define rules for special usernames such as `User:ANONYMOUS` or `User:*`. 
+These users are ignored because their names are not valid Kubernetes resource names.  
+You can manually configure ACL rules for these usernames using tools like `kafka-acls.sh`.
+When these manual configurations are present in Kafka, the User Operator logs a message for information but does not delete them.
+
+For more information about the `AclRule` object and the properties used to configure ACLs, see the link:{BookURLConfiguring}#type-AclRule-reference[`AclRule` schema reference^].

documentation/modules/security/con-securing-client-authorization.adoc

@@ -33,18 +33,3 @@ You can disable it using the `STRIMZI_ACLS_ADMIN_API_SUPPORTED` environment vari
 If no authorization is specified, the User Operator does not provision any access rights for the user.
 Whether such a `KafkaUser` can still access resources depends on the authorizer being used.
 For example, for `simple` authorization, this is determined by the `allow.everyone.if.no.acl.found` configuration in the Kafka cluster.
-
-== ACL rules
-
-`simple` authorization uses ACL rules to manage access to Kafka brokers.
-
-ACL rules grant access rights to the user, which you specify in the `acls` property.
-
-For more information about the `AclRule` object, see the link:{BookURLConfiguring}#type-AclRule-reference[`AclRule` schema reference^].
-
-== Super user access to Kafka brokers
-
-If a user is added to a list of super users in a Kafka broker configuration,
-the user is allowed unlimited access to the cluster regardless of any authorization constraints defined in ACLs in `KafkaUser`.
-
-For more information on configuring super user access to brokers, see xref:con-securing-kafka-authorization-{context}[Kafka authorization].

documentation/modules/security/con-securing-kafka-authorization.adoc

@@ -26,7 +26,7 @@ image::kafka-authorization-config-options.png[options for kafka authorization co
 Super users can access all resources in your Kafka cluster regardless of any access restrictions,
 and are supported by all authorization mechanisms.
 
-To designate super users for a Kafka cluster, add a list of user principals to the `superUsers` property.
+To designate super users for a Kafka cluster, add a list of user principals to the `superUsers` property of the `Kafka` resource.
 If a user uses mTLS authentication, the username is the common name from the TLS certificate subject prefixed with `CN=`.
 If you are not using the User Operator and using your own certificates for mTLS, the username is the full certificate subject.