.. _rbac-mds-config:

Configure |mds-long|
====================

The |mds-long| acts as the central authority for all authorization and authentication 
data. Each |ak| broker in the MDS cluster must be configured with MDS.

.. important:: The MDS cluster and |ak| cluster can be separate clusters or the same cluster.

.. _mds-config-prereqs:

Prerequisites
-------------

- Self-managed |cp| for your environment must be `downloaded <https://www.confluent.io/download/>`_.

- :ref:`Active Directory (LDAP service) must be configured <ldap-auth-mds>`. The
  configurations in this tutorial are based on Active Directory (AD). You must 
  update these configurations to match your LDAP service.
  
- Brokers running MDS must be configured with a separate listener for inter-broker 
  communication. To access this listener, a user must be configured with ACLs for 
  authorization. These users may also be configured as ``super.users`` if required.
  But these users cannot rely on access to resources using role-based or group-based 
  access. The broker user must be configured as a super user or granted access 
  using ACLs as described in :ref:`kafka_authorization`.

- Brokers will accept requests on the inter-listener port before the metadata for RBAC 
  authorization has been initialized. However, requests on other ports are only 
  accepted after the required metadata has been initialized, including any available LDAP 
  metadata. Broker initialization only completes after all relevant metadata has been 
  obtained and cached. When starting multiple brokers in an MDS cluster with a 
  replication factor of 3 (default) for a metadata topic, at least three brokers 
  must also be started simultaneously to enable initialization to complete on 
  the brokers.
  
- |crest| services that integrate with AD/LDAP using MDS, will use the user login 
  name as the user principal for authorization decisions. By default, this is 
  also the principal used by brokers for users authenticating using SASL/GSSAPI 
  (Kerberos). If your broker configuration overrides ``principal.builder.class`` or
  ``sasl.kerberos.principal.to.local.rules`` to create a different principal, 
  the user principal used by brokers may be different from the principal used by 
  other |cp| components. In this case you should configure ACLs and role bindings 
  for your customized principal for broker resources.

.. _create-pem-key-pair:

Create a PEM key pair
---------------------

In this step you create a PEM key pair for use by the token service. This key 
pair is added to your ``server.properties`` file in the next step.

#.  Create the 2048-bit RSA private key This example stores the keys in a folder 
    named ``/tmp/conf/tokenKeypair.pem``.

    ::

        mkdir /tmp/conf && openssl genrsa -out /tmp/conf/tokenKeypair.pem 2048    

#.  Extract public key.

    ::

        openssl rsa -in /tmp/conf/tokenKeypair.pem -outform PEM -pubout -out /tmp/conf/public.pem
        
.. note::
    
    Only use OpenSSL to create the PEM key files. Do not use Keytool; 
    it is not a valid option and will result in an error during startup.        

Configure the |ak| Broker to run MDS
------------------------------------

.. include:: ../../../includes/secret-tip.rst

.. note::
    This configuration example is for a standalone broker. To view an example of  
    a multiple broker (inter-broker) configuration, refer to :ref:`mutual-tls-auth-rbac`. 

#.  Add the following required configuration options to the ``/etc/kafka/server.properties`` 
    file. Any content in brackets (``<>``) must be customized for your environment.

    .. sourcecode:: RST
        :linenos:

        ############################# Confluent Authorizer Settings  #############################
        authorizer.class.name=io.confluent.kafka.security.authorizer.ConfluentServerAuthorizer
        confluent.authorizer.access.rule.providers=ZK_ACL,CONFLUENT 
        super.users=<User:admin;User:mds>

        ############################# Identity Provider Settings(LDAP) #############################
        ldap.group.name.attribute=sAMAccountName
        ldap.group.object.class=group
        ldap.group.member.attribute=member
        ldap.group.member.attribute.pattern=CN=(.*),DC=rbac,DC=confluent,DC=io
        ldap.group.search.base=CN=Users,DC=rbac,DC=confluent,DC=io
        ldap.java.naming.provider.url=ldap://<hostname>:389
        ldap.java.naming.security.authentication=simple
        ldap.java.naming.security.credentials=<password>
        ldap.java.naming.security.principal=<mds-user-DN>
        ldap.user.name.attribute=sAMAccountName
        ldap.user.object.class=user
        ldap.user.search.base=<user-search-base-DN>

        ############################# MDS Server Settings #############################
        confluent.metadata.server.advertised.listeners=http://localhost:8090
        confluent.metadata.server.listeners=http://0.0.0.0:8090
        confluent.metadata.server.authentication.method=BEARER 

        ############################# MDS Token Service Settings #############################
        advertised.listeners=<advertised.listeners>,RBAC://localhost:9092
        confluent.metadata.server.token.key.path=<path-to-token-key-pair.pem>
        listener.name.rbac.oauthbearer.sasl.login.callback.handler.class=io.confluent.kafka.server.plugins.auth.token.TokenBearerServerLoginCallbackHandler
        listener.name.rbac.oauthbearer.sasl.server.callback.handler.class=io.confluent.kafka.server.plugins.auth.token.TokenBearerValidatorCallbackHandler
        listener.name.rbac.oauthbearer.sasl.jaas.config= \
            org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
            publicKeyPath="<path-to-public.pem>";
        listener.name.rbac.sasl.enabled.mechanisms=OAUTHBEARER
        #### Configure SASL_SSL if SSL encryption is enabled, otherwise configure SASL_PLAINTEXT#####
        listener.security.protocol.map=<advertised.listeners>,RBAC:SASL_PLAINTEXT
        listeners=<listeners>,RBAC://:9092        

    .. important::
    
       Do not use token services (``listener.name.rbac.sasl.enabled.mechanisms=OAUTHBEARER``) 
       for client communication. With RBAC enabled, token services are intended for internal 
       communication between |cp| components only, and not for long-running service 
       principals or client authentication.  The ``OAUTHBEARER`` setting is for  
       internal use and subject to change, and does not implement a full-featured 
       OAUTH protocol. Therefore, use Kerberos authentication 
       for long-lived or client use cases.
       
    
    For a description of the parameters, see:

    - **Lines 2-4:** Enables RBAC. For more information, see :ref:`confluent_server_authorizer_configuration`.
    - **Lines 7-18:** Configures LDAP so that RBAC can use it. For more information, see
      :ref:`ldap-auth-config`, :ref:`ldap-auth-mds`, and :ref:`kafka_ldap_authorizer_config`.
    - **Lines 21-23:** Defines listeners and configures HTTPS for MDS. For more information, see :ref:`rbac-configuration`.
    - **Lines 26-36:** Enables MDS to use LDAP; configures MDS to generate JWT Bearer tokens; and configures MDS to talk
      to other instances of itself. For more information, see :ref:`rbac-configuration`.

#.  :ref:`Start Confluent Platform <installation>`.

.. _troubleshoot-token-authentication:

Troubleshooting token authentication 
------------------------------------

Token login and authentication to MDS using OAUTHBEARER can fail without obvious 
known exceptions or errors appearing in either ``server.log`` or ``metadata-service.log``. 
Such failures may be due to either the public and private key files being corrupt, 
or because the token was generated using different public and private key files.

To troubleshoot token authentication:

#. Delete both ``tokenKeypair.pem`` and ``public.pem`` from the folders configured 
   in ``server.properties`` and regenerate them. The newly-generated key files will 
   be placed in:
   
   ::
   
      confluent.metadata.server.token.key.path=<path-to-token-key-pair.pem> 
      
#. After regenerating ``tokenKeypair.pem`` and ``public.pem``, restart the broker 
   server where MDS is running.
   
#. On the client machine, delete the local CLI cache (``~/.confluent/config.json``), 
   which cached the token for the super user after the super user logged in. 
   
#. Log in again using the CLI.         

Configure a Kafka cluster to connect to MDS
-------------------------------------------

.. important::

   Do not attempt to run MDS as a standalone service. You must always run MDS as 
   an additional component on either your existing or a separate 
   |ak| cluster. Hence, if your |ak| cluster is separate from the |ak| cluster 
   on which MDS is running, configure your |ak| cluster to use the cluster on 
   which MDS is running.

#.  Add the following MDS configuration to your Kafka properties file 
    (``/etc/kafka/server.properties``). Any content in brackets (``<>``) must be 
    customized for your environment.

    .. sourcecode:: RST
        :linenos:

        ############################# Confluent Authorizer Settings  #############################
        authorizer.class.name=io.confluent.kafka.security.authorizer.ConfluentServerAuthorizer
        confluent.authorizer.access.rule.providers= ZK_ACL,CONFLUENT 

        ############################# Authorizer Settings #############################
        confluent.metadata.bootstrap.servers=<kafka-with-mds-host-1>:<port>,<kafka-with-mds-host-2>:<port>,...
        confluent.metadata.security.protocol=SASL_PLAINTEXT
        confluent.metadata.sasl.mechanism=PLAIN
        confluent.metadata.sasl.jaas.config= \
            sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
            username="<broker-username>" \
            password="<broker-password>";

        ############################# Token-based Listener Settings #############################
        listeners=<listeners>,TOKEN://:9092
        advertised.listeners=<advertised.listeners>,TOKEN://<hostname>:9092
        listener.security.protocol.map=<advertised.listeners>,TOKEN:SASL_PLAINTEXT
        listener.name.token.oauthbearer.sasl.jaas.config= \
            org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required \
            publicKeyPath="<path-to-public.pem>";
        listener.name.token.oauthbearer.sasl.login.callback.handler.class=io.confluent.kafka.server.plugins.auth.token.TokenBearerServerLoginCallbackHandler
        listener.name.token.oauthbearer.sasl.server.callback.handler.class=io.confluent.kafka.server.plugins.auth.token.TokenBearerValidatorCallbackHandler

    For a description of the parameters, see:

    - **Lines 2-3:** Enables RBAC. For more information, see :ref:`rbac-configuration`.
    - **Lines 6-12:** Configures |ak| so that it can talk to the MDS cluster and 
      "consume" the role bindings. In the example above, ``SASL_PLAINTEXT/PLAIN``
      is used, but you should use whatever security mechanism is required by the 
      |ak| broker running MDS. Also, you should specify the port exposed by the 
      other broker. For more information, see :ref:`rbac-configuration`.
    - **Lines 15-22:** Enables listener with the OAUTHBEARER SASL mechanism, 
      which is used for impersonation. For more information, see :ref:`auth-sasl-oauth-broker-config`.

#.  :ref:`Start Confluent Platform <installation>`.

Next steps
----------

* :ref:`rbac-cli-quickstart`
* :ref:`controlcenter_security_rbac`
* :ref:`ksql-rbac`
* :ref:`schemaregistry_rbac`
* :ref:`connect-rbac-index`
* :ref:`rbac-rest-proxy-security`

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

    rbac-configuration
    ldap-auth-mds
    ldap-auth-config
    kerberos-auth-config
    mutual-tls-auth-rbac