.. _confluentsecurityplugins_kafaka_rest_security_plugin:

Kafka REST Security Plugin
==========================

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

Kafka REST Proxy allows producing and consuming messages through a REST interface. The security
plugin adds the capability to authenticate the incoming request, build the principal and then
propagate the same to the requests to Kafka using the configured security mechanism. The
authorization is enforced through Kafka ACL's.

.. note:: Kafka REST Security plugin and ACLs do not work with the V1 consumer APIs since it
 uses a simple consumer which doesn't support Kafka Security.

Installation
------------

These JAR files must be available in the classpath of the Kafka REST deployment. You can get the files by following the download
instructions at :ref:`Security Plugin Installation <confluentsecurityplugins_installation>`.

* confluent-security-plugins-common-<version>.jar
* confluent-kafka-rest-security-plugin-<version.jar

Once the installation is done, the plugins can be activated by adding the following config in the
Kafka REST config file

.. sourcecode:: bash

 kafka.rest.resource.extension.class=io.confluent.kafkarest.security.KafkaRestSecurityResourceExtension

``kafka.rest.resource.extension.class``
  Fully qualified class name of a  valid implementation of the interface RestResourceExtension.
  This can be used to inject user defined resources like filters. Typically used to add custom
  capability like logging, security, etc

  * Type: string
  * Default: ""
  * Importance: low

Authentication Mechanisms
-------------------------

The authentication mechanism for the incoming requests is determined by the ``confluent.rest.auth
.propagate.method`` config. The only only supported mechanism at present is `SSL`. It is required
to set the ``ssl.client.auth`` to true in the Kafka REST config to use the SSL mechanism. Failing
which, all requests
would be rejected with a HTTP error code of 403.

The incoming X500 principal from the client is used as the principal while interacting
with all requests to the Kafka Broker. While connecting to the broker, the authentication happens via
SSL/SASL depending on the value of  ``client.security.protocol`` in the Kafka REST config. The
details of how the propagation happens and how the security needs to be configured  can be found at
:ref:`Principal Propagation<confluentsecurityplugins_propagation>`


On a high level, the following are required for each of the security protocols:

- **SSL** - keystore loaded with all certificates corresponding to all required principal; configured via ``client.ssl.keystore.type``
- **SASL** - JAAS config file with ``KafkaClient`` section containing all principals along with
its login module and options; configured via ``-Djava.security.auth.login.config``.

Refer to :ref:`Kafka Security<kafka_security>` for more details.

Configuration
-------------

``confluent.rest.auth.propagate.method``
  The mechanism used to authenticate REST Proxy requests. When broker security is enabled, the
  principal from this authentication mechanism is propagated to Kafka broker requests.

  * Type: string
  * Default: "SSL"
  * Importance: low

``confluent.license``
  Confluent will issue a license key to each subscriber. The license key will be a short snippet of text that you can copy and paste. Without the license key, you can use Confluent Security Plugins for a 30-day trial period. If you are a subscriber and don't have a license key, please contact Confluent Support at support@confluent.io.

  * Type: string
  * Default: ""
  * Importance: high