Authentication 驗證

為什麼要學這個

第 5 章你已經能用 WebSocket 工具連上 broker，但那時多半是「空帳密」狀態。EMQX 在你還沒建立任何驗證資源之前，client 是可以直接連的——這對生命週期單機的確認很方便，但也意味著任何人只要能碰到你的 1883 或 8083，就能發布、收看你整個主題空間。Woow 的 add-on 文件把「首次登入後必須先設定 MQTT 驗證」列為必做事項，不是可選。

這章帶你實際建立 Password-Based（密碼式）＋ 內建資料庫（Built-in Database） 的驗證，新增你要給 Home Assistant 與裝置使用的帳號，並學會停用驗證資源與刪除使用者的做法；同時把 JWT、HTTP、LDAP 三種機制「看得懂、知道何時才用」的概念講清楚，之後才會跟著裝出更符合你需要的驗證架構。

核心概念

EMQX 把「驗證」與「授權」分成兩件事：驗證（Authentication）回答「你是誰」，用帳號密碼、client ID、JWT 等機制確認；授權（Authorization）回答「這個身分能做哪些 publish／subscribe」，是第 7 章的主題。Dashboard 從左側 Access Control 展開，可以看到 Authentication、Authorization 與 Banned Clients（黑名單）。

建立驗證通常分四步：先選機制（Mechanism），再選後端（Backend）存放或取得資料，然後設定連線資訊，最後「建立」。機制有 Password-Based（帳號／密碼）、JWT（權杖）、以及 MQTT 5.0 的 SCRAM（增強式、雙向驗證）。後端有 EMQX 內建資料庫、外部資料庫（MySQL／PostgreSQL／MongoDB／Redis）、以及 HTTP Server；JWT 不需要後端。

家用 add-on 務實的一步，就是 Password-Based ＋ Built-in Database：不需要另外維護一套資料庫，直接在 Dashboard 新增使用者，就能讓 Home Assistant 與 Zigbee2MQTT 用帳密連入。

名詞對照

動手做

1. 進到 Authentication 驗證頁

   登入 Dashboard，左側 Access Control → Authentication，按右上 Create。

2. 建立 Password-Based ＋ 內建資料庫

   在 Create 頁選機制 Password-Based，後端選 Built-in Database（外部資料庫、HTTP Server 先留到概念段）。依你的需求設定是使用 Username 還是 ClientID、密碼加密方式，最後按 Create。

3. 新增使用者

   在 Authenticator List 找到剛建立的那筆，點 User Management，新增一組帳號與密碼（例如 ha_broker／<你的密碼>），它會被存在 EMQX 內建資料庫。

4. 驗證成功連線與停用

   回到第 5 章的 WebSocket 工具，用剛建立的帳密連線，確認驗證真的生效（錯的密碼會被拒）。再到 Authenticator List 把這筆驗證器的 Enable 開關關掉觀察「所有 client 都能連」的後果，實驗完記得立刻恢復。個別多餘的使用者可在 User Management 刪除。

Password-Based 內建資料庫

內建資料庫是最省心的後端：使用者帳密存在 EMQX 自己的資料庫中，不需要另外跑一套資料服務。你可以用 User Management 手動新增、刪除帳號，也可以下載官方範本填好後 Import 匯入來一次建立多筆。

設定時有兩個細節要留意。第一是 UserID Type：帳戶連線時要用「username」還是用「client ID」當作辨識基準，跟你實際送出的欄位一致才行。第二是密碼加密（Password Hash）與 Salt 位置：改動 Password Hash 或 Salt Position 之後，已建立的認證資料全部失效，必須重新建立使用者。

停用方面，EMQX 的 Enable 開關可即時停用整個驗證器。官方文件特別強調：停用之後「所有 client 都能連線」——它不是一刀擋下所有人，而是把這層身分檢查拿掉。如果你是為了維運暫時停用，記得用畢立刻恢復；想要「連得上但不見得能做事」，那是第 7 章授權的責任。

JWT 驗證概念

JWT（JSON Web Token）是權杖式驗證：client 在連線時把一顆 JWT token 放進 username 或 password 欄位，EMQX 驗證簽名與 Payload 聲明即可，因此 JWT 不需另外的後端。建立時可選 Secret（以密鑰驗證）或 Public Key（以公鑰驗證），搭配是否對 secret 做 Base64，並在 Payload 填入需要驗證的聲明。

若你使用 JWKS Endpoint，EMQX 會定期向授權伺服器取回一組 RSA／ECDSA 公開金鑰來驗證 JWT，並可設定取得更新的間隔（秒）。JWT 適合「權杖已由既有的身分服務簽發、你只是想讓 EMQX 也認這些 token」的場景。

對純 Home Assistant 自建環境來說，這通常是加分項而不是必選：如果你還沒有任何 token 簽發服務，直接走帳號密碼會更簡單。

HTTP 與 LDAP 概念

HTTP Server 是把驗證交給你自己準備的外部 HTTP 服務：EMQX 將每次連線請求送到該 URL，依回應決定允許或拒絕。設定需要提供請求方法（POST 或 GET）、請求網址（需含 http／https 協定）、Header，以及在 Body 裡放入要驗證的資訊（通常含 username 與 password）。它可以配合現有的帳號系統，但你要自行維護並確保回應格式符合 EMQX 期待。

LDAP（Lightweight Directory Access Protocol）是走到目錄伺服器查證使用者的協定。重點要先講在這裡：LDAP 在 EMQX 只有 Enterprise 付費版提供，你 Open Source 的 5.8.9 Dashboard 裡不會看到它。因此概念上它是「借既有的 LDAP 目錄當帳號來源」，但對家用 add-on 來說，先用內建資料庫或 HTTP 會更務實。

故障排除

• 建立驗證後，Home Assistant 開始連不上去：多數原因是你對齊的欄位或密碼不對。回頭確認 UserID Type 是看 username 還是 client ID、增設的帳號大小寫與密碼、以及驗證器沒有被帶停用。如果你的實驗把 Enable 關掉了，重新開啟即可恢復。
• 把 Enable 關掉後「所有 client 都能連」：這是設計行為：停用代表把整層驗證規則拿掉，不是「防護更強」。想「擋掉不認得的 client」，需要授權（第 7 章）與正確的驗證器共存；不要以為關掉驗證器等於開啟防護。
• JWT 一直驗證失敗：檢查你選的是 Secret 還是 Public Key、Base64 開關是否一致、Payload 聲明與你在 JWT 內的 claims 匹配；先拿一顆你在簽發端就能看的 token，到 Dashboard 最小路徑測試。
• 外部資料庫／HTTP 後端顯示 Disconnected：表示 EMQX 連不到該伺服器或查詢失敗。檢查伺服器位址、埠、帳密與回應格式是否符合期待；修好外部狀態後回到 Authenticator List，再讓它重新連一次。

常見問題

官方來源

• EMQX 5.8 Dashboard Authentication（pinned docs 分支）
• EMQX 5.8 Access Control（驗證／授權總覽）
• Woow EMQX add-on README（首次登入必先設定驗證）