EMQX Cloud

English

简体中文
日本語

English

简体中文
日本語

Appearance

Contact Us
Contact Us

Configure TLS/SSL for Dedicated and Dedicated Flex Deployments ​

Dedicated and Dedicated Flex deployments support custom certificates for one-way and two-way TLS/SSL authentication. This guide explains how to configure TLS/SSL and test client connections.

The following table provides an overview of different certification requirements in one-way and two-way authentication modes.

Certification ModeSelf-signed CertificateServer CertificateCertificate ChainPrivate KeyClient CA Certificate
One-way AuthenticationYesRequiredOptionalRequiredNot required
Two-way AuthenticationYesRequiredOptionalRequiredRequired

Certificate Requirements ​

Server Certificate and Certificate Chain ​

  • Provide X.509 certificates in PEM format. Only whitespace is allowed between certificate blocks.
  • Place the server certificate first, followed by its intermediate certificates in issuing order. A single server certificate is accepted. A chain can contain no more than five certificates.
  • The server certificate must be currently valid and have at least 5 days remaining before expiration.
  • Certificates must pass certificate encoding, signature, and chain validation.

If a CA issued the server certificate through an intermediate CA, include the intermediate certificates so clients can verify the server certificate. The root certificate is optional.

Client CA Certificates ​

For two-way TLS, provide one or more trusted client CA certificates in PEM format. EMQX Cloud validates the encoding and fields of each certificate separately. These certificates do not need to form an ordered chain. Only the server certificate chain is subject to these requirements: no more than five certificates, and at least 5 days of remaining validity for the first certificate.

Private Key ​

Provide a passwordless PEM private key in PKCS#1 or PKCS#8 format. The private key must match the server certificate.

TIP

EMQX Cloud validates certificate input before saving or applying a TLS/SSL configuration. If validation fails, the current certificate and configuration remain unchanged.

Configure One-Way TLS/SSL ​

The following instructions guide you to configure one-way TLS/SSL in EMQX Cloud Console and test the client connection with TLS/SSL configured. You can also watch One-Way TLS/SSL Tutorial for each step of the setup.

  1. Login to the EMQX Cloud Console.
  2. On your deployment Overview page, click the +TLS/SSL Config button to configure the certificate. You can upload the file or fill in the certificate contents directly.
    • TLS/SSL Type: Choose one-way (only the client verifies the server-side certificate).
    • Certificate and Certificate Chain: Custom server-side certificate.(Including certificate chain, which is provided by a third-party organization when issuing the certificate.)
    • Certificate Private Key: Private secret key.
  3. After filling in all the fields, click Confirm. On your deployment overview page, you should see the certificate information in TLS/SSL Config.

Test One-Way TLS with MQTTX Client ​

Before testing, make sure that you have created authentication information, refer to Authentication. You can use MQTTX Client to connect to EMQX Cloud and test the TLS/SSL configuration.

  1. In MQTTX Client, create a new connection.

    In the General section, fill in the information as follows:

    • Name: Type the name of the connection.

    • Client ID: The client ID is randomly generated. You can click the refresh button to regenerate the id.

    • Host: Select the protocol from the drop-down list and fill in the deployed connection address and port.

      • If you use MQTT over TLS, select ports mqtts:// and 8883.
      • If you use WebSocket over TLS, select ports wss:// and 8084.

    • Username and Password: Type the authentication information you have created.

    • SSL/TLS: Click the toggle switch to enable SSL/TLS.

    • SSL Secure: Click the toggle switch to enable SSL Secure.

    • Certificate: Select the certification as needed.

      • If it is a certificate certified by CA authority, click CA signed server.
      • If it is self-signed certificate, click Self signed to provide self-signed server-side CA certificate. For information on how to create self-signed TSL/SSL certificate, see Create Self-Signed TSL/SSL Certificate.

  2. Click Connect.

mqttx_tls

Configure Two-Way TLS/SSL ​

The following instructions guide you to configure two-way TLS/SSL in EMQX Cloud Console and test the client connection with TLS/SSL configured. You can also watch Two-Way TLS/SSL Tutorial for each step of the setup.

  1. Login to the EMQX Cloud Console.
  2. On your deployment Overview page, click the +TLS/SSL Config button to configure the certificate. You can upload the file or fill in the certificate contents directly.
    • TLS/SSL Type: Select two-way (client and server verify each other's certificates).
    • Certificate and Certificate Chain: Custom server-side certificate.(Including certificate chain, which is provided by a third-party organization when issuing the certificate.)
    • Certificate Private Key: Private secret key.
    • Client CA Certificate : When choosing two-way, you need to provide the client CA certificate.
  3. After filling in all the fields, click on Confirm. On your deployment overview page, you should see the certificate information in TLS/SSL Config.

Test Two-Way TLS with MQTTX Client ​

Before testing, make sure that you have created authentication information, refer to Authentication. You can use MQTTX Client to connect to EMQX Cloud and test the TLS/SSL configuration.

  1. In MQTTX Client, create a new connection.

    In the General section, fill in the information as follows:

    • Name: Type the name of the connection.

    • Client ID: The client ID is randomly generated. You can click the refresh button to regenerate the id.

    • Host: Select the protocol from the drop-down list and fill in the deployed connection address and port.

      • If you use MQTT over TLS, select ports mqtts:// and 8883.
      • If you use WebSocket over TLS, select ports wss:// and 8084.

    • Username and Password: Type the authentication information you have created.

    • SSL/TLS: Click the toggle switch to enable SSL/TLS.

    • SSL Secure: Click the toggle switch to enable SSL Secure.

    • Certificate: Select the certification as needed.

      • If it is a server-side CA certified by CA authority, click Self signed and fill in the certificate in CA File field. For information on how to create self-signed TSL/SSL certificate, see Create Self-Signed TSL/SSL Certificate.
      • If it is self-signed server-side certificate, click Self signed to provide self-signed server-side CA certificate.
      • Two-way TLS also needs to fill in the client certificate file and client key file.

  2. Click Connect.

mqttx_tls

Create Self-Signed TSL/SSL Certificate ​

The following instructions guide you to create self-signed TSL/SSL certificates. You can also watch Create a self-signed TLS/SSL certificate tutorial for each step of the setup.

Prerequisite

Make sure you have installed OpenSSL.

Generate Server-Side CA Certificate ​

You can use the following statement to generate a server-side CA certificate. You should adjust subj to actual use.

bash
openssl req \
    -new \
    -newkey rsa:2048 \
    -days 365 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQ Technologies Co., Ltd/CN=EMQ CA" \
    -keyout server-ca.key \
    -out server-ca.crt

Create a Server-Side Certificate ​

  1. Generate server-side secret key server.key.
bash
openssl genrsa -out server.key 2048
  1. Create openssl.cnf file. Replace the IP.1 or DNS.1 address with your deployment address.
cat << EOF > ./openssl.cnf
[policy_match]
countryName             = match
stateOrProvinceName     = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
req_extensions     = req_ext
x509_extensions    = v3_req
prompt             = no

[req_distinguished_name]
commonName          = Server

[req_ext]
subjectAltName = @alt_names

[v3_req]
subjectAltName = @alt_names

[alt_names]
# EMQX deployment connections address
# IP.1 = <IP Connect Address>
DNS.1 = <Domain Connect Address>
EOF
  1. Generate the server-side certificate request file server.csr.
bash
openssl req -new -key server.key -config openssl.cnf -out server.csr
  1. Sign the server-side certificate with a CA certificate server.crt.
bash
openssl x509 -req \
    -days 365 \
    -sha256 \
    -in server.csr \
    -CA server-ca.crt \
    -CAkey server-ca.key \
    -CAcreateserial -out server.crt \
    -extensions v3_req -extfile openssl.cnf
  1. View server-side certificate information.
bash
openssl x509 -noout -text -in server.crt
  1. Verify the certificate.
bash
openssl verify -CAfile server-ca.crt server.crt

Create a Client Certificate ​

For two-way authentication, you need to generate the client CA certificate first.

Generate Client CA Certificate ​

You can use the following statement to generate a client CA certificate. You should adjust subj to actual use.

bash
openssl req \
    -new \
    -newkey rsa:2048 \
    -days 365 \
    -nodes \
    -x509 \
    -subj "/C=CN/O=EMQ Technologies Co., Ltd/CN=EMQ CA" \
    -keyout client-ca.key \
    -out client-ca.crt
  1. Generate client-side secret key client.key.
bash
openssl genrsa -out client.key 2048
  1. Generate the client-side certificate request file client.csr.
bash
openssl req -new -key client.key -out client.csr -subj "/CN=Client"
  1. Sign the client-side certificate with a CA certificate client.crt.
bash
openssl x509 -req -days 365 -sha256 -in client.csr -CA client-ca.crt -CAkey client-ca.key -CAcreateserial -out client.crt
  1. View client-side certificate information.
bash
openssl x509 -noout -text -in client.crt
  1. Verify the certificate.
bash
openssl verify -CAfile client-ca.crt client.crt

Delete Certificate ​

Deleting the certificate will disconnect the client from 8883 and 8084. Make sure that the deletion does not affect your business.

  1. Login to the EMQX Cloud Console.
  2. Click the delete icon for the certificate in the TLS/SSL Config section.
  3. Click OK in the dialog to complete the deletion.

FAQ ​

A Certificate Contains Multiple Certificates ​

Purchased certificates contain intermediate certificates, which open the certificate in text form, and multiple certificates in the order of User Certificate - Intermediate Certificate - Root Certificate. Generally, a certificate contains a user certificate and several intermediate certificates, you need to separate the user certificate from the intermediate certificate and fill in the certificate chain with the intermediate certificate.

bash
-----BEGIN CERTIFICATE-----

User Certificate

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

Intermediate Certificate

-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----

Root Certificate

-----END CERTIFICATE-----

Lack of Certificate Chain ​

Certificate chain completion: https://myssl.com/chain_download.html

Can I Disable Username/Password Authentication When Using Two-Way TLS or Mutual TLS (mTLS)? ​

Yes, you can disable username and password authentication when using mutual TLS (mTLS). However, we strongly recommend keeping both authentication methods enabled for security reasons. If a device certificate is compromised, unauthorized devices could use it to connect to EMQX Cloud.

If you still wish to disable username/password authentication, Dedicated and Dedicated Flex deployments running EMQX v5 or v6 can do this directly in the Console via Ports Management. For other deployment types, please submit a support ticket. Our SRE team can assist you in disabling it for ports 8883 and 8084 in your deployment.

For a complete end-to-end setup guide, see mTLS Best Practices for Device Connection.

Can I Map the Certificate CN to the Username or Client ID? ​

Yes, EMQX Cloud allows you to map the certificate Common Name (CN) to either the username or the client ID. For Dedicated and Dedicated Flex deployments running EMQX 5.10.3 or later, set Use Peer Certificate as Username or Use Peer Certificate as Client ID to cn in MQTT Settings to configure the mapping directly, without submitting a support ticket.

Important Considerations:

  • Mapping CN to the client ID: Ensure that each CN is unique. If multiple clients share the same CN, they will disconnect each other due to client ID conflicts.
  • Mapping CN to the username: This is generally safer, as it prevents connection conflicts while still enabling identity verification.

When Disabling Username/Password Authentication and Map CN to the Username, How to Block a Compromised Certificate from Connecting ? ​

If a certificate is leaked and CN is mapped to the username, you can prevent the compromised device from connecting by adding the corresponding username to the blacklist.

Can One-Way and Mutual TLS Connections be Used Simultanouely? ​

Yes. Each deployment in EMQX can only use a single set of TLS/SSL certificates, but different types of TLS connections can be supported through different listeners. If mutual TLS authentication is already enabled in the deployment, you can also enable an additional one-way TLS port. It's important to note that both the mutual TLS and one-way TLS ports must use the same server certificate to ensure that certificate updates do not cause service interruptions.