How to configure ESE to use Certificates Authentication

Owned by Sheetal Shet, created
Last updated: Sept 23, 2024
8 min read

This article explains how to configure HiveMQ. Enterprise Security Extension to use X509 certificates for authentication. For example, the Client certificates include a subject common name that is used for authentication and role-based permissions for authorization.

Pre-requisites

  1. Created Key-store and trust-stores certificates with subject common name configured. You can always refer to our documentation to know how to generate these certificates.

  2. Running setup of database realm (here we are using PostgreSQL)

 Instructions

  1. The first step is to configure <tls-tcp-listener> in your hivemq config.xml. Please refer following example.

    <hivemq> <listeners> <tls-tcp-listener> <port>8883</port> <bind-address>0.0.0.0</bind-address> <tls> <keystore> <path>/path/to/hivemq.jks</path> <password><your passsword></password> <private-key-password><your passsword></private-key-password> </keystore> <truststore> <path>/path/to/hivemq-trust-store.jks</path> <password><your passsword></password> </truststore> <client-authentication-mode>REQUIRED</client-authentication-mode> </tls> </tls-tcp-listener> </listeners>

  2. Next step, make sure you have the database setup ready with the users, roles and permissions data.

    1. Make sure you have users.username matching the client’s certificate's common name in order to work authentication successfully. For authorization, roles and permissions are configured correctly.

    2. Please check our documentation for database schema and how to use a helper tool to insert data.

  3. Now configure ESE configuration file, i.e enterprise-security-extension.xml

    1. First configure the realm with your database type, name, host, password, db-username and db-password. For more details about different realms please check our documentation. Please refer to the following example of Postgres

      <realms> <!-- a postgresql db--> <sql-realm> <name>postgres-backend</name> <enabled>true</enabled> <configuration> <db-type>POSTGRES</db-type> <db-name>hivemq-db</db-name> <db-host>localhost</db-host> <db-port>5432</db-port> <db-username>postgres</db-username> <db-password>hivemq</db-password> </configuration> </sql-realm> </realms>

    2. Configure <pipelines> in order to authenticate and authorize the client before the client connection is accepted. You can also add preprocessors to do some modifications or processing to inputs before authentication and authorization happens.

      1. In the current scenario will be using <x509-preprocessor> to process and extract subject-common-name and set the ESE variable authentication-key for authentication.

        <x509-preprocessor prefix="{{" postfix="}}"> <x509-extractions> <x509-extraction> <x509-field>subject-common-name</x509-field> <ese-variable>authentication-key</ese-variable> </x509-extraction> </x509-extractions> </x509-preprocessor>

      2. you can also add a logging preprocessor to debug the state of ESE variables. Please remember to add a logger in your logback.xml to see these log messages.
        Example to add <logging-preprocessor>:

        Example to add logger in logback.xml:

      3. With the help of plain-preprocessor, set the authentication-byte-secret ESE variable from mqtt-password.

    3. Once pipelines with the help of preprocessor are configured, the Next step is to configure authentication managers i.e <sql-authentication-manager>. An authentication manager is defined in a pipeline and handles the authentication processes of connecting MQTT clients by using the content of the authentication variables. Configure the realm name (this was set in step 3-a.)
      Example:

    4. In the ESE, authorization is done by authorization managers. An authorization manager is defined in a pipeline and handles the authorization processes of connecting MQTT clients by using the content of the authorization variables. Configure the realm name (this was set in step 3-a.), <use-authorization-key> and <use-authorization-role-key>. Here we are using role-based permissions hence set <use-authorization-role-key> to true and use-authorization-key to false;
      Example:

       

    5. after configuring all the above steps final enterprise-security-extension.xml will be as

    6. Run HiveMQ broker and look for the log messages which mention that HiveMq Broker and ESE is started successfully.

    7. You can quickly test your configurations with MQTT CLI.
      Subscribe to the authorised topic:

      Publish message to the authorised topic:

       

    8. You can also check access.log and hivemq.log to see the log entries

 Related articles