All Products
Search

This Product

    ApsaraMQ for MQTT:Manage device certificates

    Document Center

    ApsaraMQ for MQTT:Manage device certificates

    Last Updated:Jul 09, 2026

    ApsaraMQ for MQTT supports client authentication by using device certificates. This topic describes how to issue a device certificate with a CA certificate and manage device certificates in the ApsaraMQ for MQTT console. Management includes querying, activating, inactivating, and deleting certificates.

    Background

    A device certificate is a digital certificate issued by a root CA certificate for use by client devices. When a client connects to the broker, the broker uses the device certificate to authenticate the client. If authentication is successful, the client and broker can communicate securely by using the encryption key in the certificate. If authentication fails, the broker rejects the connection request from the client.

    Important

    This topic applies only to X.509 device certificate management. If you are using unique-certificate-per-device (device unique certificate) authentication — which generates a username and password from an AccessKey ID (AK) and AccessKey Secret (SK) — see Unique-certificate-per-device authentication mode.

    For unique-certificate-per-device scenarios, use the official tool to generate device credentials first, then connect using a client such as MQTTX or MQTT.fx. When connecting, enter the AccessKey ID and AccessKey Secret generated when you created the AK. The AccessKey Secret (SK) is only visible once and must be saved in advance.

    To use device certificate authentication, the CA certificate that issued the device certificate must be registered with the ApsaraMQ for MQTT broker. For more information, see Register a CA certificate.

    When a client authenticates using a device certificate, the broker validates it against the registered CA certificate. If validation is successful, the client is authenticated, and the system automatically registers the device certificate with the broker.

    Limitations

    • Only Platinum Edition instances and Professional Edition instances support device certificate management.

    • You can manage only device certificates that are registered with the ApsaraMQ for MQTT broker.

    • The serial number of a device certificate must be unique.

    Prerequisites

    Issue a device certificate with a CA certificate

    This section uses a self-signed CA certificate as an example to show how to issue a device certificate. For information about how to generate a self-signed CA certificate, see Create a self-signed CA certificate.

    Generate a device certificate

    RSA algorithm certificates

    1. Prepare the configuration files.

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

        Note

        Modify the content in the [dn] section to meet your requirements.

        [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=client-test

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

        authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign

    2. Generate the device certificate private key and Certificate Signing Request (CSR) file.

      • macOS:

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

      • Windows:

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

    3. Generate the device certificate.

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

    ECC algorithm certificates

    1. Prepare the configuration files.

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

        Note

        Modify the content in the [dn] section to meet your requirements.

        [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=client-test

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

        authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign

    2. Generate the private key (client.key) for the device certificate:

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

    3. Generate the CSR file (client.csr) for the device certificate:

      • macOS:

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

      • Windows:

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

    4. Generate the device certificate:

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

    5. Convert the device certificate's private key to the PKCS#8 format:

      openssl pkcs8 -topk8 -nocrypt -in client.key -out client_pkcs8.key
      Important

      When connecting programmatically, set the deviceKyPath parameter to the path of client_pkcs8.key, not client.key.

    Generate a device certificate chain

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

      touch client_chain.crt

    2. Copy the content of the device certificate to the certificate chain file.

      cat client.crt >> client_chain.crt

    3. Append the content of the CA certificate to the certificate chain file.

      cat CA.crt >> client_chain.crt

    Run the cat client_chain.crt command to view the device certificate chain's content.

      Note

      To connect to the broker, generate a certificate chain from the device certificate and its issuing CA certificate.

      Generating a certificate chain concatenates the content of multiple certificates. Place the child certificate first and the parent certificate last.

    Query device certificates

    You can view all device certificates registered with a specific instance, or search for a specific certificate by its serial number.

    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 left-side navigation pane, choose Certificate Management > Device Certificate.

      The Device Certificate page displays all device certificates registered with the broker.

    4. In the search box above the device certificate list, enter the serial number of a device certificate or a CA certificate to find a specific certificate.

      • Entering the serial number of a device certificate returns that certificate.

      • Entering the serial number of a CA certificate returns all device certificates that it issued and are registered with the broker.

    Activate or inactivate a device certificate

    You can change a certificate's status by activating or inactivating it. A certificate is either activated or inactivated. By default, a device certificate is activated upon registration with the broker.

    • If a certificate is activated: To temporarily disable the certificate, inactivate it. Inactivating the certificate makes it unavailable and changes its status to inactivated.

    • If a certificate is inactivated: To restore the certificate, activate it. Activating it changes its status to activated.

    In the device certificate list, find the certificate that you want to manage and in the Actions column, click Inactivate or Activate.

    Delete a device certificate

    Deleting a device certificate removes its registration record from the broker. This action does not delete the actual certificate file.

    After a device certificate is deleted, if a client attempts to authenticate using that certificate and the associated CA certificate is still valid, the broker automatically re-registers the device certificate, and authentication succeeds.

    1. In the device certificate list, find the certificate that you want to delete and in the Actions column, click Delete.

    2. In the confirmation dialog box, click OK.

    FAQ

    Unique-certificate-per-device authentication

    Does ApsaraMQ for MQTT Basic Edition support unique-certificate-per-device authentication?

    Yes. Basic Edition instances support unique-certificate-per-device authentication. This mode uses the AccessKey ID and AccessKey Secret to generate the username and password for client authentication.

    Is DeviceAccessKey the same as an Alibaba Cloud primary account's AccessKey? Can multiple devices share the same DeviceAccessKey?

    No. A DeviceAccessKey is an independent credential separately issued for each device. It is not the primary account's AccessKey. Different devices cannot share a DeviceAccessKey. Sharing a DeviceAccessKey may cause authentication conflicts and violates the principle of security isolation.

    What should I do if the Username or Password format is incorrect in unique-certificate-per-device mode, causing a connection failure?

    Check and correct the format of the username and password. Unique-certificate-per-device mode enforces strict format requirements for Username and Password. For the specific format requirements, see Unique-certificate-per-device authentication mode.

    What should I do if the username generated in unique-certificate-per-device mode is too long for my client?

    Consider switching to Token authentication mode. Token mode generates shorter usernames and resolves compatibility issues with clients that do not support long usernames.

    Serverless Edition and custom authentication

    How can MQTT Serverless Edition obtain authentication parameters via OpenAPI?

    Call API operations via OpenAPI Explorer to obtain authentication parameters. For more information, see Unique-certificate-per-device authentication mode.

    What should I do if some Device IDs fail to connect with an "unauthorized" error when using shared credentials?

    Perform the following troubleshooting steps:

    1. Check the instance type. Only Professional Edition or Platinum Edition instances support using shared credentials across multiple devices.

    2. Check the authentication configuration. Ensure you have called the AddCustomAuthIdentity API to correctly generate and add a custom authentication identity.

    3. Verify the connection. Load the generated credentials on the client and perform a connection test.

    4. If the connection still fails, query the connection history for the Client ID in the ApsaraMQ for MQTT console to help identify the root cause.