EMQX Cloud

English

简体中文
日本語

English

简体中文
日本語

Appearance

Contact Us
Contact Us

Configure TLS/SSL in BYOC Plan ​

To protect the confidentiality of data transmission within your MQTT ecosystem, the EMQX BYOC Plan supports establishing secure and encrypted communication channels using SSL and TLS encryption protocols. This page introduces how to enable TSL/SSL communication in both one-way and two-way authentication modes to ensure secure communication within the MQTT system..

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 AuthenticationNoRequiredOptionalRequiredNot required
Two-way AuthenticationNoRequiredOptionalRequiredRequired

One-Way Authentication Mode ​

One-way authentication ensures that the server (EMQX MQTT broker) presents a valid certificate to clients (devices or applications) during the TLS/SSL handshake. Clients verify the authenticity of the server by checking the presented certificate against a trusted Certificate Authority (CA).

In the BYOC plan, only certificates signed by a trusted CA are accepted. This enhances security and prevents unauthorized access to your MQTT clusters.

Required Certificate Components ​

To configure TLS/SSL for your BYOC deployment, prepare a PEM-encoded server certificate file and the corresponding private key file. The server certificate file can contain the following certificate components:

  1. Server Certificate: Issued by a trusted Certificate Authority (CA), this certificate enables the EMQX MQTT broker to establish secure connections with clients.

  2. Certificate Chain: If the server certificate was issued through an intermediate CA, include the intermediate certificates so clients can verify the server certificate. The root certificate is optional.

Prepare the Private Key that corresponds to the server certificate as a separate PEM file.

Certificate Requirements for Console Configuration and Updates ​

When you create or update a BYOC TLS/SSL configuration in the EMQX Cloud Console, EMQX Cloud validates the submitted certificate input as follows:

  • 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.
  • Provide a passwordless PEM private key in PKCS#1 or PKCS#8 format. The private key must match the server certificate.

For two-way TLS, provide one or more trusted client CA certificates in PEM format. EMQX Cloud validates 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.

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

Use PEM File in "byoc create" Command ​

During initial deployment, the BYOC Toolkit validates the files provided through --sslCertPath, --sslKeyPath, and, when used, --clientCaPath. This validation is separate from the Console validation described above.

Before running ./byoc create, copy the server certificate, private key, and optional client CA certificate files to your Ubuntu environment. Use --sslCertPath, --sslKeyPath, and, when needed, --clientCaPath to specify their absolute paths. For more information, see Run Deployment.

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.

      • Select the CA-signed server certificate as needed. Two-way TLS also needs to fill in the client certificate file and client key file.

  2. Click Connect.

mqttx_tls

Update Certificate ​

When a certificate is about to expire or needs to be replaced, you can update the existing TLS/SSL certificate on the deployment overview page.

  1. Login to the EMQX Cloud Console.

  2. On the deployment details page, locate the certificate to update in the TLS/SSL Config section and click the edit icon in the Actions column.

  3. In the TLS/SSL Config dialog, fill in the new certificate contents. You can upload a file or paste the content directly:

    • TLS/SSL Type: The certificate type cannot be changed and matches the existing certificate.
    • Certificate and Certificate Chain: Enter the new server certificate content, including the certificate chain.
    • Certificate Private Key: Enter the private key corresponding to the new certificate.
    • Client CA Certificate: For two-way TLS, also enter the client CA certificate.

    The Common Name (CN) in the new server certificate must match the deployment domain. The current validation uses the CN for this check; a matching Subject Alternative Name (SAN) alone is not sufficient.

  4. Click Confirm.

Delete Certificate ​

Note

Deleting a TLS/SSL certificate is only supported in BYOC v4 deployments. BYOC v5 deployments do not support this operation.

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.