Fixes to examples/README-authz.md

Signed-off-by: Marko Strukelj <[email protected]>

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,6 +22,9 @@ 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
@@ -30,13 +34,17 @@ Let's start up all the containers with authorization configured, and we'll then
     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,7 +69,10 @@ 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:
 
@@ -102,6 +113,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 +126,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,7 +164,10 @@ 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
@@ -172,7 +190,10 @@ 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
@@ -186,7 +207,12 @@ Let's set custom consumer group name that starts with 'a_'
 
 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
 
@@ -204,6 +230,9 @@ There are more CLI administrative tools. For example we can try get default clus
 
 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`:
 
 ```
@@ -261,6 +290,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.