All Products
Search

This Product

    ApsaraMQ for MQTT:Manage server certificates

    Document Center

    ApsaraMQ for MQTT:Manage server certificates

    Last Updated:Aug 21, 2026

    Server certificates are used by clients to authenticate servers. You must purchase or issue a server certificate and then host it in Alibaba Cloud Certificate Management Service. This topic describes how to generate and use server certificates.

    Server certificate workflow

    image

    Limits

    Only Platinum Edition and Professional Edition instances support the server certificate management feature.

    Prerequisites

    Step 1: Use a CA certificate to issue a server certificate

    You can purchase a server certificate from a trusted CA or use your own CA certificate to issue one. For more information about obtaining a CA certificate, see Self-signed CA certificates.

    RSA algorithm certificate

    1. Create configuration files in the OpenSSL installation path.

      1. Create a file named server.csr.cfg with the following content:

        Note

        Fill in the [dn] section as required.

        [req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn

[dn]
C=CN
ST=ZJ
L=HZ
O=ALI
OU=MQTT
emailAddress=xxx@xxx
CN=mqtt-test.xxx.aliyuncs.com

      2. Create a file named server.crt.cfg with the following content:

        Note

        • You can enter your custom domain name in [alt_names]. If you use a custom domain name, you must create a canonical name (CNAME) record that maps the custom domain name to the domain name provided by the ApsaraMQ for MQTT service.

        • If you do not use a custom domain name, set [alt_names] to the domain name provided by ApsaraMQ for MQTT. For example: DNS.2=mqtt-test.cn-qingdao.aliyuncs.com.

        • To use the same server certificate for different instances in multiple regions, you can use a wildcard character in the domain name. For example: DNS.1=*.mqtt.aliyuncs.com.

        authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=*.mqtt.aliyuncs.com
DNS.2=mqtt-test.cn-qingdao.aliyuncs.com

    2. Run the following command to generate the private key and Certificate Signing Request (CSR) file for the server certificate.

      • Mac:

        openssl req -new -sha256 -nodes -out server.csr -newkey rsa:2048 -keyout server.key -config <(cat server.csr.cfg)

      • Windows:

        openssl req -new -sha256 -nodes -out server.csr -newkey rsa:2048 -keyout server.key -config server.csr.cfg

    3. Run the following command to convert the server certificate's private key to the PKCS#8 format.

      openssl pkcs8 -topk8 -nocrypt -in server.key -out server_pkcs8.key

      The converted private key is named server_pkcs8.key. You can run the cat server_pkcs8.key command to view it. The following is an example:

      Important

      When you perform the operations in Step 2: Host the server certificate, you must upload the server private key that is generated in this step.

      -----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBALaDOET1McZD0hV/
ma1YlSZjim00rVwrdXefqOHXWEqm8/HxZ3iWmKN/jGWW1aAoYFRAg0CNar1eDap4
*****
*****
*****
PLX2WlXAXggKZvpozkig/J6klAN8pVvwM4BPgJDLk+hllM8MowOxlNjoHsI34lAQ
g17SUS1ERIK+
-----END PRIVATE KEY-----

    4. Run the following command to generate the server certificate.

      openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 500 -sha256 -extfile server.crt.cfg

      The generated server certificate is named server.crt.

    5. Run the following command to generate the server certificate chain.

      1. Create an empty certificate chain file named server_chain.crt.

        touch server_chain.crt

      2. Copy the server certificate content to the certificate chain file.

        cat server.crt >> server_chain.crt

      3. Copy the CA certificate content and append it after the server certificate content in the certificate chain file.

        cat CA.crt >> server_chain.crt

      You can run the cat server_chain.crt command to view the server certificate chain. The content of the certificate chain is displayed in the following format:

      Important

      When you perform the operations in Step 2: Host the server certificate, you must upload the server certificate chain that is generated in this step.

      -----BEGIN CERTIFICATE-----
xxx
Server certificate content
xxx
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
xxx
CA certificate content
xxx
-----END CERTIFICATE-----

    ECC algorithm certificate

    1. Create configuration files in the OpenSSL installation path.

      1. Create a file named server.csr.cfg with the following content:

        Note

        Fill in the [dn] section as required.

        [req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn

[dn]
C=CN
ST=ZJ
L=HZ
O=ALI
OU=MQTT
emailAddress=xxx@xxx
CN=mqtt-test.xxx.aliyuncs.com

      2. Create a file named server.crt.cfg with the following content:

        Note

        • You can enter your custom domain name in [alt_names]. If you use a custom domain name, you must create a CNAME record that maps the custom domain name to the domain name provided by the ApsaraMQ for MQTT service.

        • If you do not use a custom domain name, set [alt_names] to the domain name provided by ApsaraMQ for MQTT. For example: DNS.2=mqtt-test.cn-qingdao.aliyuncs.com.

        • To use the same server certificate for different instances in multiple regions, you can use a wildcard character in the domain name. For example: DNS.1=*.mqtt.aliyuncs.com.

        authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=*.mqtt.aliyuncs.com
DNS.2=mqtt-test.cn-qingdao.aliyuncs.com

    2. Generate the private key for the server certificate (server.key)

      openssl ecparam -out server.key -name prime256v1 -genkey

    3. Generate the server.csr file for the server certificate

      • Mac:

        openssl req -new -sha256 -nodes -out server.csr -key server.key -config <(cat server.csr.cfg)

      • Windows:

        openssl req -new -sha256 -nodes -out server.csr -key server.key -config server.csr.cfg

    4. Issue the server certificate from the CA certificate

      openssl x509 -req -in server.csr -CA CA.crt -CAkey CA.key -CAcreateserial -out server.crt -days 500 -sha256 -extfile server.crt.cfg

    5. Run the following command to convert the server certificate's private key to the PKCS#8 format. The converted private key is named server_pkcs8.key.

      openssl pkcs8 -topk8 -nocrypt -in server.key -out server_pkcs8.key
      Important

      When you perform the operations in Step 2: Host the server certificate, you must upload the server private key that is generated in this step.

    6. Run the following command to generate the server certificate chain.

      1. Create an empty certificate chain file named server_chain.crt.

        touch server_chain.crt

      2. Copy the server certificate content to the certificate chain file.

        cat server.crt >> server_chain.crt

      3. Copy the CA certificate content and append it after the server certificate content in the certificate chain file.

        cat CA.crt >> server_chain.crt
      Important

      When you perform the operations in Step 2: Host the server certificate, you must upload the server certificate chain that is generated in this step.

    Step 2: Host the server certificate

    Host the issued server certificate in the Alibaba Cloud Certificate Management Service console. After the certificate is hosted, you can view and enable it in the ApsaraMQ for MQTT console.

    Note

    • Server certificates support the RSA and ECC algorithms.

    • To use a custom domain name, you can add the domain name to the certificate and create a CNAME record that points to the endpoint of the ApsaraMQ for MQTT instance.

    1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

    2. In the top navigation bar, select the region where the instance that you want to manage resides. On the Instances page, click the instance name to go to the Instance Details page.

    3. In the navigation pane on the left, choose Certificates > Server Certificate. Then, in the upper-left corner of the page, click Create Certificate.

      The system automatically redirects you to the SSL Certificate Management page of the Alibaba Cloud Certificate Management Service console.

    4. On the SSL Certificate Management page, click Upload Certificate. In the Upload Certificate panel that appears, specify the parameters and click OK.

      • Certificate Standard: Select International Standard.

      • Certificate File: Upload the server certificate chain file server_chain.crt that you generated in Step 1: Use a CA certificate to issue a server certificate, or paste the content of the certificate chain into the text box.

      • Certificate Private Key: Upload the converted private key file server_pkcs8.key that you generated in Step 1: Use a CA certificate to issue a server certificate, or paste the content of the private key into the text box.

      • Certificate Chain: Do not upload a certificate chain file or enter the content of a certificate chain for this parameter. Otherwise, certificate authentication will fail.

    Step 3: Use the server certificate to start the service

    Warning

    When you use a server certificate to start the service, clients will be disconnected during the process. Proceed with caution.

    An incorrect certificate will cause the service to be temporarily unavailable.

    1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

    2. In the top navigation bar, select the region where the instance that you want to manage resides. On the Instances page, click the instance name to go to the Instance Details page.

    3. In the navigation pane on the left, choose Certificates > Server Certificate.

    4. Click Mutual Authentication. In the dialog box that appears, select the server certificate. Then, in the Actions column, click Enable Service.

      • Starting the service restarts the ApsaraMQ for MQTT instance. The restart takes about 5 to 10 minutes. After the restart, clients can use the server certificate for server-side authentication.

      • After the service starts, mutual authentication is enabled on port 8883, and one-way authentication is disabled.

    5. In the dialog box that appears, carefully read the message and click OK.

    Note

    If you want to revert to one-way authentication, click One-way Authentication. In the dialog box that appears, click OK and wait for the server to restart.