全部產品
Search

搜尋本產品

    ApsaraMQ for MQTT：裝置認證管理

    文件中心

    ApsaraMQ for MQTT：裝置認證管理

    更新時間：Jul 10, 2026

    雲Message QueueTT 版支援使用裝置認證進行用戶端的接入認證。本文介紹如何使用CA認證簽發裝置認證，並在雲Message QueueTT 版控制台管理裝置認證，包括查詢認證、啟用或登出認證以及刪除認證。

    背景資訊

    裝置認證是由CA根憑證簽發給用戶端裝置使用的數位憑證，用於用戶端和服務端串連時，服務端對用戶端進行安全認證。認證通過後服務端和用戶端可基於認證內的加密金鑰進行安全通訊，若認證不通過則服務端拒絕用戶端接入。

    說明

    本文檔僅適用於基於 X.509 裝置認證的用戶端認證管理。如果使用的是一機一密（裝置唯一認證、AK/SK 鑒權）模式，即通過 AccessKey ID 和 AccessKey Secret 產生使用者名稱和密碼進行認證，請參見裝置唯一認證鑒權概述。在一機一密情境下，需先使用官方工具產生裝置憑證，再使用 MQTTX 或 MQTT.fx 等用戶端工具串連，串連時需填入建立 AK 時產生的 AccessKey ID 和 AccessKey Secret（AccessKey Secret 僅可見一次，需提前儲存）。

    使用裝置認證認證時，必須保證簽發該裝置認證的CA認證已在雲Message QueueTT 版服務端中註冊。更多資訊，請參見註冊CA認證。

    用戶端裝置使用裝置認證進行接入認證時，服務端會根據登入的CA認證驗證裝置認證是否正確，若CA認證和裝置認證匹配成功，則用戶端認證通過，且系統會將該裝置認證自動註冊到服務端中。

    使用限制

    • 僅鉑金版執行個體和專業版執行個體支援裝置認證管理功能。

    • 雲Message QueueTT 版僅支援對已在服務端註冊的裝置認證進行操作。

    • 裝置認證的SN序號必須唯一。

    前提條件

    使用CA認證簽發裝置認證

    本操作以自簽名CA認證為例簽發裝置認證，自簽名CA認證產生步驟，請參見自簽CA認證。

    產生裝置認證

    RSA演算法認證

    1. 準備設定檔。

      1. 建立一個名稱為client.csr.cfg的檔案，內容如下：

        說明

        [dn]內容需要根據您的實際需求修改。

        [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. 建立一個名稱為client.crt.cfg的檔案，內容如下：

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

    2. 根據配置產生裝置認證私密金鑰和CSR檔案。

      • Mac：

        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. 產生裝置認證。

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

    ECC演算法認證

    1. 準備設定檔。

      1. 建立一個名稱為client.csr.cfg的檔案，內容如下：

        說明

        [dn]內容需要根據您的實際需求修改。

        [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. 建立一個名稱為client.crt.cfg的檔案，內容如下：

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

    2. 執行如下命令，產生裝置認證的私密金鑰client.key

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

    3. 執行如下命令，產生裝置認證的client.csr

      • Mac：

        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. 執行如下命令，產生裝置認證。

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

    5. 執行如下命令，將裝置認證私密金鑰的格式轉換為PKCS#8格式。

      openssl pkcs8 -topk8 -nocrypt -in client.key -out client_pkcs8.key
      重要

      使用代碼串連時參數deviceKyPath應該填寫client_pkcs8.key 的路徑，而不是client.key。

    產生裝置認證的憑證鏈結

    1. 建立一個名稱為client_chain.crt的空的憑證鏈結檔案。

      touch client_chain.crt

    2. 將裝置認證內容複寫到憑證鏈結檔案中。

      cat client.crt >> client_chain.crt

    3. 將CA認證內容複寫到憑證鏈結檔案並將其追加到裝置認證內容後面。

      cat CA.crt >> client_chain.crt

    您可以執行cat client_chain.crt命令查看裝置憑證鏈結內容。

      說明

      裝置認證需要與簽發的CA認證先產生憑證鏈結，才能用於串連到服務端。

      憑證鏈結產生實際上是將幾個認證的內容拼接到一起，順序為子級認證內容在上，父級認證內容在下。

    查詢裝置認證

    您可以查看指定執行個體下所有登入過的裝置認證，或根據認證SN序號進行精確尋找。

    1. 登入雲Message QueueTT 版控制台，並在左側導覽列單擊实例列表。

    2. 在頂部功能表列選擇目標地區，然後在執行個體列表中單擊執行個體名稱進入实例详情頁面。

    3. 在左側導覽列選擇证书管理 > 裝置認證。

      在裝置認證頁面，顯示所有已在服務端註冊過的裝置認證。

    4. 在裝置認證列表上方的搜尋方塊中輸入裝置認證SN序號或CA認證SN序號查詢指定裝置認證。

      • 輸入裝置認證SN序號，查詢結果為該SN序號對應的唯一的裝置認證。

      • 輸入CA認證SN序號，查詢結果為該CA認證所簽發的且已在服務端註冊的所有裝置認證。

    啟用或登出裝置認證

    您可以通過啟用和登出操作修改認證的生效狀態。認證狀態包含啟用和未啟用。裝置認證在服務端註冊後預設為啟用狀態。

    • 認證為啟用狀態：若您需要臨時禁用某個認證，可以將該認證登出，登出後認證不可用且狀態變為未啟用。

    • 認證為未啟用狀態：若您要恢複某個認證，可以將該認證重新啟用，啟用後認證狀態變為啟用。

    在裝置認證列表中，選擇目標認證，在其操作列單擊登出或啟用。

    刪除裝置認證

    刪除裝置認證表示將指定的裝置認證的註冊資訊從服務端的儲存記錄中刪除，並非將認證內容直接刪掉。

    裝置認證刪除後，用戶端使用該裝置認證進行接入認證，如果關聯的CA認證正確並有效，該裝置認證會被重新自動註冊到服務端，並通過認證。

    1. 在裝置認證列表中，選擇目標認證，在其操作列單擊删除。

    2. 在彈出的提示對話方塊中單擊确定。

    常見問題

    一機一密鑒權相關

    雲Message QueueTT 版基礎版是否支援一機一密鑒權？

    支援。基礎版執行個體支援一機一密鑒權模式，該模式通過 AccessKey ID 和 AccessKey Secret 產生使用者名稱和密碼進行認證。

    DeviceAccessKey 是否為阿里雲主帳號 AccessKey？不同裝置能否共用？

    DeviceAccessKey 是為每個裝置單獨申請的獨立憑證，並非阿里雲主帳號的 AccessKey。不同裝置不能共用同一個 DeviceAccessKey，否則可能引發認證衝突並違反安全隔離原則。

    一機一密模式下 Username 或 Password 格式錯誤導致串連失敗怎麼辦？

    需檢查並修正使用者名稱和密碼的格式規範。一機一密模式對 Username 和 Password 有嚴格的格式要求，具體格式請參見裝置唯一認證鑒權概述中的說明。

    一機一密模式使用者名稱過長導致用戶端不支援怎麼辦？

    建議改用 Token 鑒權模式。Token 模式產生的使用者名稱較短，可解決部分用戶端工具不支援長使用者名稱的問題。

    Serverless 版及自訂鑒權

    MQTT Serverless 版如何通過 OpenAPI 擷取鑒權參數？

    可以通過 OpenAPI Explorer 調用相關介面擷取鑒權參數，具體操作請參見裝置唯一認證鑒權概述。

    使用同一套賬密時部分 DeviceId 串連失敗提示無許可權如何排查？

    按以下步驟排查：

    1. 確認執行個體類型，僅專業版或鉑金版支援使用同一套賬密。

    2. 檢查鑒權配置，確保已通過 AddCustomAuthIdentity API 正確產生並添加自訂鑒權身份。

    3. 驗證串連狀態，使用產生的賬密在用戶端進行載入和串連測試。

    4. 若仍失敗，可在控制台查詢該 Client ID 的裝置串連歷史軌跡輔助定位原因。