Additional documentation for OAuth 0.15.0 features and how to use Service Accounts

api/src/main/java/io/strimzi/api/kafka/model/common/authentication/KafkaClientAuthenticationOAuth.java

@@ -274,7 +274,7 @@ public void setIncludeAcceptHeader(boolean includeAcceptHeader) {
         this.includeAcceptHeader = includeAcceptHeader;
     }
 
-    @Description("Link to Kubernetes Secret containing the client assertion which was manually configured for the client.")
+    @Description("Link to Kubernetes secret containing the client assertion which was manually configured for the client.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public GenericSecretSource getClientAssertion() {
         return clientAssertion;
@@ -294,8 +294,8 @@ public void setClientAssertionLocation(String path) {
         this.clientAssertionLocation = path;
     }
 
-    @Description("The client assertion type. If not set, and `clientAssertion` or `clientAssertionLocation` is configured, " +
-            "then this value defaults to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")
+    @Description("The client assertion type. If not set, and either `clientAssertion` or `clientAssertionLocation` is configured, " +
+            "this value defaults to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public String getClientAssertionType() {
         return clientAssertionType;

api/src/main/java/io/strimzi/api/kafka/model/kafka/listener/KafkaListenerAuthenticationOAuth.java

@@ -287,7 +287,7 @@ public void setIntrospectionEndpointUri(String introspectionEndpointUri) {
         this.introspectionEndpointUri = introspectionEndpointUri;
     }
 
-    @Description("Path to the file on the local filesystem that contains a bearer token to be used instead of client_id and secret when authenticating to authorization server")
+    @Description("Path to the file on the local filesystem that contains a bearer token to be used instead of client ID and secret when authenticating to authorization server.")
     @JsonInclude(JsonInclude.Include.NON_NULL)
     public String getServerBearerTokenLocation() {
         return serverBearerTokenLocation;
@@ -308,10 +308,10 @@ public void setUserNameClaim(String userNameClaim) {
         this.userNameClaim = userNameClaim;
     }
 
-    @Description("The prefix to use with the value of `userNameClaim` to construct the user id. " +
-            "This only takes effect if `userNameClaim` is specified, and the value is present for the claim. " +
-            "When used in combination with `fallbackUserNameClaims` it ensures consistent mapping of usernames and client ids " +
-            "into the same user id space and prevents name collisions.")
+    @Description("The prefix to use with the value of `userNameClaim` to construct the user ID. " +
+            "This only takes effect if `userNameClaim` is specified and the value is present for the claim. " +
+            "When used in combination with `fallbackUserNameClaims`, it ensures consistent mapping of usernames and client IDs " +
+            "into the same user ID space and prevents name collisions.")
     public String getUserNamePrefix() {
         return userNamePrefix;
     }
@@ -320,8 +320,8 @@ public void setUserNamePrefix(String userNamePrefix) {
         this.userNamePrefix = userNamePrefix;
     }
 
-    @Description("The fallback username claim to be used for the user id if the claim specified by `userNameClaim` is not present. " +
-            "This is useful when `client_credentials` authentication only results in the client id being provided in another claim. " +
+    @Description("The fallback username claim to be used for the user ID if the claim specified by `userNameClaim` is not present. " +
+            "This is useful when `client_credentials` authentication only results in the client ID being provided in another claim. " +
             "It only takes effect if `userNameClaim` is set.")
     public String getFallbackUserNameClaim() {
         return fallbackUserNameClaim;

documentation/api/io.strimzi.api.kafka.model.common.authentication.KafkaClientAuthenticationOAuth.adoc

@@ -60,12 +60,12 @@ authentication:
     key: access-token
 ----
 
-.An example of OAuth client authentication using an access token provided in the form of the file on the mounted filesystem
+.Example (service account) access token configuration specifying a mounted file
 [source,yaml,subs=attributes+]
 ----
 authentication:
   type: oauth
-  accessTokenLocation: `/path/to/token/file`
+  accessTokenLocation: `/var/run/secrets/kubernetes.io/serviceaccount/token`
 ----
 
 .Username and password

documentation/modules/appendix_crds.adoc

@@ -263,7 +263,7 @@ It must have the value `oauth` for the type `KafkaListenerAuthenticationOAuth`.
 |Name of the claim from the JWT authentication token, Introspection Endpoint response or User Info Endpoint response which will be used to extract the user id. Defaults to `sub`.
 |fallbackUserNameClaim
 |string
-|The fallback username claim to be used for the user id if the claim specified by `userNameClaim` is not present. This is useful when `client_credentials` authentication only results in the client id being provided in another claim. It only takes effect if `userNameClaim` is set.
+|The fallback username claim to be used for the user ID if the claim specified by `userNameClaim` is not present. This is useful when `client_credentials` authentication only results in the client ID being provided in another claim. It only takes effect if `userNameClaim` is set.
 |fallbackUserNamePrefix
 |string
 |The prefix to use with the value of `fallbackUserNameClaim` to construct the user id. This only takes effect if `fallbackUserNameClaim` is true, and the value is present for the claim. Mapping usernames and client ids into the same user id space is useful in preventing name collisions.
@@ -338,10 +338,10 @@ It must have the value `oauth` for the type `KafkaListenerAuthenticationOAuth`.
 |Whether the Accept header should be set in requests to the authorization servers. The default value is `true`.
 |serverBearerTokenLocation
 |string
-|Path to the file on the local filesystem that contains a bearer token to be used instead of client_id and secret when authenticating to authorization server.
+|Path to the file on the local filesystem that contains a bearer token to be used instead of client ID and secret when authenticating to authorization server.
 |userNamePrefix
 |string
-|The prefix to use with the value of `userNameClaim` to construct the user id. This only takes effect if `userNameClaim` is specified, and the value is present for the claim. When used in combination with `fallbackUserNameClaims` it ensures consistent mapping of usernames and client ids into the same user id space and prevents name collisions.
+|The prefix to use with the value of `userNameClaim` to construct the user ID. This only takes effect if `userNameClaim` is specified and the value is present for the claim. When used in combination with `fallbackUserNameClaims`, it ensures consistent mapping of usernames and client IDs into the same user ID space and prevents name collisions.
 |====
 
 [id='type-GenericSecretSource-{context}']
@@ -2543,13 +2543,13 @@ It must have the value `oauth` for the type `KafkaClientAuthenticationOAuth`.
 |Path to the token file containing an access token to be used for authentication.
 |clientAssertion
 |xref:type-GenericSecretSource-{context}[`GenericSecretSource`]
-|Link to Kubernetes Secret containing the client assertion which was manually configured for the client.
+|Link to Kubernetes secret containing the client assertion which was manually configured for the client.
 |clientAssertionLocation
 |string
 |Path to the file containing the client assertion to be used for authentication.
 |clientAssertionType
 |string
-|The client assertion type. If not set, and `clientAssertion` or `clientAssertionLocation` is configured, then this value defaults to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
+|The client assertion type. If not set, and either `clientAssertion` or `clientAssertionLocation` is configured, this value defaults to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
 |saslExtensions
 |map
 |SASL extensions parameters.