<commit_before>// Module included in the following module:
//
// con-oauth-config.adoc

[id='proc-oauth-broker-config-{context}']
= Configuring {oauth} support for Kafka brokers

This procedure describes how to configure Kafka brokers so that the broker listeners are enabled to use {oauth} authentication using an authorization server.

If the authorization server is using certificates signed by the trusted CA and matching the {oauth} server hostname, TLS connection works using the default settings.
Otherwise, you have two connection options for your external listener configuration when delegating token validation to the authorization server:

. TLS connection to the authorization server with trusted certificates
. Direct connection using an introspection endpoint configuration

Both options are described in this procedure.


.Before you start

For more information on the configuration and authentication of Kafka broker listeners, see:

* xref:assembly-configuring-kafka-broker-listeners-deployment-configuration-kafka[Kafka broker listeners]
* xref:assembly-kafka-authentication-and-authorization-deployment-configuration-kafka[Authentication and Authorization]

.Prerequisites

* {ProductName} and Kafka are running
* An {oauth} authorization server is deployed

.Procedure

. Update the Kafka broker configuration (`Kafka.spec.kafka`) of your `Kafka` resource in an editor.
+
[source,shell]
----
kubectl edit kafka my-cluster
----

. Configure the Kafka broker `listeners` configuration.
+
The configuration for each type of listener does not have to be the same, as they are independent.
+
For example:
+
[source,yaml,subs="+quotes,attributes"]
----
#...
   authentication:
     type: oauth <1>
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/master__> <2>
     jwksEndpointUri: <__https://<authorization-server-address>/auth/realms/master/protocol/openid-connect/certs__> <3>
     userNameClaim: preferred_username <4>

#external configuration
 external:
   type: loadbalancer

   //Option 1
   authentication: <5>
     type: oauth
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/external__>
     jwksEndpointUri: <__https://<authorization-server-address>/auth/realms/external/protocol/openid-connect/certs__>
     userNameClaim: preferred_username
     tlsTrustedCertificates: <6>
     - secretName: oauth-server-cert
       certificate: ca.crt
   disableTlsHostnameVerification: true <7>

   //Option 2
   authentication: <8>
     type: oauth
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/external__>
     introspectionEndpointUri: <__https://<authorization-server-address>/auth/realms/external/protocol/openid-connect/token/introspect__>
     clientId: kafka-broker
     clientSecret:
       secretName: my-cluster-oauth
       key: clientSecret

----
<1> Listener type set to `oauth`.
<2> URI of the token issuer used for authentication.
<3> URI of the JWKS certificate endpoint used for local JWT validation.
<4> The user name profile claim (or key) that contains the actual user name in the token. The user name is the _principal_ used to identify the user. The `userNameClaim` value will depend on the authentication flow and the authorization server used.
<5> OPTION 1: TLS connection to the authorization server.
<6> (Optional) Trusted certificates for TLS connection to the authorization server.
<7> Enable TLS hostname verification. Default is `false`.
<8> OPTION 2: Introspection endpoint to connect directly to the authorization server.

. Save and exit the editor, then wait for rolling updates to complete.

. Check the update in the logs or by watching the pod state transitions:
+
[source,shell,subs="+quotes,attributes"]
----
kubectl logs -f ${POD_NAME} -c ${CONTAINER_NAME}
kubectl get po -w
----
+
The rolling update configures the brokers to use {oauth} authentication.

.What to do next

* xref:proc-oauth-client-config-{context}[Configure your Kafka clients to use {oauth}]
<commit_msg>Fix indentation and description for OAuth docs (#2201)<commit_after>// Module included in the following module:
//
// con-oauth-config.adoc

[id='proc-oauth-broker-config-{context}']
= Configuring {oauth} support for Kafka brokers

This procedure describes how to configure Kafka brokers so that the broker listeners are enabled to use {oauth} authentication using an authorization server.

If the authorization server is using certificates signed by the trusted CA and matching the {oauth} server hostname, TLS connection works using the default settings.
Otherwise, you have two connection options for your external listener configuration when delegating token validation to the authorization server:

. TLS connection to the authorization server with trusted certificates
. Direct connection using an introspection endpoint configuration

Both options are described in this procedure.


.Before you start

For more information on the configuration and authentication of Kafka broker listeners, see:

* xref:assembly-configuring-kafka-broker-listeners-deployment-configuration-kafka[Kafka broker listeners]
* xref:assembly-kafka-authentication-and-authorization-deployment-configuration-kafka[Authentication and Authorization]

.Prerequisites

* {ProductName} and Kafka are running
* An {oauth} authorization server is deployed

.Procedure

. Update the Kafka broker configuration (`Kafka.spec.kafka`) of your `Kafka` resource in an editor.
+
[source,shell]
----
kubectl edit kafka my-cluster
----

. Configure the Kafka broker `listeners` configuration.
+
The configuration for each type of listener does not have to be the same, as they are independent.
+
For example:
+
[source,yaml,subs="+quotes,attributes"]
----
#...
   authentication:
     type: oauth <1>
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/master__> <2>
     jwksEndpointUri: <__https://<authorization-server-address>/auth/realms/master/protocol/openid-connect/certs__> <3>
     userNameClaim: preferred_username <4>

#external configuration
 external:
   type: loadbalancer

   //Option 1
   authentication: <5>
     type: oauth
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/external__>
     jwksEndpointUri: <__https://<authorization-server-address>/auth/realms/external/protocol/openid-connect/certs__>
     userNameClaim: preferred_username
     tlsTrustedCertificates: <6>
     - secretName: oauth-server-cert
       certificate: ca.crt
     disableTlsHostnameVerification: true <7>

   //Option 2
   authentication: <8>
     type: oauth
     validIssuerUri: <__https://<authorization-server-address>/auth/realms/external__>
     introspectionEndpointUri: <__https://<authorization-server-address>/auth/realms/external/protocol/openid-connect/token/introspect__>
     clientId: kafka-broker
     clientSecret:
       secretName: my-cluster-oauth
       key: clientSecret

----
<1> Listener type set to `oauth`.
<2> URI of the token issuer used for authentication.
<3> URI of the JWKS certificate endpoint used for local JWT validation.
<4> The user name profile claim (or key) that contains the actual user name in the token. The user name is the _principal_ used to identify the user. The `userNameClaim` value will depend on the authentication flow and the authorization server used.
<5> OPTION 1: TLS connection to the authorization server.
<6> (Optional) Trusted certificates for TLS connection to the authorization server.
<7> (Optional) Disable TLS hostname verification. Default is `false`.
<8> OPTION 2: Introspection endpoint to connect directly to the authorization server.

. Save and exit the editor, then wait for rolling updates to complete.

. Check the update in the logs or by watching the pod state transitions:
+
[source,shell,subs="+quotes,attributes"]
----
kubectl logs -f ${POD_NAME} -c ${CONTAINER_NAME}
kubectl get po -w
----
+
The rolling update configures the brokers to use {oauth} authentication.

.What to do next

* xref:proc-oauth-client-config-{context}[Configure your Kafka clients to use {oauth}]

{'fraction_non_alphanumeric': 0.08755417956656347, 'fraction_numerical': 0.005448916408668731, 'mean_word_length': 4.460446247464503, 'pattern_counts': {'":': 0, '<': 59, '<?xml version=': 0, '>': 59, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5933311', 'n_tokens_mistral': 2289, 'n_tokens_neox': 2211, 'n_words': 822}