Some OIDC documentation fixes

CONFIGURATION.md

@@ -92,12 +92,12 @@ sasl.password | * | |
 sasl.oauthbearer.config | * | | | low | SASL/OAUTHBEARER configuration. The format is implementation-dependent and must be parsed accordingly. The default unsecured token implementation (see https://tools.ietf.org/html/rfc7515#appendix-A.5) recognizes space-separated name=value pairs with valid names including principalClaimName, principal, scopeClaimName, scope, and lifeSeconds. The default value for principalClaimName is "sub", the default value for scopeClaimName is "scope", and the default value for lifeSeconds is 3600. The scope value is CSV format with the default value being no/empty scope. For example: `principalClaimName=azp principal=admin scopeClaimName=roles scope=role1,role2 lifeSeconds=600`. In addition, SASL extensions can be communicated to the broker via `extension_NAME=value`. For example: `principal=admin extension_traceId=123` <br>*Type: string*
 enable.sasl.oauthbearer.unsecure.jwt | * | true, false | false | low | Enable the builtin unsecure JWT OAUTHBEARER token handler if no oauthbearer_refresh_cb has been set. This builtin handler should only be used for development or testing, and not in production. <br>*Type: boolean*
 oauthbearer_token_refresh_cb | * | | | low | SASL/OAUTHBEARER token refresh callback (set with rd_kafka_conf_set_oauthbearer_token_refresh_cb(), triggered by rd_kafka_poll(), et.al. This callback will be triggered when it is time to refresh the client's OAUTHBEARER token. Also see `rd_kafka_conf_enable_sasl_queue()`. <br>*Type: see dedicated API*
-sasl.oauthbearer.method | * | default, oidc | default | low | Set to "default" or "oidc" to control which login method is used. If set it to "oidc", OAuth/OIDC login method will be used. sasl.oauthbearer.client.id, sasl.oauthbearer.client.secret, and sasl.oauthbearer.token.endpoint.url are needed if sasl.oauthbearer.method is set to "oidc". <br>*Type: enum value*
-sasl.oauthbearer.client.id | * | | | low | It's a public identifier for the application. It must be unique across all clients that the authorization server handles. This is only used when sasl.oauthbearer.method is set to oidc. <br>*Type: string*
-sasl.oauthbearer.client.secret | * | | | low | A client secret only known to the application and the authorization server. This should be a sufficiently random string that are not guessable. This is only used when sasl.oauthbearer.method is set to "oidc". <br>*Type: string*
-sasl.oauthbearer.scope | * | | | low | Client use this to specify the scope of the access request to the broker. This is only used when sasl.oauthbearer.method is set to "oidc". <br>*Type: string*
-sasl.oauthbearer.extensions | * | | | low | Allow additional information to be provided to the broker. It's comma-separated list of key=value pairs. The example of the input is "supportFeatureX=true,organizationId=sales-emea". This is only used when sasl.oauthbearer.method is set to "oidc". <br>*Type: string*
-sasl.oauthbearer.token.endpoint.url | * | | | low | OAUTH issuer token endpoint HTTP(S) URI used to retrieve the token. This is only used when sasl.oauthbearer.method is set to "oidc". <br>*Type: string*
+sasl.oauthbearer.method | * | default, oidc | default | low | Set to "default" or "oidc" to control which login method to be used. If set to "oidc", the following properties must also be be specified: `sasl.oauthbearer.client.id`, `sasl.oauthbearer.client.secret`, and `sasl.oauthbearer.token.endpoint.url`. <br>*Type: enum value*
+sasl.oauthbearer.client.id | * | | | low | Public identifier for the application. Must be unique across all clients that the authorization server handles. Only used when `sasl.oauthbearer.method` is set to "oidc". <br>*Type: string*
+sasl.oauthbearer.client.secret | * | | | low | Client secret only known to the application and the authorization server. This should be a sufficiently random string that is not guessable. Only used when `sasl.oauthbearer.method` is set to "oidc". <br>*Type: string*
+sasl.oauthbearer.scope | * | | | low | Client use this to specify the scope of the access request to the broker. Only used when `sasl.oauthbearer.method` is set to "oidc". <br>*Type: string*
+sasl.oauthbearer.extensions | * | | | low | Allow additional information to be provided to the broker. Comma-separated list of key=value pairs. E.g., "supportFeatureX=true,organizationId=sales-emea".Only used when `sasl.oauthbearer.method` is set to "oidc". <br>*Type: string*
+sasl.oauthbearer.token.endpoint.url | * | | | low | OAuth/OIDC issuer token endpoint HTTP(S) URI used to retrieve token. Only used when `sasl.oauthbearer.method` is set to "oidc". <br>*Type: string*
 plugin.library.paths | * | | | low | List of plugin libraries to load (; separated). The library search path is platform dependent (see dlopen(3) for Unix and LoadLibrary() for Windows). If no filename extension is specified the platform-specific extension (such as .dll or .so) will be appended automatically. <br>*Type: string*
 interceptors | * | | | low | Interceptors added through rd_kafka_conf_interceptor_add_..() and any configuration handled by interceptors. <br>*Type: see dedicated API*
 group.id | C | | | high | Client group id string. All clients sharing the same group.id belong to the same group. <br>*Type: string*

INTRODUCTION.md

@@ -55,7 +55,7 @@ librdkafka also provides a native C++ interface.
  - [Threads and callbacks](#threads-and-callbacks)
  - [Brokers](#brokers)
  - [SSL](#ssl)
- - [OAUTHBEARER with Support for OIDC](#oauthbearer-with-support-for-oidc)
+ - [OAUTHBEARER with support for OIDC](#oauthbearer-with-support-for-oidc)
  - [Sparse connections](#sparse-connections)
  - [Random broker selection](#random-broker-selection)
  - [Persistent broker connections](#persistent-broker-connections)
@@ -1125,28 +1125,28 @@ For example, to read both intermediate and root CAs, set
 `ssl.ca.certificate.stores=CA,Root`.
 
 
-#### OAUTHBEARER with Support for OIDC
+#### OAUTHBEARER with support for OIDC
 
-Oauthbearer with OIDC is another way for the client to connect to a broker's
-SASL endpoints/listeners. To use this method the client needs to be
-configured with `security.protocol=SASL_SSL` for SASL authentication
-and SSL transport, and `sasl.oauthbearer.method=OIDC` to use
-OIDC with OAUTHBEARER.
+OAUTHBEARER with OIDC provides a method for the client to authenticate to the
+Kafka cluster by requesting an authentication token from an issuing server
+and passing the retrieved token to brokers during connection setup.
 
-OAUTHBEARER with OIDC will also require configuration of the
-following configuration properties:
+To use this authentication method the client needs to be configured as follows:
 
- * `sasl.oauthbearer.token.endpoint.url` - OAUTH issuer token endpoint HTTP(S)
- URI used to retrieve the token.
- * `sasl.oauthbearer.client.id` - A public identifier for the application.
+ * `security.protocol` - set to `SASL_SSL` or `SASL_PLAINTEXT`.
+ * `sasl.mechanism` - set to `OAUTHBEARER`.
+ * `sasl.oauthbearer.method` - set to `OIDC`.
+ * `sasl.oauthbearer.token.endpoint.url` - OAUTH issuer token
+ endpoint HTTP(S) URI used to retrieve the token.
+ * `sasl.oauthbearer.client.id` - public identifier for the application.
  It must be unique across all clients that the authorization server handles.
- * `sasl.oauthbearer.client.secret` - This is only known to the application
- and the authorization server. This should be a sufficiently random string
- that is not guessable.
- * `sasl.oauthbearer.scope` - Client use this to specify the scope of the
+ * `sasl.oauthbearer.client.secret` - secret known only to the
+ application and the authorization server.
+ This should be a sufficiently random string that is not guessable.
+ * `sasl.oauthbearer.scope` - clients use this to specify the scope of the
  access request to the broker.
- * `sasl.oauthbearer.extensions` - Allow additional information to be provided
- to the broker. It's a comma-separated list of key=value pairs.
+ * `sasl.oauthbearer.extensions` - (optional) additional information to be
+ provided to the broker. A comma-separated list of key=value pairs.
  For example:
  `supportFeatureX=true,organizationId=sales-emea`
 

src/rdkafka_conf.c

@@ -949,49 +949,45 @@ static const struct rd_kafka_property rd_kafka_properties[] = {
  {_RK_GLOBAL, "sasl.oauthbearer.method", _RK_C_S2I,
  _RK(sasl.oauthbearer.method),
  "Set to \"default\" or \"oidc\" to control which login method "
- "is used. If set it to \"oidc\", OAuth/OIDC login method will "
- "be used. "
- "sasl.oauthbearer.client.id, sasl.oauthbearer.client.secret, "
- "and sasl.oauthbearer.token.endpoint.url are needed if "
- "sasl.oauthbearer.method is set to \"oidc\".",
+ "to be used. If set to \"oidc\", the following properties must also be "
+ "be specified: "
+ "`sasl.oauthbearer.client.id`, `sasl.oauthbearer.client.secret`, "
+ "and `sasl.oauthbearer.token.endpoint.url`.",
  .vdef = RD_KAFKA_SASL_OAUTHBEARER_METHOD_DEFAULT,
  .s2i = {{RD_KAFKA_SASL_OAUTHBEARER_METHOD_DEFAULT, "default"},
  {RD_KAFKA_SASL_OAUTHBEARER_METHOD_OIDC, "oidc"}},
  _UNSUPPORTED_OIDC},
  {_RK_GLOBAL, "sasl.oauthbearer.client.id", _RK_C_STR,
  _RK(sasl.oauthbearer.client_id),
- "It's a public identifier for the application. "
- "It must be unique across all clients that the "
+ "Public identifier for the application. "
+ "Must be unique across all clients that the "
  "authorization server handles. "
- "This is only used when sasl.oauthbearer.method is set to oidc.",
+ "Only used when `sasl.oauthbearer.method` is set to \"oidc\".",
  _UNSUPPORTED_OIDC},
  {_RK_GLOBAL, "sasl.oauthbearer.client.secret", _RK_C_STR,
  _RK(sasl.oauthbearer.client_secret),
- "A client secret only known to the application and the "
+ "Client secret only known to the application and the "
  "authorization server. This should be a sufficiently random string "
- "that are not guessable. "
- "This is only used when sasl.oauthbearer.method is set to \"oidc\".",
+ "that is not guessable. "
+ "Only used when `sasl.oauthbearer.method` is set to \"oidc\".",
  _UNSUPPORTED_OIDC},
  {_RK_GLOBAL, "sasl.oauthbearer.scope", _RK_C_STR,
  _RK(sasl.oauthbearer.scope),
  "Client use this to specify the scope of the access request to the "
  "broker. "
- "This is only used when sasl.oauthbearer.method is set to \"oidc\".",
+ "Only used when `sasl.oauthbearer.method` is set to \"oidc\".",
  _UNSUPPORTED_OIDC},
  {_RK_GLOBAL, "sasl.oauthbearer.extensions", _RK_C_STR,
  _RK(sasl.oauthbearer.extensions_str),
  "Allow additional information to be provided to the broker. "
- "It's comma-separated list of key=value pairs. "
- "The example of the input is "
- "\"supportFeatureX=true,organizationId=sales-emea\"."
- " This is only used when sasl.oauthbearer.method is set "
- "to \"oidc\".",
+ "Comma-separated list of key=value pairs. "
+ "E.g., \"supportFeatureX=true,organizationId=sales-emea\"."
+ "Only used when `sasl.oauthbearer.method` is set to \"oidc\".",
  _UNSUPPORTED_OIDC},
  {_RK_GLOBAL, "sasl.oauthbearer.token.endpoint.url", _RK_C_STR,
  _RK(sasl.oauthbearer.token_endpoint_url),
- "OAUTH issuer token endpoint HTTP(S) URI used to retrieve the "
- "token. "
- "This is only used when sasl.oauthbearer.method is set to \"oidc\".",
+ "OAuth/OIDC issuer token endpoint HTTP(S) URI used to retrieve token. "
+ "Only used when `sasl.oauthbearer.method` is set to \"oidc\".",
  _UNSUPPORTED_OIDC},
 
  /* Plugins */