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 SAP 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 in 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 internal 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. You can make the certificate 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.

This procedure explains how to configure a client certificate using a common name (CN). You can configure the event broker service to use a Microsoft universal principal name (msUPN) from the otherName field of the SAN extension if the client certificate has one. Event broker services only support using msUPNs from the SAN extension. They do not support other SAN, including email addresses, DNS names, or UP addresses. See Subject Alternative Name in the x509v3_config documentation on the OpenSSL website for more information.

  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

After creating an internal CA and signed certificate for the client, you can enable client certificate authentication for your event broker service. By default, the event broker service has basic authentication enabled, which allows authentication using a username and password. For this procedure, you will basic authentication enabled so that the existing usernames and passwords for your service still work.

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

To enable client certificate authentication, follow the steps below.

  1. Log in to the Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your SAP BTP region. For more information, see Logging In to the 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 the Username Source list and select the type of username for authentication. Selecting Common Name uses the Common Name (CN) in the Subject field of your client certificate. If you select Subject Alternative Name (SAN), the Microsoft universal principal name (msUPN) inside the SAN section of your client certificate is used. The msUPN is typically found in the otherName field of the SAN (the event broker service does not support other SAN identities, such as email addresses, IP addresses, or DNS names).
  8. (Optional) Click Allow API Provided Username to allow authentication using API provided usernames. This overrides the username provided in Username Source with the one provided by an API. SAP recommends against using client-provided user names, as they are less secure than those in the Username Source. It can allow an authenticated user to assume any client username rather than restricting that user to a particular client username.
  9. 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 Broker 100 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

For a client to authenticate when connecting with an event broker service, it must provide a valid client username. By default, the event broker service uses the first Common Name (CN) from the Subject Name field of the certificate as the client username. In the case of the certificate you created at the start of this procedure, that is client1.messaging.solace.cloud. You can configure the event broker service to use a different source for the username, including:

  • A universal principal name (UPN) from the subject alternative name (SAN) otherName field if the certificate has a SAN extension.
  • An API provided usernames.

Consider the following details when adding client usernames:

  • Client certificate SAN extensions must carry a UPN using the otherName field. Other identities, including email address, DNS name, or IP address, are not supported.

  • If multiple SAN extensions with UPNs exist, the first is used.

  • If you enable the Allow API Provided Username toggle, usernames provided by APIs take precedence over those in the SAN extension.

  • If you leave Allow API Provided Username toggle disabled, and are using subject alternative names to authenticate, clients connecting with certificates without SAN extension fail authentication.

To add a client username

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

    Screenshot showing the settings described in the surrounding text

  4. Click + Client Username.
  5. Enter a username from the client certificate and click Create. The username can be the CN or a UPN from the SAN extension. For example, the common name from the certificate you created earlier was client1.messaging.solace.cloud.

    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 View by drop down and select Protocol.
  3. Click the MQTT tile to expand it.

  4. Click the tile for the language your client application is written in. For example, we have selected Java. Under Connections Details, record the value for the Secured MQTT URI. This includes the host name and port for the secure MQTT connection in URL format.

  5. At the top of the page, click the Solace Messaging tile to expand it and click the tile for the language your client application is written in.
  6. 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?