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.
Setting Up Client Certificates
To access MQTT using mTLS with Connectware, the following steps are required:
Prepare Connectware for mTLS by configuring the necessary settings.
Create Certificate Signing Requests (CSR) and obtain signed client certificates using a custom CA certificate chain.
Create a Connectware user with role-based permissions and assign the appropriate permissions to the client.
Learn More About
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.
Enabling mTLS in Connectware (Kubernetes)
To configure Connectware for certificate-based authentication:
Open the
values.yaml
file.Set the
global.authentication.mTLS.enabled
Helm value totrue
.
global:
authentication:
mTLS:
# Enable mTLS authentication
enabled: true
After configuring your
values.yaml
file, deploy or update Connectware by running the following Helm command:
helm upgrade --install connectware <repository>/connectware -f values.yaml
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:
Generate a private key for your device:
openssl genrsa -out anymachine-key.pem 2048
Download the
openssl-client-cert.conf
sample file from GitHub.Open the
openssl-client-cert.conf
file and modify the following settings:
COMMON_NAME = device001
ORGNAME = Smart Factory Inc.
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
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.
Create a CSR for the device that you want to connect to Connectware.
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
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.
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
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:
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.
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" ]
}'
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.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
Verifying the mTLS Configuration
Verifying the mTLS Configuration (Kubernetes)
To confirm that mTLS is configured correctly for Connectware, do the following:
In the Admin UI, select User > User Management, and select the admin user.
In the Edit User dialog, enable Advanced Mode.
Enable Certificate and click Update.
Download the certificate files from the Connectware pod using kubectl. The following commands will extract the
cybus_ca.crt
,cybus_client.crt
, andcybus_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
Use the
cybus_client
key pair withCN=admin
.Connect to an MQTT client on port 8883 using the CA file (
cybus_ca.crt
) and thecybus_client
key pair.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.
Last updated
Was this helpful?