Client Certificates

Learn how to secure MQTT connections with client certificates via mTLS.

Mutual Transport Layer Security (mTLS) with client certificates provides enhanced security for MQTT connections to Connectware by eliminating the need for traditional username/password authentication. This approach uses X.509 client certificates for public-key authentication, reducing security risks during the authentication process.

Connectware uses a truststore file (cybus_ca.crt) to determine which Certificate Authorities (CAs) it trusts for mTLS authentication.

Connectware supports TLS up to version 1.2.

Setting Up Client Certificates

To access MQTT using mTLS with Connectware, the following steps are required:

1. Prepare Connectware for mTLS by configuring the necessary settings.

2. Create Certificate Signing Requests (CSR) and obtain signed client certificates using a custom CA certificate chain.

3. Create a Connectware user with role-based permissions and assign the appropriate permissions to the client.

All certificate and key files must be in PEM format.

Learn More About

• Server Certificates

• Using Mutual Transport Layer Security (mTLS) for agents with the connectware-agent Helm chart

• X.509

• OpenSSL PKI

• OpenSSL

1. Enabling mTLS in Connectware

Connectware provides the following authentication methods for the message broker:

• Default authentication: Utilizes username and password credentials. This method is compatible with:

  • Unencrypted connections over port 1883

  • Encrypted connections over port 8883 (TLS)

• Alternative authentication: Certificate-based mutual TLS authentication (mTLS)

Once mTLS is enabled, the following changes take effect:

• All MQTTS connections on port 8883 must present valid client certificates.

• Connectware will extract the certificate's Common Name (CN) for user identification.

• The extracted CN must match an existing Connectware user configured for certificate-based authentication (grant type).

• A connection will only be established if both the certificate is validated and the associated user is successfully authenticated.

You must choose either username/password or certificate-based authentication - they cannot operate simultaneously.

Kubernetes

Enabling mTLS in Connectware (Kubernetes)

To configure Connectware for certificate-based authentication:

1. Open the values.yaml file.

2. Set the global.authentication.mTLS.enabled Helm value to true.

global:
    authentication:
        mTLS:
            # Enable mTLS authentication
            enabled: true

1. After configuring your values.yaml file, deploy or update Connectware by running the following Helm command:

Make sure to adjust the command parameters based on your specific setup:

• Installation name (currently set to connectware)

• Namespace (currently set to cybus)

• Repository name (currently set to cybus/connectware)

• Path and filename of your values file (currently set to values.yaml)

helm upgrade --install connectware <repository>/connectware -f values.yaml

Docker

Enabling mTLS in Connectware (Docker)

To configure Connectware for certificate-based authentication:

1. Navigate to your Connectware installation directory (typically /opt/connectware).

2. Open the .env file.

3. Set the CYBUS_BROKER_USE_MUTUAL_TLS environment variable to yes:

# Broker mutual TLS config
CYBUS_BROKER_USE_MUTUAL_TLS=yes

1. Apply the configuration by restarting Connectware.

2. Generating a Certificate Signing Request (CSR)

We recommend implementing your own Public Key Infrastructure (PKI) to issue and manage client certificates for Connectware authentication.

Prerequisites

• Access to your organization's Certificate Authority (CA) infrastructure

• The ability to sign certificate requests with your CA or Intermediate CA

• Basic understanding of OpenSSL commands

Procedure

To generate the CSR, proceed as follows:

1. Generate a private key for your device:

openssl genrsa -out anymachine-key.pem 2048

1. Download the openssl-client-cert.conf sample file from GitHub.
2. Open the openssl-client-cert.conf file and modify the following settings:

COMMON_NAME = device001
ORGNAME = Smart Factory Inc.

1. Create the CSR using your configuration and key:

openssl req -new \
-config openssl-client-cert.conf \
-key anymachine-key.pem \
-out anymachine.csr

You can also create both the private key and the CSR at the same time via -keyout:

openssl req -new \
-config openssl-client-cert.conf \
-keyout anymachine-key.pem \
-out anymachine.csr

1. Verify your CSR:

openssl req -in anymachine.csr -noout -text -nameopt sep_multiline

The important fields to verify include:

Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C=DE
            O=Smart Factory Inc.
            CN=device001

3. Signing the CSR with Your Custom CA

A manual or automated process for signing certificates with a company Root CA or Intermediate CA is up to the customer.

In this tutorial, we assume the availability of a custom CA key-pair or a corresponding Intermediate CA key-pair eligible to sign certificate requests.

Example: For testing purposes, you can use an example root CA configuration to generate a new self-signed root CA. Download the openssl-root-ca-example.conf sample file from GitHub.

1. Create a CSR for the device that you want to connect to Connectware.

2. Sign the CSR with your custom CA:

openssl x509 -req -in anymachine.csr -days 100 \
-CA custom_ca.crt \
-CAkey custom_ca.key \
-set_serial 01 > anymachine.crt

This produces the signed certificate valid 100 days with the following output:

Signature ok
subject=/C=DE/O=Smart Factory Inc./CN=device001
Getting CA Private Key

1. Inspect the signed certificate to verify its details. The output should confirm that the issuer matches your custom CA and that the subject corresponds to the device or machine identity you provided.

openssl x509 -in anymachine.crt -text -noout

Result: Once properly configured, your custom-signed client certificates will function with Connectware without requiring container restarts.

4. Add a Custom CA to the cybus_ca.crt Truststore

To allow Connectware to authenticate clients using this certificate, the custom CA certificate (or full certificate chain) must be trusted by Connectware.

1. Add your CA chain to the Connectware truststore (cybus_ca.crt). You can retrieve this file from your Connectware instance and then add your custom CA:

cat custom_ca.crt >> cybus_ca.crt

1. To verify the trust chain locally before deploying:

openssl verify -CAfile cybus_ca.crt cybus_client.crt custom_client.crt

Expected output:

cybus_client.crt: OK
custom_client.crt: OK

5. Configuring Certificate-Based Authentication

After generating client certificates, you must configure Connectware to recognize and authorize connections using these certificates:

1. For certificate authentication to work, the Common Name (CN) in your client certificate must exactly match a username in Connectware that has been configured with the certificate grant type.

2. Create a user in Connectware with the same name as the CN in your client certificate:

curl -k --location --request POST 'https://localhost/api/users' \
--header 'Authorization: Bearer eyJzdWI...
--data-raw '{
    "username": "device001",
    "identityProvider": "local",
    "grantTypes": [ { "method": "certificate", "isRequired": false } ],
    "roles": [ "cfb72c04-e4a8-11eb-92a8-0242ac1e0006" ]
}'

1. Assign appropriate access roles to this certificate-authenticated user. For testing, you can use the connectware-admin role. For production environments, follow the principle of least privilege with more restricted roles.

2. To find the correct connectware-admin role ID for your environment, use the following GET request:

https://localhost/api/roles?name[eq]=connectware-admin

Result: Once properly configured, clients connecting via mTLS with a certificate containing CN=device001 will authenticate successfully, provided the certificate was signed by a CA in the trusted cybus_ca.crt chain.

Learn More About

• Adding Individual Permissions to Users

Verifying the mTLS Configuration

Kubernetes

Verifying the mTLS Configuration (Kubernetes)

To confirm that mTLS is configured correctly for Connectware, do the following:

1. In the Admin UI, select User > User Management, and select the admin user.
2. In the Edit User dialog, enable Advanced Mode.

3. Enable Certificate and click Update.

4. Download the certificate files from the Connectware pod using kubectl. The following commands will extract the cybus_ca.crt, cybus_client.crt, and cybus_client.key files from the /connectware_certs directory in the system-control-server pod to your current local directory.

kubectl cp $(kubectl get pod -lapp=system-control-server -o name | sed -e 's/pod\///g'):/connectware_certs/cybus_ca.crt cybus_ca.crt
kubectl cp $(kubectl get pod -lapp=system-control-server -o name | sed -e 's/pod\///g'):/connectware_certs/cybus_client.crt cybus_client.crt
kubectl cp $(kubectl get pod -lapp=system-control-server -o name | sed -e 's/pod\///g'):/connectware_certs/cybus_client.key cybus_client.key

1. Use the cybus_client key pair with CN=admin.

2. Connect to an MQTT client on port 8883 using the CA file (cybus_ca.crt) and the cybus_client key pair.

3. Use an MQTT client like mosquitto_sub to check for successful connection.

mosquitto_sub \
--cert cybus_client.crt \
--key cybus_client.key \
--cafile cybus_ca.crt \
-h localhost -p 8883 -t '#' -d

Docker

Verifying the mTLS Configuration (Docker)

To confirm that mTLS is configured correctly for Connectware, do the following:

1. In the Admin UI, select User > User Management, and select the admin user.
2. In the Edit User dialog, enable Advanced Mode.

3. Enable Certificate and click Update.

4. Download the cybus_client.key and cybus_client.crt files, located in the /connectware_certs Docker volume.

5. To extract the cybus_client.* files, use the extract script, which uses docker cp to copy files from a running container.
6. Use the cybus_client key pair with CN=admin.

7. Connect to an MQTT client on port 8883 using the CA file (cybus_ca.crt) and the cybus_client key pair.

8. Use an MQTT client like mosquitto_sub to check for successful connection.

mosquitto_sub \
--cert cybus_client.crt \
--key cybus_client.key \
--cafile cybus_ca.crt \
-h localhost -p 8883 -t '#' -d

mTLS Example Output

Successful connection

Client mosq-wcdbhQtb5lkGOBMIbi sending CONNECT
Client mosq-wcdbhQtb5lkGOBMIbi received CONNACK (0)
Client mosq-wcdbhQtb5lkGOBMIbi sending SUBSCRIBE (Mid: 1, Topic: #, QoS: 0, Options: 0x00)
Client mosq-wcdbhQtb5lkGOBMIbi received SUBACK
Subscribed (mid: 1): 0

TLS handshake failure

Client mosq-wcdbhQtb5lkGOBMIbi sending CONNECT
OpenSSL Error[0]: error:14094418:SSL routines:ssl3_read_bytes:tlsv1 alert unknown ca
Error: A TLS error occurred.

Backend authorization failure

Client mosq-wcdbhQtb5lkGOBMIbi sending CONNECT
Client mosq-wcdbhQtb5lkGOBMIbi  received CONNACK (5)
Connection error: Connection Refused: not authorised.
Client mosq-wcdbhQtb5lkGOBMIbi  sending DISCONNECT

Revoking Access for Clients with Custom CA Certificates

• To revoke all client certificates issued by a particular custom CA, simply remove the custom CA entries from the cybus_ca.crt file.

This will block further access from any certificate issued by that CA without needing to restart Connectware.