Configuring an Event Broker Service to use Client Certificate Authentication

The tutorial provides an example of how to configure client certificate authentication, from generating the certificates to using the PubSub+ Cloud Console to upload the certificate. For more detailed information, see Managing Domain and Client Certificate Authorities.

The tutorial uses the widely available OpenSSL tools to create an internal certificate authority that you can use to sign client certificates. It also uses the MQTT.fx tool to demonstrate connecting an MQTT client using the client certificate. The MQTT.fx tool is open source and can be downloaded here. Packages are available for Linux, Windows, and Mac.

The tasks in this tutorial include:

Before You Begin

Before starting this tutorial make sure you have:

  • An event broker service of the Enterprise service type. For information about selecting your event broker service version, see Selecting the Broker Release and Version.
  • OpenSSL tools installed
  • MQTT.fx tool installed

Create an Internal Certificate Authority

Certificates signed by a public certificate authority (CA) are expensive and are necessary only if you want to allow clients from the public to connect to your event broker service. Typically, this is not the case, so an internal CA is suitable. An internal CA is also potentially more secure because your organization controls the entire certificate issuing process.

To create your own internal CA, you can use OpenSSL, which is included with most Linux-based operating systems. You can install it on most operating systems if it is not already available. For details on installing OpenSSL, see the OpenSSL Wiki.

All you need to do to create your own CA is generate a private key to sign client certificates and a CA certificate that you can distribute to validate that your CA is the signer. To create an internal CA:

  • Use Open SSL to generate a private key and a public certificate for the CA. The command below generates two files, one for the private key and one for the public certificate. The certificate common name will be *.messaging.solace.cloud, as specified as part of the -subj parameter in the command line. If you prefer to enter the common name and the other values interactively, omit the -subj parameter. 
    openssl req -newkey rsa:2048 -nodes -keyout MyRootCaKey.key -x509 -days 365 -out MyRootCaCert.pem -subj "/C=GB/ST=London/L=London/O=Global Security/OU=IT Department/CN=*.messaging.solace.cloud"

Make sure you store the private key file (MyRootCaKey.key) in a safe place. The certificate can be made public. You will upload it to the event broker service later.

Create a Client Certificate

After you create your internal CA key and certificate files, follow these steps to create a client certificate and have the CA sign it.

  1. Use Open SSL to create a private key for the client. The client application needs the private key file (client1.key) to connect to the event broker service. Keep this file secure. 
    openssl genrsa -out client1.key 2048
  2. Create a certificate signing request (CSR) for the client certificate. The common name for the client certficate is client1.messaging.solace.cloud. The common name is important because it identifies the client. As before, you can omit the -subj parameter to add the common name interactively. 
    openssl req -new -key client1.key -out MyClient1.csr -subj "/C=GB/ST=London/L=London/O=Global Security/OU=IT Department/CN=client1.messaging.solace.cloud"
  3. Sign the client certificate using your internal CA private key and certificate that you already created. The new client certificate is valid for one year. 
    openssl x509 -req -in MyClient1.csr -CA MyRootCaCert.pem -CAkey MyRootCaKey.key -CAcreateserial -out clientCert1.pem -days 365 -sha256

    The following files, created during this step, need to be accessible by the client:

    • client1.key—This is the private key for the client. Keep this file safe.
    • clientCert1.pem—This is the client certificate that has been signed by your internal CA. It authenticates the client with the event broker service.

Enable Client Certificate Authentication

Now that we have an Internal CA and a signed certificate for the client, we can enable client certificate authentication for our event broker service. By default, the event broker service has basic authentication enabled, which allows authentication using a username and password. We will leave this enabled so that the existing usernames and passwords for your service will still work.

You can only configure client certificate authentication for Developer service types in an Enterprise account.

To enable client certificate authentication, follow the steps below.

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging into the PubSub+ Cloud Console.

  2. On the navigation bar, select Cluster Manager , and then click the card of the event broker service you want to configure.
  3. On the Service Details page, select the Manage tab.
  4. Click the Authentication tile.

  5. Click the Client Certificate Authentication toggle to turn on certificate-based authentication.
  6. Click the Validate Certificate Dates toggle to require event broker services to check the expiry dates of certificates.

    Screenshot showing the settings described in the surrounding text.

  7. Click Save.

Upload a Certificate for an Internal CA

Now that we have enabled client certificate authentication, we need to make sure that client certificates signed by our internal CA are trusted by the event broker service. To do that, we need upload the certificate for our internal CA to the list of CAs trusted by our event broker service.

You can only configure client certificate authentication for Developer service types in an Enterprise account.

To upload a certificate for a trusted CA, perform the following steps:

  1. In Cluster Manager, click the card of the event broker service you want to configure.
  2. Select the Manage tab and then click Certificate Authorities.
    Screenshot highlighting the Certificate Authorities tile.

  3. On the Client Certificates tab , click Add Client Certificate Authority to upload a new CA certificate.

  4. In the Add Client Certificate Authority dialog, enter a name for the client certificate CA. The name can't contain spaces or special characters.

    Screenshot showing the settings described in the surrounding text.

  5. Open the public certificate (MyRootCaCert.pem) for the internal CA that you created in a text editor. The public certificate was create in Create an Internal Certificate Authority.
  6. Copy all of the text in the certificate file, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

  7. Paste the certificate text into the Certificate Content text box.
  8. Click Save. After the certificate has been uploaded, click OK in the confirmation dialog.

For more information about adding and managing CA certificates, see Managing Certificates in the Cloud Console.

Add the Client Username from a Client Certificate

Now that our internal CA has been added as a trusted certificate authority, the event broker service will trust the client certificate we created. The client certificate validates the identity of the client, which is represented by the common name in the client certificate (client1.messaging.solace.cloud). We must also configure access control for the event broker service to allow the client with this certificate to access the service. To do this, we must add a username for the client that matches the common name in our client certificate.

To add a client username, perform the following steps:

  1. On the navigation bar, select Cluster Manager, and then select your event broker service.
  2. Click Open PubSub+ Broker Manager.
  3. In the new browser tab, click Access Control in the navigation bar and select the Client Username tab.

    Screenshot showing the settings described in the surrounding text

  4. Click the + Client Username button.
  5. Enter the common name from the client certificate, client1.messaging.solace.cloud, and click Create.

    Screenshot showing the settings described in the surrounding text.

  6. Click the Enable toggle and then click Apply. The client username is added and enabled.

    Screenshot showing the settings described in the surrounding text

Connect an MQTT Client to an Event Broker Service

The event broker service is now configured to authenticate a client using a client certificate. If you want to authenticate an MQTT client, you need to gather some connection details from the event broker service. We need to know the host name and secure MQTT port for our service. We also need the certificate for the public CA used by the event broker service so that the client can validate our server certificate.

Note: The certificate for the public CA is not needed in all cases. The CA certificate used to sign the server certificate is highly trusted and installed in most default trust stores. However, not all clients have access to a default trust store, especially IoT client which may be running in a minimally configured environment. The MQTT.fx tool that we will use in the next step requires that we specify the root CA certificate when using client certificates. If we were not using client certificates, the MQTT.fx tool would trust our server certificate (using the CA signed server certificate setting).

To gather connection information for an MQTT client:

  1. From the service details page, click the Connect tab.
  2. Click the MQTT tile to expand it.

  3. In the Connections Details column, record the value for the Secured MQTT Host. This includes the host name and port for the secure MQTT connection in URL format.

  4. At the top of the page, click the Solace Messaging tile to expand it.
  5. Right-click the Download PEM link and save the file. Note the location of this file. This is the certificate for the public CA.

Connect an MQTT Client using the Client Certificate

The event broker service is configured to authenticate a client using the client certificate we created in step 2. We will now using the MQTT.fx tool to connect an MQTT client to our service using a client certificate. If you haven't already, you can download it from MQTT.fx.

To connect an MQTT client, do the following:

  1. Start the MQTT.fx tool.
  2. Click the settings icon in the top bar, near the middle.

  3. In the MQTT Broker Profile Settings section, enter the host value from the connection details in the Broker Address and the port value in the Broker Port (typically 8883). Click the Generate button to generate a random client ID.

  4. Click the SSL/TLS tab underneath the MQTT Broker Profile Settings section. Click on Enable SSL/TLS, then click the Self signed certificates radio button.

  5. In the CA File field enter the path to the public CA certificate you downloaded in the previous step. In the Client Certificate File field, enter the path to the client certificate you created in step 2. In the Client Key File field, enter the path to the client key you created in step 2. Select the PEM Formatted checkbox since all files are in PEM format.

  6. Click on OK.
  7. Click the Connect button in top bar beside the settings icon to connect the MQTT client to the event broker service using the client certificate.

  8. When the client is successfully connected, the circular indicator in the top right turns green. Since the client is encrypted, a padlock icon also appears.

  9. You can use the MQTT.fx tool to publish and subscribe using the MQTT connection.

Next Steps

Congratulations! You've done a lot in this tutorial. You created an internal CA, generated a client certificate, configured your event broker service to authenticate using that client certificate, and connected an MQTT client with mutual (two-way) authentication. Still want to learn more?