后端物聯(lián)網(wǎng)消息隊(duì)列通信【免費(fèi)下載鏈接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles項(xiàng)目地址https://gitcode.com/gh_mirrors/em/emqx點(diǎn)擊查看免費(fèi)下載導(dǎo)讀本文圍繞 EMQX當(dāng)前開源倉庫中一項(xiàng)針對SCRAM 認(rèn)證 HTTP API的缺陷修復(fù)展開此前調(diào)用創(chuàng)建用戶接口時接口返回的user_id與實(shí)際創(chuàng)建的用戶 ID 不一致。文章將以該修復(fù)為核心梳理 SCRAM 認(rèn)證scrambuilt_in_database在 HTTP API 層的完整用戶管理調(diào)用鏈結(jié)合倉庫源碼說明缺陷根因、修復(fù)后的正確行為并給出可直接復(fù)現(xiàn)與驗(yàn)證的 API 用法。讀完本文你將掌握 EMQX 內(nèi)置數(shù)據(jù)庫 SCRAM 認(rèn)證的創(chuàng)建/查詢/更新/刪除/輪換密碼接口語義以及接口返回值必須與實(shí)際寫入數(shù)據(jù)一致這一契約在源碼中的實(shí)現(xiàn)方式。1. 缺陷描述創(chuàng)建用戶接口返回了錯誤的 user_id本次修復(fù)記錄位于倉庫 changes/ee/fix-16459.en.md原文如下Fixed the issue in SCRAM authentication HTTP API. Previously, incorrect user ID was returned for the created user in the user creation API call.翻譯過來即修復(fù)了 SCRAM 認(rèn)證 HTTP API 中的問題——此前調(diào)用用戶創(chuàng)建 API時返回的 user_id 并非實(shí)際創(chuàng)建的那個用戶。這條 changelog 雖短但指向明確問題發(fā)生在SCRAM 認(rèn)證認(rèn)證機(jī)制為scram后端為內(nèi)置數(shù)據(jù)庫built_in_database的用戶創(chuàng)建 HTTP 接口上屬于典型的API 返回值與后端真實(shí)寫入狀態(tài)不一致類缺陷。這類問題在自動化運(yùn)維場景中危害明顯——腳本若依賴創(chuàng)建接口返回的user_id做后續(xù)綁定、授權(quán)或?qū)徲嬀蜁玫藉e誤的標(biāo)識符。需要說明的是該修復(fù)記錄位于changes/ee/目錄企業(yè)版變更記錄因此該缺陷及其修復(fù)首先出現(xiàn)在 EMQX 企業(yè)版渠道但從下文源碼分析可以看到相關(guān)的用戶管理邏輯位于開源倉庫中apps/emqx_auth_mnesia與apps/emqx_auth兩個應(yīng)用修復(fù)本身可直接在開源代碼中定位與驗(yàn)證。2. SCRAM 認(rèn)證與內(nèi)置數(shù)據(jù)庫用戶管理全景在深入缺陷根因之前先厘清 SCRAM 認(rèn)證在 EMQX 中的位置與用戶管理的整體架構(gòu)。2.1 SCRAM 認(rèn)證是什么SCRAMSalted Challenge Response Authentication MechanismRFC 5802是一種不傳輸明文密碼的挑戰(zhàn)-響應(yīng)認(rèn)證機(jī)制。EMQX 內(nèi)置數(shù)據(jù)庫認(rèn)證支持兩種機(jī)制password_based密碼散列scramSCRAM 挑戰(zhàn)-響應(yīng)倉庫 apps/emqx_auth_mnesia/include/emqx_auth_mnesia.hrl 中定義了機(jī)制與后端的常量-define(AUTHN_MECHANISM_SIMPLE, password_based). -define(AUTHN_MECHANISM_SIMPLE_BIN, password_based). -define(AUTHN_MECHANISM_SCRAM, scram). -define(AUTHN_MECHANISM_SCRAM_BIN, scram). -define(AUTHN_BACKEND, built_in_database). -define(AUTHN_BACKEND_BIN, built_in_database).SCRAM 認(rèn)證的關(guān)鍵特性源碼中體現(xiàn)為約束包括密碼不以明文落庫創(chuàng)建用戶時客戶端提交的明文密碼會被轉(zhuǎn)化為stored_keyStoredKey、server_keyServerKey和salt鹽值存儲明文密碼本身不持久化不支持批量導(dǎo)入正因?yàn)辂}值和密鑰由明文密碼推導(dǎo)且明文不落盤SCRAM 認(rèn)證的導(dǎo)入用戶操作被顯式拒絕。見 emqx_authn_scram_mnesia.erl%% SCRAM credentials cannot be bulk-imported: salts and stored/server keys %% derive from the plaintext password, which is never persisted. The provider %% advertises user-management support generally, so we surface the limitation %% here rather than letting dispatch crash. import_users(_File, _State) - {error, unsupported_operation}.不支持密碼輪換rotate_password接口對 SCRAM 類型返回Operation not supported in this authentication type見下文測試用例。2.2 用戶管理 API 的完整調(diào)用鏈EMQX 內(nèi)置數(shù)據(jù)庫認(rèn)證的用戶管理 API 由 apps/emqx_auth/src/emqx_authn/emqx_authn_api.erl 暴露路由定義于該文件/authentication/:id/users/:user_id 全局認(rèn)證鏈用戶管理 /authentication/:id/users/:user_id/password/rotate /listeners/:listener_id/authentication/:id/users/:user_id 監(jiān)聽器級認(rèn)證鏈調(diào)用鏈如下HTTP API (emqx_authn_api) └─ add_user / update_user / find_user / delete_user / rotate_password └─ emqx_authn_chains:add_user / update_user / ... └─ emqx_authn_scram_mnesia:add_user / do_add_user / do_update_user / ... └─ mria 事務(wù) mnesia 寫入 (?TAB / ?NS_TAB)其中用戶數(shù)據(jù)存儲層位于 apps/emqx_auth_mnesia/src/emqx_authn_scram_mnesia.erlSCRAM 憑證的生成鹽值、StoredKey、ServerKey由sasl_auth_scram:generate_authentication_info/2完成。存儲上區(qū)分兩個表全局命名空間用戶#user_info{}記錄表?TABuser_id形如{UserGroup, UserId}命名空間多租戶用戶#?NS_TAB{}記錄表?NS_TABuser_id形如?NS_KEY(Namespace, UserGroup, UserId)三元組編碼了命名空間、用戶組與用戶 ID。user_id的編碼與解碼key/3、rec_to_map/1、format_user_info/1集中在 emqx_authn_scram_mnesia.erlkey(?global_ns, UserGroup, UserId) - {UserGroup, UserId}; key(Namespace, UserGroup, UserId) when is_binary(Namespace) - ?NS_KEY(Namespace, UserGroup, UserId).對外輸出時統(tǒng)一取元組中的UserIdformat_user_info(#user_info{user_id {_, UserId}, is_superuser IsSuperuser}) - #{user_id UserId, is_superuser IsSuperuser}; format_user_info(#?NS_TAB{user_id ?NS_KEY(_, _, UserId), is_superuser IsSuperuser}) - #{user_id UserId, is_superuser IsSuperuser}.可以看到對外暴露的用戶 ID與存儲層復(fù)合主鍵之間存在一層解包邏輯這正是本缺陷容易產(chǎn)生偏差的位置。3. 缺陷根因剖析返回值為何與真實(shí)寫入不一致3.1 從源碼看應(yīng)當(dāng)一致的契約先看修復(fù)后當(dāng)前倉庫狀態(tài)的正確行為。HTTP 層創(chuàng)建用戶的入口add_user/3位于 emqx_authn_api.erladd_user(ChainName, AuthenticatorID, #{user_id : UserID} RawUserInfo) - Namespace maps:get(namespace, RawUserInfo, ?global_ns), IsSuperuser maps:get(is_superuser, RawUserInfo, false), PasswordField case RawUserInfo of #{password : Password} - #{password Password}; _ - #{} end, UserInfo maps:merge( #{ namespace Namespace, user_id UserID, is_superuser IsSuperuser }, PasswordField ), case check_superuser_allowed(Namespace, IsSuperuser) of ok - case emqx_authn_chains:add_user(ChainName, AuthenticatorID, UserInfo) of {ok, User} - {201, user_out(User)}; {error, Reason} - serialize_error({user_error, Reason}) end; ... end;這里 HTTP 層把請求體中的user_id原樣放入UserInfo透傳下去然后直接透傳后端返回的User并序列化給客戶端。因此創(chuàng)建接口返回什么user_id完全取決于認(rèn)證提供者emqx_authn_scram_mnesia在寫入后返回了什么。存儲層do_add_user/1emqx_authn_scram_mnesia.erldo_add_user(UserInfoRecord) - case do_lookup_by_rec_txn(UserInfoRecord) of [] - ok insert_user(UserInfoRecord), #{ namespace : Namespace, user_id : UserId, is_superuser : IsSuperuser } rec_to_map(UserInfoRecord), {ok, #{namespace Namespace, user_id UserId, is_superuser IsSuperuser}}; [_] - {error, already_exist} end.即先寫入insert_user再把rec_to_map/1解包出的、確實(shí)寫入表中的UserId作為返回值。rec_to_map/1emqx_authn_scram_mnesia.erl從記錄中解包rec_to_map(#user_info{} Rec) - #user_info{ user_id {UserGroup, UserId}, ... } Rec, #{ namespace ?global_ns, user_id UserId, user_group UserGroup, ... }; rec_to_map(#?NS_TAB{} Rec) - #?NS_TAB{ user_id ?NS_KEY(Namespace, UserGroup, UserId), ... } Rec, #{ namespace Namespace, user_id UserId, user_group UserGroup, ... }.同時user_info_record/5emqx_authn_scram_mnesia.erl在構(gòu)造記錄時也把請求中的UserId與UserGroup即認(rèn)證器 ID編碼進(jìn)復(fù)合主鍵user_info_record(?global_ns, UserGroup, UserId, Password, IsSuperuser, State) - {StoredKey, ServerKey, Salt} sasl_auth_scram:generate_authentication_info(Password, State), #user_info{ user_id {UserGroup, UserId}, stored_key StoredKey, server_key ServerKey, salt Salt, is_superuser IsSuperuser };綜合可見請求的user_id→ 復(fù)合主鍵 → 表中記錄 →rec_to_map解包 → HTTP 響應(yīng)這一條鏈在修復(fù)后是嚴(yán)格閉環(huán)一致的。修復(fù)前的缺陷正是這條鏈上出現(xiàn)了偏差——返回給客戶端的user_id取自了錯誤的字段或錯誤的位置例如直接取復(fù)合鍵的某一錯誤分量、或使用了占位/默認(rèn)值導(dǎo)致返回的 user_id 不是實(shí)際創(chuàng)建的用戶。修復(fù)的本質(zhì)就是讓返回值回到以實(shí)際寫入記錄的復(fù)合主鍵解包結(jié)果為準(zhǔn)這一契約上。3.2 為什么是 SCRAM 特有與其他機(jī)制的差異該問題被標(biāo)記為SCRAM 認(rèn)證 HTTP API特有從源碼結(jié)構(gòu)看可以推斷其背景是SCRAM 提供者emqx_authn_scram_mnesia與普通密碼散列提供者emqx_authn_mnesia共用同一套 HTTP 用戶管理入口但各自維護(hù)獨(dú)立的存儲記錄格式與轉(zhuǎn)換函數(shù)rec_to_map、format_user_info。任何一邊在返回用戶信息時若未嚴(yán)格復(fù)用寫入后解包的結(jié)果就會出現(xiàn)與其他機(jī)制行為不一致的返回內(nèi)容。SCRAM 這邊記錄結(jié)構(gòu)含stored_key/server_key/salt等額外字段格式轉(zhuǎn)換路徑更長出現(xiàn)偏差的概率也更高。3.3 測試用例對修復(fù)行為的固化倉庫測試套件 apps/emqx_auth_mnesia/test/emqx_authn_api_mnesia_SUITE.erl 中固化了創(chuàng)建接口返回真實(shí) user_id的斷言例如創(chuàng)建后校驗(yàn)返回體lists:foreach( fun(User) - {201, CreatedUser} add_user(User), ?assertMatch( #{ user_id : _, namespace : NsAPIOut }, CreatedUser, #{expected_ns NsAPIOut} ) end, ValidUsers ),以及用戶存在性檢查后抓取返回的user_id{201, _} add_user(User), ... ?assertMatch(#{user_id : u1}, FetchedUser),此外t_scram_user_api_errors/1emqx_authn_api_mnesia_SUITE.erl專門針對 SCRAM 用戶 API 的邊界行為做了斷言可作為理解該 API 語義的參考t_scram_user_api_errors(_TCConfig) - put_auth_header(create_superuser()), ScramConfig #{ mechanism scram, backend built_in_database, algorithm sha512, iteration_count 4096 }, {200, _} create_authenticator(ScramConfig), AuthenticatorID scram:built_in_database, {400, #{message : PasswordRequired}} add_authenticator_user(AuthenticatorID, #{user_id scram-user}), ?assertNotEqual(nomatch, binary:match(PasswordRequired, Password is required)), {201, _} add_authenticator_user(AuthenticatorID, #{ user_id scram-user, password scram-password }), {400, #{message : Unsupported}} rotate_authenticator_password(AuthenticatorID, scram-user), ?assertEqual(Operation not supported in this authentication type, Unsupported), ok.該用例同時印證了三件事SCRAM 創(chuàng)建用戶缺少密碼時返回 400Password is required——因?yàn)槊荑€必須由明文密碼生成正確提交user_idpassword時返回 201SCRAM不支持密碼輪換rotate_password返回 400。4. 完整用戶管理 API 實(shí)操請求與響應(yīng)語義以下 API 均基于修復(fù)后的當(dāng)前倉庫行為。認(rèn)證鏈用戶管理接口全局認(rèn)證鏈路徑前綴為/api/v5/authentication/:id/users監(jiān)聽器級接口為/api/v5/listeners/:listener_id/authentication/:id/users:id為認(rèn)證器 ID如scram:built_in_database。4.1 創(chuàng)建用戶POSTPOST /api/v5/authentication/:id/users請求體{ user_id: scram-user, password: scram-password, is_superuser: false }可選字段字段類型默認(rèn)值說明user_idstring必填用戶名/用戶標(biāo)識缺失時返回 400missing_parameter: user_id見 emqx_authn_api.erlpasswordstring必填SCRAM明文密碼SCRAM 機(jī)制缺失時返回 400Password is requiredis_superuserbooleanfalse是否超級用戶namespacestring全局命名空間僅限全局管理員為多租戶命名空間創(chuàng)建用戶時使用成功響應(yīng)201{ user_id: scram-user, is_superuser: false, namespace: null }注意全局命名空間下返回體中namespace為null見 emqx_authn_api.erl 的user_out/1User#{namespace : null}命名空間用戶則返回實(shí)際命名空間名。user_id必須與請求體中的user_id一致——這正是本次修復(fù)保證的契約。重復(fù)創(chuàng)建同一用戶返回 409already_exist。4.2 查詢用戶列表GETGET /api/v5/authentication/:id/users支持分頁與模糊查詢參數(shù)其中l(wèi)ike_user_id用于按用戶名子串模糊過濾emqx_authn_api.erl多命名空間場景可用ns查詢參數(shù)指定命名空間。模糊匹配的底層實(shí)現(xiàn)見 emqx_authn_scram_mnesia.erl通過binary:match實(shí)現(xiàn)子串匹配。4.3 查詢/更新/刪除單個用戶GET /api/v5/authentication/:id/users/:user_id PUT /api/v5/authentication/:id/users/:user_id DELETE /api/v5/authentication/:id/users/:user_idGET按user_id精確查找返回{user_id, is_superuser, namespace}不存在時返回 404not_foundPUT可更新password重新生成鹽值與 StoredKey/ServerKey與is_superuser至少需提供其一否則返回 400missing_parameter: password見 emqx_authn_api.erl更新成功后同樣返回格式化后的完整用戶信息DELETE刪除指定用戶成功返回 204用戶不存在返回 404。更新操作的字段篩選見fields_to_update/3emqx_authn_scram_mnesia.erl僅keys_and_salt由密碼推導(dǎo)與is_superuser兩個字段會被實(shí)際寫回。4.4 密碼輪換SCRAM 不支持POST /api/v5/authentication/:id/users/:user_id/password/rotate對 SCRAM 認(rèn)證器調(diào)用返回 400{ message: Operation not supported in this authentication type }這是 SCRAM 的固有約束鹽值與密鑰隨密碼生成并落庫服務(wù)端無從進(jìn)行類似 JWT 那樣的無狀態(tài)密碼輪換。4.5 命名空間多租戶語義對于啟用了命名空間Namespace的部署用戶管理 API 支持兩種指定命名空間的方式emqx_authn_api.erl請求體中的namespace字段查詢參數(shù)ns。兩者的解析與鑒權(quán)遵循以下規(guī)則未指定時使用調(diào)用者管理員賬號自身的命名空間全局管理員?global_ns可以操作任意命名空間普通命名空間管理員只能操作自身命名空間越權(quán)操作返回 403。測試用例t_delete_user_namespace_resolution/1emqx_authn_api_mnesia_SUITE.erl驗(yàn)證了 body 與 query 兩種方式均可獨(dú)立選擇刪除目標(biāo)命名空間。多命名空間下的寫入存儲于獨(dú)立的?NS_TAB表復(fù)合主鍵為?NS_KEY(Namespace, UserGroup, UserId)。5. SCRAM 認(rèn)證器的配置參數(shù)SCRAM 內(nèi)置數(shù)據(jù)庫認(rèn)證器的配置 schema 位于 apps/emqx_auth_mnesia/src/emqx_authn_scram_mnesia_schema.erlfields(scram) - [ {mechanism, emqx_authn_schema:mechanism(?AUTHN_MECHANISM_SCRAM)}, {backend, emqx_authn_schema:backend(?AUTHN_BACKEND)}, {algorithm, fun algorithm/1}, {iteration_count, fun iteration_count/1} ] emqx_authn_schema:common_fields().配置項(xiàng)類型/取值默認(rèn)值說明mechanismscram—認(rèn)證機(jī)制固定為 SCRAMbackendbuilt_in_database—后端存儲固定為內(nèi)置數(shù)據(jù)庫algorithmsha256/sha512sha256散列算法schema 定義iteration_count非負(fù)整數(shù)4096SCRAM 迭代次數(shù)schema 定義越大越安全但認(rèn)證開銷越高enablebooleantrue認(rèn)證器啟用開關(guān)common fieldsuser_id_typeusername/clientidusername用戶 ID 取自 MQTT 連接的哪個字段common fields認(rèn)證器創(chuàng)建后其user_group即認(rèn)證器 ID如scram:built_in_database創(chuàng)建用戶的create/2回調(diào)把它作為用戶記錄的user_group分量emqx_authn_scram_mnesia.erl這也是復(fù)合主鍵{UserGroup, UserId}的來源。測試中使用的配置示例algorithm sha512, iteration_count 4096與 schema 默認(rèn)值保持一致。6. 總結(jié)與驗(yàn)證要點(diǎn)本次修復(fù)的核心契約可以歸納為一句話創(chuàng)建用戶 API 返回的user_id必須與實(shí)際寫入內(nèi)置數(shù)據(jù)庫記錄中的用戶 ID 一致。驗(yàn)證修復(fù)是否生效可以從三個層面入手API 層POST /api/v5/authentication/:id/users創(chuàng)建 SCRAM 用戶后斷言響應(yīng)體201中的user_id與請求體中的user_id完全一致參考測試 emqx_authn_api_mnesia_SUITE.erl數(shù)據(jù)層通過GET /api/v5/authentication/:id/users/:user_id查詢同一用戶確認(rèn)返回的user_id與創(chuàng)建時的請求/響應(yīng)一致參考 emqx_authn_api_mnesia_SUITE.erl源碼層確認(rèn)emqx_authn_scram_mnesia的do_add_user/1返回值取自rec_to_map/1解包出的復(fù)合主鍵UserId而非請求體之外的其他來源。對該缺陷的修復(fù)提醒我們在認(rèn)證這類對數(shù)據(jù)一致性高度敏感的場景中寫什么就返回什么必須由同一份數(shù)據(jù)源驅(qū)動任何在返回路徑上另起爐灶的字段處理都可能制造出 API 契約與真實(shí)狀態(tài)脫節(jié)的隱性缺陷。EMQX 通過讓返回體直接復(fù)用寫入后解包的記錄從代碼結(jié)構(gòu)上杜絕了這類偏差這也是本次修復(fù)最值得借鑒的實(shí)現(xiàn)思路。涉及的核心文件索引修復(fù)記錄changes/ee/fix-16459.en.mdHTTP API 層apps/emqx_auth/src/emqx_authn/emqx_authn_api.erlSCRAM 存儲與憑證邏輯apps/emqx_auth_mnesia/src/emqx_authn_scram_mnesia.erlSCRAM 配置 schemaapps/emqx_auth_mnesia/src/emqx_authn_scram_mnesia_schema.erl類型常量定義apps/emqx_auth_mnesia/include/emqx_auth_mnesia.hrl用戶管理 API 測試apps/emqx_auth_mnesia/test/emqx_authn_api_mnesia_SUITE.erl贊分享后端物聯(lián)網(wǎng)消息隊(duì)列通信【免費(fèi)下載鏈接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles項(xiàng)目地址https://gitcode.com/gh_mirrors/em/emqx點(diǎn)擊查看免費(fèi)下載相關(guān)推薦EMQX 連接 MongoDB 8.0 認(rèn)證失敗問題修復(fù)解析buildInfo 探測與 SCRAM 認(rèn)證機(jī)制EMQX 連接 MongoDB 8.0 認(rèn)證失敗問題修復(fù)解析buildInfo 探測與 SCRAM 認(rèn)證機(jī)制 導(dǎo)讀 本文基于 EMQX 倉庫中的變更記錄 c后端物聯(lián)網(wǎng)消息隊(duì)列通信EMQX 集群加入期間監(jiān)控指標(biāo) API 返回 500 的根因分析與修復(fù)解讀EMQX 集群加入期間監(jiān)控指標(biāo) API 返回 500 的根因分析與修復(fù)解讀 本篇文章基于 EMQX 開源倉庫變更記錄 changes/ee/fix 18114.后端物聯(lián)網(wǎng)消息隊(duì)列通信EMQX 修復(fù) SCRAM 認(rèn)證指標(biāo)計數(shù)異常Total 重復(fù)累加與 Success 缺失問題剖析EMQX 修復(fù) SCRAM 認(rèn)證指標(biāo)計數(shù)異常Total 重復(fù)累加與 Success 缺失問題剖析 導(dǎo)讀 本文圍繞 EMQX 開源倉庫中 changes/ee/后端物聯(lián)網(wǎng)消息隊(duì)列通信創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考