.. _kafka_sasl_auth:

Authentication with SASL
-------------------------

|ak-tm| brokers supports client authentication via SASL. SASL authentication can be enabled concurrently with SSL encryption (SSL client authentication will be disabled).

The supported SASL mechanisms are:

* :ref:`GSSAPI <kafka_sasl_auth_gssapi>` (Kerberos)
* :ref:`OAUTHBEARER <kafka_oauth_auth>`
* :ref:`SCRAM <kafka_sasl_auth_scram>`
* :ref:`PLAIN <kafka_sasl_auth_plain>`
* :ref:`Delegation Tokens <kafka_sasl_delegate_auth>`
* :ref:`LDAP <client-auth-with-ldap>` 

.. include:: ../../includes/cp-demo-tip.rst

.. _jaas-configurations:

JAAS configurations
~~~~~~~~~~~~~~~~~~~

|ak| uses the Java Authentication and Authorization Service (`JAAS <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASRefGuide.html>`_)
for SASL configuration. You must provide JAAS configurations for all SASL authentication mechanisms.

Brokers can configure JAAS by passing a static JAAS configuration file into the JVM using the ``java.security.auth.login.config`` property at runtime. For example:

.. codewithvars:: bash

     export KAFKA_OPTS="-Djava.security.auth.login.config=/etc/kafka/kafka_server_jaas.conf"
     bin/kafka-server-start etc/kafka/server.properties

.. include:: ../../includes/installation-types-zip-tar.rst

``KafkaServer`` is the section name in the JAAS file used by each broker. This section provides
SASL configuration options for the broker, including any SASL client connections made by the broker
for inter-broker communication.  If multiple listeners are configured to use SASL, you can prefix
the section name with the lower-case listener name followed by a period, e.g. ``sasl_ssl.KafkaServer``.

Brokers can also configure JAAS using the broker configuration property ``sasl.jaas.config``.
You must prefix the property name with the listener prefix, including the SASL mechanism,
i.e. ``listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config``. You can only specify
one login module in the config value.  To configure multiple mechanisms on a listener, you must
provide a separate config for each mechanism using the listener and mechanism prefix. For example:

.. codewithvars:: bash

  listener.name.sasl_ssl.scram-sha-256.sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
    username="admin" \
    password="admin-secret";
  listener.name.sasl_ssl.plain.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
    username="admin" \
    password="admin-secret" \
    user_admin="admin-secret" \
    user_alice="alice-secret";

This is the preferred method of configuring JAAS for brokers.

If JAAS configuration is defined at different levels, the order of precedence used is:

1. Broker configuration property ``listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config``
2. ``{listenerName}.KafkaServer`` section of static JAAS configuration
3. ``KafkaServer`` section of static JAAS configuration


Clients also have two ways to configure JAAS:

1. pass a static JAAS configuration file into the JVM using the ``java.security.auth.login.config`` property at runtime, as done with brokers
2. embed the JAAS configuration itself in the configuration property ``sasl.jaas.config``

The preferred method for clients is the second way: to embed the JAAS configuration itself in the configuration property ``sasl.jaas.config``, or whatever is the client's prefixed configuration property for ``sasl.jaas.config``. For example: 

.. codewithvars:: bash

   sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
      username="confluent" \
      password="confluent-secret";

If a client specifies both the client property ``sasl.jaas.config`` and the static JAAS configuration system property ``java.security.auth.login.config``, the client property ``sasl.jaas.config`` will be used.


.. _kafka_sasl_jaas_c3:

JAAS and |c3|
'''''''''''''''''''''''''''''''''

There is one scenario when you should explicitly use the client property ``sasl.jaas.config`` instead of passing in the JVM argument ``-Djava.security.auth.login.config=/path/to/jaas.config``, and that is when you are using |c3| that has its own |ak| cluster separate from the production cluster being monitored, and the security profile differs between the two clusters.

If you were to use ``java.security.auth.login.config``, it would set a single configuration for the whole JVM for communicating to the production cluster being monitored as well as the cluster backing Control Center. This may be undesirable because this wouldn't distinguish security profiles to each cluster.

Instead, use the client property to differentiate the security profiles, i.e., different JAAS configurations, depending on the target cluster:

* production cluster: e.g., ``sasl.jaas.config``
* monitoring cluster: for |cmetric-full| use ``confluent.metrics.reporter.sasl.jaas.config``, and for Confluent Monitoring Interceptors use ``confluent.monitoring.interceptor.sasl.jaas.config``.


.. _kafka_sasl_multi_mechanisms:

Enabling multiple SASL mechanisms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Multiple SASL mechanisms can be enabled on the broker simultaneously while each client has to choose one mechanism. 

Specify the configuration for the login modules of all enabled mechanisms in the ``KafkaServer`` section of the broker JAAS config file. For example:

.. codewithvars:: bash

   KafkaServer {
     com.sun.security.auth.module.Krb5LoginModule required
     useKeyTab=true
     storeKey=true
     keyTab="/etc/security/keytabs/kafka_server.keytab"
     principal="kafka/kafka1.hostname.com@EXAMPLE.COM";

     org.apache.kafka.common.security.plain.PlainLoginModule required
     username="admin"
     password="admin-secret"
     user_admin="admin-secret"
     user_alice="alice-secret";
  };

Enable the SASL mechanisms in ``server.properties``:

.. codewithvars:: bash

   # List of enabled mechanisms, can be more than one
   sasl.enabled.mechanisms=GSSAPI,PLAIN

Specify the SASL security protocol and mechanism for inter-broker communication in ``server.properties`` if required:

.. codewithvars:: bash

   # Configure SASL_SSL if SSL encryption is enabled, otherwise configure SASL_PLAINTEXT
   security.inter.broker.protocol=SASL_SSL

   # Configure the appropriate inter-broker protocol
   sasl.mechanism.inter.broker.protocol=GSSAPI


Then follow the mechanism-specific steps in :ref:`GSSAPI <sasl_gssapi_broker>`, :ref:`SCRAM <sasl_scram_broker>`, and :ref:`PLAIN <sasl_plain_broker>` to configure SASL for the enabled mechanisms.


Modifying SASL mechanisms in a Running Cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The SASL mechanisms can be modified in a running cluster using the following sequence:

1. Enable new SASL mechanism by adding the mechanism to ``sasl.enabled.mechanisms`` in ``server.properties`` for each broker. Update JAAS config file to
   include both mechanisms as described :ref:`here <kafka_sasl_multi_mechanisms>`. Incrementally restart the cluster nodes, taking into consideration the recommendations for doing :ref:`rolling restarts <rolling_restart>` to avoid downtime for end users..
2. Restart clients using the new mechanism (if required).
3. To change the inter-broker communication mechanism (if required), set ``sasl.mechanism.inter.broker.protocol`` in ``server.properties`` to the new mechanism and
   incrementally restart the cluster again.
4. To remove the old mechanism (if required), remove the old mechanism from ``sasl.enabled.mechanisms`` in ``server.properties`` and remove the entries for the
   old mechanism from JAAS config file. Incrementally restart the cluster again.

Note that the sequence above is somewhat complex to cater for all possible mechanism changes. For example, to add a new mechanism in the brokers and swap the clients to use it, you would have to do steps 1 and 2.


.. toctree::
   :hidden:
   :maxdepth: 1

   authentication_sasl_gssapi
   authentication_sasl_oauth
   authentication_sasl_plain
   authentication_sasl_scram
   authentication_sasl_delegation
   client-authentication-ldap