<commit_before>// Module included in the following assemblies:
//
// assembly-securing-kafka-brokers.adoc

[id='con-securing-kafka-authentication-{context}']
= Listener authentication

For clients inside the Kubernetes cluster, you can create `plain` (without encryption) or `tls` _internal_ listeners.

For clients outside the Kubernetes cluster, you create _external_ listeners and specify a connection mechanism,
which can be `nodeport`, `loadbalancer`, `ingress` or `route` (on OpenShift).

For more information on the configuration options for connecting an external client, see xref:assembly-configuring-external-listeners-str[Configuring external listeners].

Supported authentication options:

. Mutual TLS authentication (only on the listeners with TLS enabled encryption)
. SCRAM-SHA-512 authentication
. xref:assembly-oauth-authentication_str[OAuth 2.0 token based authentication]

The authentication option you choose depends on how you wish to authenticate client access to Kafka brokers.

.Kafka listener authentication options
image::listener-config-options.png[options for listener authentication configuration]

The listener `authentication` property is used to specify an authentication mechanism specific to that listener.

If no `authentication` property is specified then the listener does not authenticate clients which connect through that listener.
The listener will accept all connections without authentication.

Authentication must be configured when using the User Operator to manage `KafkaUsers`.

The following example shows:

* A `plain` listener configured for SCRAM-SHA-512 authentication
* A `tls` listener with mutual TLS authentication
* An `external` listener with mutual TLS authentication

Each listener is configured with a unique name and port within a Kafka cluster.

NOTE: Listeners cannot be configured to use the ports reserved for inter-broker communication (9091 or 9090) and metrics (9404).

.An example showing listener authentication configuration
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  - name: plain
    port: 9092
    type: internal
    tls: true
    authentication:
      type: scram-sha-512
  - name: tls
    port: 9093
    type: internal
    tls: true
    authentication:
      type: tls
  - name: external
    port: 9094
    type: loadbalancer
    tls: true
    authentication:
      type: tls
# ...
----

[id='con-mutual-tls-authentication-{context}']
== Mutual TLS authentication

Mutual TLS authentication is always used for the communication between Kafka brokers and ZooKeeper pods.

Strimzi can configure Kafka to use TLS (Transport Layer Security) to provide encrypted communication between Kafka brokers and clients either with or without mutual authentication.
For mutual, or two-way, authentication, both the server and the client present certificates.
When you configure mutual authentication, the broker authenticates the client (client authentication) and the client authenticates the broker (server authentication).

NOTE: TLS authentication is more commonly one-way, with one party authenticating the identity of another.
For example, when HTTPS is used between a web browser and a web server, the browser obtains proof of the identity of the web server.

[id='con-scram-sha-authentication-{context}']
== SCRAM-SHA-512 authentication

SCRAM (Salted Challenge Response Authentication Mechanism) is an authentication protocol that can establish mutual authentication using passwords.
Strimzi can configure Kafka to use SASL (Simple Authentication and Security Layer) SCRAM-SHA-512 to provide authentication on both unencrypted and encrypted client connections.

When SCRAM-SHA-512 authentication is used with a TLS client connection, the TLS protocol provides the encryption, but is not used for authentication.

The following properties of SCRAM make it safe to use SCRAM-SHA-512 even on unencrypted connections:

* The passwords are not sent in the clear over the communication channel.
Instead the client and the server are each challenged by the other to offer proof that they know the password of the authenticating user.

* The server and client each generate a new challenge for each authentication exchange.
This means that the exchange is resilient against replay attacks.

When a `KafkaUser.spec.authentication.type` is configured with `scram-sha-512` the User Operator will generate a random 12-character password consisting of upper and lowercase ASCII letters and numbers.

[id='assembly-kafka-broker-listener-network-policies-{context}']
== Network policies

Strimzi automatically creates a `NetworkPolicy` resource for every listener that is enabled on a Kafka broker.
By default, a `NetworkPolicy` grants access to a listener to all applications and namespaces.

If you want to restrict access to a listener at the network level to only selected applications or namespaces,
use the `networkPolicyPeers` property.

Use network policies as part of the listener authentication configuration.
Each listener can have a different `networkPolicyPeers` configuration.

For more information, refer to the xref:configuration-listener-network-policy-reference[Listener network policies] section and the {K8sNetworkPolicyPeerAPI}.

NOTE: Your configuration of Kubernetes must support ingress `NetworkPolicies` in order to use network policies in Strimzi.

== Additional listener configuration options

You can use the properties of the xref:type-GenericKafkaListenerConfiguration-reference[GenericKafkaListenerConfiguration schema] to add further configuration to listeners.<commit_msg>doc: Minor addition to Network Policy Generation doc (#5553)<commit_after>// Module included in the following assemblies:
//
// assembly-securing-kafka-brokers.adoc

[id='con-securing-kafka-authentication-{context}']
= Listener authentication

For clients inside the Kubernetes cluster, you can create `plain` (without encryption) or `tls` _internal_ listeners.

For clients outside the Kubernetes cluster, you create _external_ listeners and specify a connection mechanism,
which can be `nodeport`, `loadbalancer`, `ingress` or `route` (on OpenShift).

For more information on the configuration options for connecting an external client, see xref:assembly-configuring-external-listeners-str[Configuring external listeners].

Supported authentication options:

. Mutual TLS authentication (only on the listeners with TLS enabled encryption)
. SCRAM-SHA-512 authentication
. xref:assembly-oauth-authentication_str[OAuth 2.0 token based authentication]

The authentication option you choose depends on how you wish to authenticate client access to Kafka brokers.

.Kafka listener authentication options
image::listener-config-options.png[options for listener authentication configuration]

The listener `authentication` property is used to specify an authentication mechanism specific to that listener.

If no `authentication` property is specified then the listener does not authenticate clients which connect through that listener.
The listener will accept all connections without authentication.

Authentication must be configured when using the User Operator to manage `KafkaUsers`.

The following example shows:

* A `plain` listener configured for SCRAM-SHA-512 authentication
* A `tls` listener with mutual TLS authentication
* An `external` listener with mutual TLS authentication

Each listener is configured with a unique name and port within a Kafka cluster.

NOTE: Listeners cannot be configured to use the ports reserved for inter-broker communication (9091 or 9090) and metrics (9404).

.An example showing listener authentication configuration
[source,yaml,subs="attributes+"]
----
# ...
listeners:
  - name: plain
    port: 9092
    type: internal
    tls: true
    authentication:
      type: scram-sha-512
  - name: tls
    port: 9093
    type: internal
    tls: true
    authentication:
      type: tls
  - name: external
    port: 9094
    type: loadbalancer
    tls: true
    authentication:
      type: tls
# ...
----

[id='con-mutual-tls-authentication-{context}']
== Mutual TLS authentication

Mutual TLS authentication is always used for the communication between Kafka brokers and ZooKeeper pods.

Strimzi can configure Kafka to use TLS (Transport Layer Security) to provide encrypted communication between Kafka brokers and clients either with or without mutual authentication.
For mutual, or two-way, authentication, both the server and the client present certificates.
When you configure mutual authentication, the broker authenticates the client (client authentication) and the client authenticates the broker (server authentication).

NOTE: TLS authentication is more commonly one-way, with one party authenticating the identity of another.
For example, when HTTPS is used between a web browser and a web server, the browser obtains proof of the identity of the web server.

[id='con-scram-sha-authentication-{context}']
== SCRAM-SHA-512 authentication

SCRAM (Salted Challenge Response Authentication Mechanism) is an authentication protocol that can establish mutual authentication using passwords.
Strimzi can configure Kafka to use SASL (Simple Authentication and Security Layer) SCRAM-SHA-512 to provide authentication on both unencrypted and encrypted client connections.

When SCRAM-SHA-512 authentication is used with a TLS client connection, the TLS protocol provides the encryption, but is not used for authentication.

The following properties of SCRAM make it safe to use SCRAM-SHA-512 even on unencrypted connections:

* The passwords are not sent in the clear over the communication channel.
Instead the client and the server are each challenged by the other to offer proof that they know the password of the authenticating user.

* The server and client each generate a new challenge for each authentication exchange.
This means that the exchange is resilient against replay attacks.

When a `KafkaUser.spec.authentication.type` is configured with `scram-sha-512` the User Operator will generate a random 12-character password consisting of upper and lowercase ASCII letters and numbers.

[id='assembly-kafka-broker-listener-network-policies-{context}']
== Network policies

By default, Strimzi automatically creates a `NetworkPolicy` resource for every listener that is enabled on a Kafka broker.
This `NetworkPolicy` allows applications to connect to listeners in all namespaces.
Use network policies as part of the listener authentication configuration. 

If you want to restrict access to a listener at the network level to only selected applications or namespaces, use the `networkPolicyPeers` property.
Each listener can have a different xref:configuration-listener-network-policy-reference[`networkPolicyPeers`] configuration.
For more information on network policy peers, refer to the {K8sNetworkPolicyPeerAPI}.

If you want to use custom network policies, you can set the `STRIMZI_NETWORK_POLICY_GENERATION` environment variable to `false` in the Cluster Operator configuration.
For more information, see xref:ref-operator-cluster-{context}[Cluster Operator configuration]. 

NOTE: Your configuration of Kubernetes must support ingress `NetworkPolicies` in order to use network policies in Strimzi.

.Additional resources

* xref:configuration-listener-network-policy-reference[`networkPolicyPeers`] 

== Additional listener configuration options

You can use the properties of the xref:type-GenericKafkaListenerConfiguration-reference[GenericKafkaListenerConfiguration schema] to add further configuration to listeners.
{'fraction_non_alphanumeric': 0.05393939393939394, 'fraction_numerical': 0.009523809523809525, 'mean_word_length': 5.089088033737481, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, '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': '1460946', 'n_tokens_mistral': 2853, 'n_tokens_neox': 2670, 'n_words': 1380}