Fixes to examples/README-authz.md

Signed-off-by: Marko Strukelj <marko.strukelj@gmail.com>

Author: mstruk

examples/README-authz.md

@@ -1,12 +1,13 @@
-## Token based authorization with Keycloak Authorization Services
+## Token Based Authorization with Keycloak Authorization Services
 
 Once the Kafka Broker has obtained an access token by using Strimzi Kafka OAuth for authentication, it is possible to use centrally managed authorization rules to enforce access restrictions onto Kafka Clients.
 For this Strimzi Kafka OAuth supports the use of Keycloak Authorization Services.
 
 A custom authorizer has to be configured on the Kafka Broker to take advantage of Authorization Services REST endpoints available on Keycloak, which provide a list of granted permissions on resources for authenticated users.
 The list is fetched once, and enforced locally on the Kafka Broker for each user session in order to provide fast authorization decisions.
 
-## Authorization example
+
+## Building the Example Project
 
 Before using the example, we first need to build the project, and prepare resources.
 
@@ -21,22 +22,30 @@ Now build the project, and prepare resources:
 
 We are now ready to start up the containers and see Keycloak Authorization Services in action.
 
+
+## Starting Up the Containers
+
 First make sure any existing containers with the same name are removed, otherwise we might use previous configurations:
 
     docker rm keycloak kafka zookeeper
 
 Let's start up all the containers with authorization configured, and we'll then perform any manual step, and explain how everything works.
 
-    docker-compose -f compose.yml -f keycloak/compose.yml -f keycloak-import/compose.yml -f kafka-oauth-strimzi/compose-authz.yml up --build
+    docker-compose -f compose.yml -f keycloak/compose.yml -f keycloak-import/compose.yml \
+      -f kafka-oauth-strimzi/compose-authz.yml up --build
 
 When everything starts up without errors we should have one instance of `keycloak` listening on localhost:8080.
-You can login to the admin console by opening `http://localhost:8080/auth/admin` and using `admin` as both username, and a password.
 
-In upper left corner under Keycloak icon you should see `Master` selected as a current realm.
+
+## Using Keycloak Admin Console to Configure Authorization
+ 
+You can login to the Admin Console by opening `http://localhost:8080/auth/admin` and using `admin` as both username, and a password.
+
+In the upper left corner under Keycloak icon you should see `Master` selected as a current realm.
 Moving the mouse pointer over it should reveal two additional realms - `Demo` and `Kafka-authz`.
 
 For this example we are interested in the `kafka-authz` realm.
-Selecting it will open the `Realm Settings` for `kafka-authz` realm.
+Selecting it will open the `Realm Settings` for the `kafka-authz` realm.
 Next to `Realm Settings` there are other sections we are interested in - `Groups`, `Roles`, `Clients` and `Users`.
 
 Under `Groups` we can see several groups that can be used to mark users as having some permissions.
@@ -61,15 +70,18 @@ Clients `team-a-client`, and `team-b-client` are confidential clients representi
 The authorization configuration is defined in `kafka` client under `Authorization` tab.
 This tab becomes visible when `Authorization Enabled` is turned on under `Settings` tab.
 
-If we take a look under `Resources` sub-tab we'll see the list of resource definitions.
+
+## Authorization Services - Resources, Authorization Scopes, Policies and Permissions
+
+If we take a look under `Resources` sub-tab of `Authorization` tab, we'll see the list of resource definitions.
 These are resource specifiers - patterns in a specific format, that are used to target policies to specific resources.
 The format is quite simple. For example:
 
-    kafka-cluster:cluster-1,Topic:a_*  ... targets only topics in kafka cluster 'cluster-1' with names starting with 'a_'
+- `kafka-cluster:cluster-1,Topic:a_*`  ... targets only topics in kafka cluster 'cluster-1' with names starting with 'a_'
 
 If `kafka-cluster:XXX` segment is not present, the specifier targets any cluster.
 
-    Group:x_* ... targets all consumer groups on any cluster with names starting with 'x_'
+- `Group:x_*` ... targets all consumer groups on any cluster with names starting with 'x_'
 
 The possible resource types mirror the Kafka authorization model (Topic, Group, Cluster).
 
@@ -102,6 +114,7 @@ Let's click on `Dev Team A` policy. We see that it matches all users that have a
 Similarly, the `Dev Team B ...` permissions perform matching using `Dev Team B` policy which also uses realm role to match allowed users - in this case those with realm role `Dev Team B`.
 The `Dev Team B ...` permissions grant users `Describe` and `Read` on `Topic:x_*`, and `Group:x_*` resources, effectively giving matching users and clients the ability to read from topics, and update the consumed offsets for topics and consumer groups that have names starting with 'x_'. 
 
+## Targeting Permissions - Clients and Roles vs. Users and Groups
 
 In Keycloak, confidential clients with 'service accounts' enabled can authenticate to the server in their own name using a clientId and a secret.
 This is convenient for microservices which typically act in their own name, and not as agents of a particular user (like a web site would, for example).
@@ -114,6 +127,9 @@ Performing cluster management is usually done interactively - in person - using
 It makes sense to require the user to log-in, before using the resulting access token to authenticate to Kafka Broker.
 In this case the access token represents the specific user, rather than the client application.
 
+
+## Authorization in Action Using CLI Clients
+
 Before continuing, there is one setting we need to check.
 Due to [a little bug in Keycloak](https://issues.redhat.com/browse/KEYCLOAK-12640) the realm is at this point misconfigured, and we have to fix the configuration manually.
 Under `Clients` / `kafka` / `Authorization` / `Settings` make sure the `Decision Strategy` is set to `Affirmative`, and NOT to `Unanimous`. Click `Save` after fixing it.
@@ -149,10 +165,14 @@ Make sure the necessary classes are on the classpath:
 
     export CLASSPATH=/opt/kafka/libs/strimzi/*:$CLASSPATH
 
-Now let's try produce some messages to topic 'my-topic':
+
+### Producing Messages
+
+Let's try produce some messages to topic 'my-topic':
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic my-topic --producer.config=$HOME/team-a-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic my-topic \
+  --producer.config=$HOME/team-a-client.properties
 First message
 ```
 
@@ -164,46 +184,62 @@ Topic named `my-topic` does not fall in either of these two.
 Use CTRL-C to exit the CLI application, and let's try to write to topic `a_messages`.
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic a_messages --producer.config ~/team-a-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic a_messages \
+  --producer.config ~/team-a-client.properties
 First message
 Second message
 ```
 
 We can see some warnings but looking at Kafka container log there is DEBUG level output saying 'Authorization GRANTED'.
 
 Use CTRL-C to exit the CLI application.
- 
+
+
+### Consuming Messages
+
 Let's now try to consume the messages we have produced.
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic a_messages --from-beginning --consumer.config ~/team-a-client.properties
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic a_messages \
+      --from-beginning --consumer.config ~/team-a-client.properties
 
 This gives us an error like: 'Not authorized to access group: console-consumer-55841'.
 
 The reason is that we have to override the default consumer group name - `Dev Team A` only has access to consumer groups that have names starting with 'a_'.
 Let's set custom consumer group name that starts with 'a_'
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic a_messages --from-beginning --consumer.config ~/team-a-client.properties --group a_consumer_group_1
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic a_messages \
+      --from-beginning --consumer.config ~/team-a-client.properties --group a_consumer_group_1
 
 We should now receive all the messages for 'a_messages' topic, after which the client blocks waiting for more to come down the stream.
 
-Use CTRL-C to exit, and let's list the topics:
+Use CTRL-C to exit.
+
+
+### Using Kafka CLI Administration Tools
+
+Let's now list the topics:
 
     bin/kafka-topics.sh --bootstrap-server kafka:9092 --command-config ~/team-a-client.properties --list
 
 We get one topic listed: 'a_messages'.
 
 Let's try and list the consumer groups:
 
-    bin/kafka-consumer-groups.sh --bootstrap-server kafka:9092 --command-config ~/team-a-client.properties --list
+    bin/kafka-consumer-groups.sh --bootstrap-server kafka:9092 \
+      --command-config ~/team-a-client.properties --list
 
 Similarly to listing topics, we get one consumer group listed: `a_consumer_group_1`.
 
 There are more CLI administrative tools. For example we can try get default cluster configuration:
 
-    bin/kafka-configs.sh --bootstrap-server kafka:9092 --command-config ~/team-a-client.properties --entity-type brokers --describe --entity-default
+    bin/kafka-configs.sh --bootstrap-server kafka:9092 --command-config ~/team-a-client.properties \
+      --entity-type brokers --describe --entity-default
 
 But that will fail with `Cluster authorization failed.` error, because this operation requires cluster level permissions which `team-a-client` does not have.
 
+
+### Client with Different Permissions
+
 Let's prepare a configuration for `team-b-client`:
 
 ```
@@ -226,14 +262,16 @@ The `Dev Team B` users have full access to topics beginning with 'b_' on Kafka c
 Let's try produce some messages to topic 'a_messages' as `team-b-client`:
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic a_messages --producer.config ~/team-b-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic a_messages \
+  --producer.config ~/team-b-client.properties
 Message 1
 ```
 
 We get `Not authorized to access topics: [a_messages]` error as we expected. Let's try to produce to topic `b_messages`:
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic b_messages --producer.config ~/team-b-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic b_messages \
+  --producer.config ~/team-b-client.properties
 Message 1
 Message 2
 Message 3
@@ -244,15 +282,17 @@ This should work fine.
 What about producing to topic `x_messages`. `team-b-client` is only supposed to be able to read from such a topic.
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages --producer.config ~/team-b-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages \
+  --producer.config ~/team-b-client.properties
 Message 1
 ```
 
 We get a `Not authorized to access topics: [x_messages]` error as we expected. 
 Client `team-a-client`, on the other hand, should be able to write to such a topic:
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages --producer.config ~/team-a-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages \
+  --producer.config ~/team-a-client.properties
 Message 1
 ```
 
@@ -261,6 +301,9 @@ The reason for failure is that while `team-a-client` can write to `x_messages` t
 
 We now need a power user that can create a topic with all the proper settings - like the right number of partitions and replicas.
 
+
+### Power User Can Do Anything
+
 Let's create a configuration for user `bob` who has full ability to manage everything on Kafka cluster `cluster2`.
 
 First, `bob` will authenticate to Keycloak server with username and password and get a refresh token.
@@ -298,7 +341,8 @@ We can use this, because we authenticate with a token directly (in this case a r
 
 Let's now try to create `x_messages` topic:
 
-    bin/kafka-topics.sh --bootstrap-server kafka:9092 --command-config ~/bob.properties --topic x_messages --create --replication-factor 1 --partitions 3
+    bin/kafka-topics.sh --bootstrap-server kafka:9092 --command-config ~/bob.properties \
+      --topic x_messages --create --replication-factor 1 --partitions 1
 
 The operation should succeed. We can list the topics:
 
@@ -314,7 +358,8 @@ Roles `Dev Team A`, and `Dev Team B` both have `Describe` permission on topics t
 We can now again try to produce to the topic as `team-a-client`.
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages --producer.config ~/team-a-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages \
+  --producer.config ~/team-a-client.properties
 Message 1
 Message 2
 Message 3
@@ -325,29 +370,34 @@ This works.
 If we try the same as `team-b-client` it should fail.
 
 ```
-bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages --producer.config ~/team-b-client.properties
+bin/kafka-console-producer.sh --broker-list kafka:9092 --topic x_messages \
+  --producer.config ~/team-b-client.properties
 Message 4
 Message 5
 ```
 
 But `team-b-client` should be able to consume messages from the `x_messages` topic:
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages --from-beginning --consumer.config ~/team-b-client.properties --group x_consumer_group_b
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages \
+      --from-beginning --consumer.config ~/team-b-client.properties --group x_consumer_group_b
 
 Whereas `team-a-client` does not have permission to read, even though they can write:
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages --from-beginning --consumer.config ~/team-a-client.properties --group x_consumer_group_a
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages \
+      --from-beginning --consumer.config ~/team-a-client.properties --group x_consumer_group_a
 
 We get a `Not authorized to access group: x_consumer_group_a` error.
 What if we try to use a consumer group name that starts with 'a_'?
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages --from-beginning --consumer.config ~/team-a-client.properties --group a_consumer_group_a
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages \
+      --from-beginning --consumer.config ~/team-a-client.properties --group a_consumer_group_a
 
 We now get a different error: `Not authorized to access topics: [x_messages]`
 
 It just won't work - `Dev Team A` has no `Read` access on topics that start with 'x_'.
 
 User `bob` should have no problem reading from or writing to any topic:
 
-    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages --from-beginning --consumer.config ~/bob.properties
+    bin/kafka-console-consumer.sh --bootstrap-server kafka:9092 --topic x_messages \
+      --from-beginning --consumer.config ~/bob.properties