/docs/engineer/tls-certificates

Understand and configure MQTT TLS certificates

Choose the right TLS trust path, configure Mqttable, and verify a secure MQTTS, WSS, or QUIC connection.

Author:: Mqttable
Updated:: Aug 24, 2026

On this page6 sections

Most public and managed Brokers use a server certificate issued by a public CA. Start with System CA and upload nothing unless the Broker operator explicitly gives you a private CA or requires mTLS.

You are done when Verify server identity remains enabled, Test Connection returns Connection OK, the created Connection reaches Connected, and an authorized message round trip succeeds.

Choose your TLS path

Use the material supplied by the Broker operator, cloud console, or your administrator. Do not guess from filenames and do not generate an arbitrary client certificate: the Broker cannot authenticate a certificate it does not trust.

Hostname and TLS port: Keep server verification enabled, select System CA, and leave mTLS off. Usually no certificate file is needed.
A ca.crt, ca.pem, or CA bundle: Select Custom CA and put the supplied trust material in CA Certificate.
An mTLS requirement plus a client certificate and key: Choose System CA or Custom CA for the server, enable mTLS, and configure both Client Certificate and Private Key.
Only a username, password, or token: This is MQTT Authentication, not a client certificate. Configure it when creating the MQTT Connection.

Never request or upload server.key. The server private key stays on the Broker.

Configure System CA

This is the default path for public and managed Brokers.

Open Connections → New Broker and choose mqtts, wss, or quic.
Enter the Host and Port supplied by the operator. WSS also requires the WebSocket Path.
Keep Verify server identity enabled.
Set Server Certificate Trust to System CA.
Leave Client Authentication (mTLS) off.
Keep SNI on Auto and ALPN empty unless the operator provides exact values.

Mqttable New Broker form using mqtts, server identity verification, and System CA with client authentication disabled — Public-CA endpoints usually need no uploaded file; System CA verifies the Broker certificate.
Protocol, Host, and Port must identify the same secure listener.
Keep server identity verification enabled.
Select System CA for a public-CA Broker.

Configure Custom CA or mTLS

Only use these paths when the Broker operator explicitly supplies the required material.

Private CA or self-signed Broker

Ask for the CA Certificate or CA bundle that clients must trust. If you receive only server.crt, confirm that the operator intends clients to trust that self-signed certificate.
Set Server Certificate Trust to Custom CA.
Under CA Certificate, choose Upload, Paste clipboard, or a protected Saved reference.
Leave mTLS off unless the Broker also requires a client certificate.

Broker that requires mTLS

Choose System CA or Custom CA for server verification.
Enable Client Authentication (mTLS).
Configure the supplied Client Certificate and matching Private Key separately.
Confirm that the Broker trusts the client certificate issuer. A normal username/password connection does not require mTLS.

Mqttable New Broker form showing custom CA, client certificate, and private key inputs — mTLS adds a client certificate and private key to normal server verification; put each item in its matching field.
Custom CA verifies the Broker server certificate.
Client Certificate is the client identity the Broker verifies.
Private Key must match the client certificate and remain secret.

Test and verify

Select Test Connection in the Broker form.
Expect a green Connection OK for each accepted MQTT version. This proves that the current endpoint and TLS settings completed the handshake.
Select Create, then create an MQTT Connection. Configure MQTT Authentication such as a username, password, JWT, or SCRAM separately.
Connect and wait for Connected.
Follow the first MQTT message tutorial to verify one non-sensitive subscribe, publish, and Trace round trip.

Mqttable New Broker form showing successful MQTT 5 and MQTT 3.1.1 TLS connection tests — Connection OK confirms that the endpoint and current TLS settings completed the test handshake.
Test the exact secure Host and Port before creating the Broker.
Each accepted MQTT version reports Connection OK independently.

Do not fix a certificate error by disabling server verification. Keep it enabled for every production or public-network connection.

Troubleshoot by error

Unknown CA / unable to get local issuer: Check whether System CA or Custom CA is correct and whether the CA bundle is complete.
Hostname mismatch: Check whether Host appears in the server certificate SAN. Do not disable verification.
Certificate expired / not yet valid: Check the certificate dates and the computer clock.
Missing Client Certificate or Private Key: Check whether mTLS was enabled by mistake. A required mTLS connection needs both materials.
Certificate and key do not match: Check whether the client certificate and key came from the same issuance.
Unsupported or encrypted private key: Use a separate supported, unencrypted Private Key instead of .p12 or .pfx.
Connection refused / timeout: Check Host, Port, listener, DNS, firewall, and network. This usually happens before certificate validation.
Not authorized after TLS succeeds: Check the Connection username/password, client-certificate authorization, or Topic ACL. Do not keep changing the CA.

Change one item at a time and retest. This separates network, TLS handshake, MQTT Authentication, and Topic Authorization failures.

Certificate and file reference

Open certificate roles, supported files, and source references

Mqttable always verifies the Broker certificate. The Broker verifies a Mqttable client certificate only when mTLS is enabled.

Certificate relationship diagram with a CA above, a Broker sending its server certificate to Mqttable, a client certificate returning only for mTLS, and private keys staying local — Mqttable is on the left; the MQTT Broker is on the right.
1The CA is the issuer and trust source for both certificates.
2
The Broker sends its Server Certificate; Mqttable verifies it.
3
Mqttable sends a Client Certificate only when mTLS is required.
4The Client Private Key always stays with Mqttable.
5The Server Key always stays with the Broker.

Supported files and limits

CA and client certificates: .pem, .crt, and .der.
Client private keys: .pem, .key, and .der.
Maximum size: 5 MB for each material.
Input: Upload, pasted PEM, or a protected Saved reference.

Mqttable does not import .p12 or .pfx directly and does not accept an encrypted Private Key. Ask the administrator for separate supported certificate files and an unencrypted key. Never send a private key to a third party just to convert it.

Before uploading, confirm that:

Host uses a name covered by the certificate; an IP connection requires that exact IP in the certificate.
The current time is within the certificate validity period.
Custom CA contains the operator-specified CA or complete CA bundle.
Client Certificate and Private Key match each other.
SNI and ALPN stay at their defaults unless specified otherwise.

Sources and scope

This page does not teach production certificate issuance or Broker-side deployment. For saved material, passwords, and rotation, continue to Manage credentials, TLS, and authentication safely.