.. _confluentsecurityplugins_propagation:

Principal Propagation
=====================

.. important:: This is a Confluent Enterprise-only feature.

Principal propagation takes the principal from authentication mechanism configured for client to
the REST proxy and propagates that same principal when making requests to the Kafka broker.

Kafka supports the SSL and SASL authentication mechanisms that are based on the client's
``security.protocol`` config. Principal propagation is supported for the supported Kafka security
mechanisms by setting up the client appropriately.

For further reference on Kafka Security, please refer to :ref:`Kafka Security <kafka_security>`.

SSL
---

SSL propagation is picked by the plugin when the ``security.protocol`` is set to ``SSL``. For SSL
propagation to work, it is required to all load all the certificates corresponding to the
required principal in a single client KeyStore file. Once this is done, the plugin would pick
the appropriate certificate alias based on the logged on principal while making requests to Kafka
. Currently, the logged on principal must exactly match the X500 Principal of the
certificate. This is straight forward when SSL is used as the authentication mechanism. 

For example, if there were two clients integrated to Kafka REST the setup could be as simple as
below

- `Client A` authenticates to Kafka REST using its key store which contains `Certificate-A`
- `Client B` authenticates to Kafka REST using its key store which contains `Certificate-B`
- Kafka REST's key store ``client.ssl.keystore.location`` is loaded with `Certificate-A` and `Certificate-B`. The certificate is then chosen by the plugin based on who the client is.

If the ACL's need to be setup with different principal other than the default X500 on the Kafka
broker, you can provide a custom principal builder for Kafka using the broker server.properties

.. sourcecode:: bash

   principal.builder.class=CustomizedPrincipalBuilderClass


SASL
----

SASL propagation is picked by the plugin when the ``security.protocol`` is set to either of
``SASL_PLAIN`` or ``SASL_SSL``. Security plugin supports all the ``sasl.mechanism`` supported by
Kafka clients. Just like a regular Kafka client, the plugin also expects a JAAS config file to be
configured through ``-Djava.security.auth.login.config``. It is required for all the principals
to be specified in the JAAS config file under the section ``KafkaClient``.  Refer to :ref:`SASL
Configuration<kafka_sasl>` for details about configuring SASL for Kafka client and broker.

In the JAAS config file all the principals need to be explicitly specified. The plugin supports
specifying principals using following supported mechanisms: `GSSAPI`, `PLAIN`, `SCRAM-SHA-256` and
`SCRAM-SHA-512`. Also, the plugin ignores any configured ``sasl.mechanism`` and picks it
automatically based on the LoginModule specified for the principal.

.. sourcecode:: bash

   KafkaClient {
     com.sun.security.auth.module.Krb5LoginModule required
     useKeyTab=true
     storeKey=true
     keyTab="/etc/security/keytabs/kafka_client.keytab"
     principal="kafka-client-1@EXAMPLE.COM";

     com.sun.security.auth.module.Krb5LoginModule required
     useKeyTab=true
     storeKey=true
     keyTab="/etc/security/keytabs/kafka_client_2.keytab"
     principal="kafka-client-2@EXAMPLE.COM";

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

     org.apache.kafka.common.security.scram.ScramLoginModule required
     username="alice-scram"
     password="alice-secret";

     org.apache.kafka.common.security.scram.ScramLoginModule required
     username="alice-scram-256"
     password="alice-secret"
     mechanism="SCRAM-SHA-256";
   };

Below is the mapping of ``sasl.mechanism`` for the configured login modules

+-----------------------------------------------------------+--------------------------------+
| Principal's Login Module                                  | SASL Mechanism                 |
+===========================================================+================================+
| com.sun.security.auth.module.Krb5LoginModule              | | GSSAPI                       |
+-----------------------------------------------------------+--------------------------------+
| org.apache.kafka.common.security.plain.PlainLoginModule   | | PLAIN                        |
+-----------------------------------------------------------+--------------------------------+
| org.apache.kafka.common.security.scram.ScramLoginModule   |  SCRAM-SHA-512                 |
|                                                           |                                |
|                                                           | | For SCRAM-SHA-256 set        |
|                                                           | | ``mechanism=SCRAM-SHA-256``  |
|                                                           | | as an option in              |
|                                                           |   ScramLoginModule             |
+-----------------------------------------------------------+--------------------------------+


All the mechanisms except ``SCRAM-SHA-256`` would be automatically detected by the plugin and
SCRAM-SHA-256 can be explicitly mentioned as an option in the ScramLoginModule.