EMQX 权限 Scope 互斥校验：Dashboard 用户与 API Key 的 privilege scope 隔离规则

后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载本篇技术指南聚焦 EMQX 5.10 中 Dashboard 登录用户与 API Key 的权限模型变更privilege scopesystem、user_management、api_key_management、sso_management不得与任何普通 scope 混合出现在同一显式 scope 列表中。读完本文你将理解这四条 scope 为何被视为管理员等价、新规则在 Dashboard 用户与 API Key 两个端点上的落地方式、边界情形空列表、mfa_management、namespaced admin如何处理以及升级后如何拆分历史遗留的混合 scope 列表。背景EMQX 的两类授权主体与 scope 目录EMQX 通过scope权限范围对两类主体做细粒度授权API Key调用 REST API 的长期凭证可持有的 scope 为通用目录connections、publish、monitoring 等Dashboard 登录用户登录 Web 控制台的账号除通用 scope 外还可持有 4 个仅限登录用户的 scopeuser_management、mfa_management、sso_management、api_key_management。全部 scope 名称以编译期宏的形式集中定义在 emqx_utils/include/emqx_api_key_scopes.hrl并通过 emqx_utils/src/emqx_scope_catalog.erl 提供静态目录与校验逻辑。该目录模块是纯数据、无运行时依赖同时被emqx_managementAPI Key 授权、/api_key_scopes端点和emqx_dashboard登录用户 scope 校验、/user_scopes端点消费。用户可见的通用 scope 共 10 个connections、publish、data_integration、access_control、gateways、monitoring、cluster_operations、system、audit、license见 common_scope_catalog/0。四条管理员等价的 privilege scope在 emqx_api_key_scopes.hrl 中定义了特权 scope 分组?PRIVILEGE_SCOPESScope 名称管理员等价的原因system覆盖/configs/*与/data/*可重写整个节点配置user_management可创建持有任意 scope 的登录用户api_key_management可签发持有任意 scope 的 API Keysso_management可轮换/替换 SSO 后端从源码结构看这四条 scope 的管理员等价推理链是持有其中任意一条即可通过被覆盖的管理面 API 间接获取或授予任意权限——例如持有user_management就能造出一个拥有完整目录的管理员账号。因此把它们与受限制的普通 scope 放在同一个显式列表中无法对账户产生任何有意义的限制只会造成看起来受限、实际等价管理员的虚假安全感。注意mfa_management虽然同样是仅限管理员admin-only的登录用户 scope但刻意被排除在 privilege 分组之外。它的语义是管理其他用户的 MFA无法供给用户、签发 Key 或改写配置不构成管理员等价因此允许与普通受限 scope 共存详见下文边界情形。新规则privilege scope 与普通 scope 互斥自本变更起Dashboard 用户端点与 API Key 端点拒绝同时包含 privilege scope 与普通 scope 的显式 scope 列表。规则可归纳为显式、非空的 scope 列表必须纯 privilege或纯非 privilege二选一列表为空[]或字段缺失undefined时不适用该规则——它们是历史遗留的不受限与拒绝一切语义而非显式混合列表校验失败时返回 HTTP 400错误消息形如Privilege scopes cannot be combined with other scopes. Privilege scopes present: system. Other scopes present: connections. Assign either privilege scopes alone (administrator-equivalent), or non-privilege scopes alone.该消息由 emqx_scope_catalog.erl 的check_privilege_scope_mutex/1生成其中通过partition_privilege_scopes/1将输入列表拆分为{Privilege, Other}两个子列表保持输入顺序再判断是否两侧都非空。源码实现互斥校验的核心逻辑核心逻辑集中在 emqx_utils/src/emqx_scope_catalog.erl%% 将 scope 列表拆分为 {Privilege, Other} partition_privilege_scopes(Scopes) when is_list(Scopes) - lists:partition(fun(S) - lists:member(S, ?PRIVILEGE_SCOPES) end, Scopes). %% 互斥校验undefined 与 [] 直接放行 check_privilege_scope_mutex(undefined) - ok; check_privilege_scope_mutex([]) - ok; check_privilege_scope_mutex(Scopes) when is_list(Scopes) - case partition_privilege_scopes(Scopes) of {[], _} - ok; %% 纯非 privilege {_, []} - ok; %% 纯 privilege {Priv, Other} - %% 混合拒绝 {error, Privilege scopes cannot be combined with other scopes. ...} end.从实现可以看到三个关键设计放行条件undefined字段缺失与[]显式空列表直接通过——分别对应历史不受限与拒绝一切语义纯 privilege 或纯非 privilege 均放行四个 privilege scope 彼此可以自由组合普通 scope 之间也照常组合错误信息带明细把 Privilege 与 Other 两组名称都拼进消息便于客户端直接定位需要拆分的内容。两个接入点Dashboard 用户与 API Key 的四层校验Dashboard 用户端点POST/PUT /users登录用户的 scope 写入校验链路位于 apps/emqx_dashboard/src/emqx_dashboard_api.erl采用多层校验、返回首个错误的策略validate_scope_names/1拒绝未知 scope 名防拼写错误与$denied注入validate_role_scope_compat/2非管理员角色不得持有 admin-only scopemaybe_check_privilege_mutex/2仅对全局命名空间?global_ns的管理员应用 privilege mutexnamespaced admin 豁免见下节。其中validate_login_user_scopes/3接收RawScopes与EffectiveScopes两个列表RawScopes是客户端实际提交的值EffectiveScopes是经过角色默认值物化后的值。mutex 只针对RawScopes执行这是有意设计——若省略scopes字段物化出来的管理员角色默认值本身就是一个 privilege 与普通 scope 的混合集但它应被当作不受限的隐式情况放行而非显式混合列表见 write_scope_intent/2 对keep/unset/{set, L}三种写入意图的归一化。API Key 端点POST/PUT /api_keysAPI Key 侧的校验在 apps/emqx_management/src/emqx_mgmt_api_api_keys.erl同样是四层、首错即返validate_publisher_scopes/2发布者角色兼容性validate_no_login_only_scopes/1API Key禁止持有任何登录用户专属 scope4 个 login-only scope 会被直接拒绝validate_scopes_in_catalog/1scope 必须存在于目录emqx_scope_catalog:check_privilege_scope_mutex(RawScopes)同样只针对客户端实际提交的RawScopes执行互斥校验。两类端点的共同原则是互斥规则作用于客户显式声明的意图而不是系统物化出的默认值。边界情形与豁免空列表与字段缺失scopes字段省略 → 走角色默认值物化mutex 不触发scopes: []→ 显式拒绝一切的 deny-all合法。测试用例t_user_non_explicit_lists_pass/1验证了这两种情况均放行见 apps/emqx_dashboard/test/emqx_dashboard_user_scopes_SUITE.erl。mfa_managementadmin-only 但不是 privilegemfa_management属于?ADMIN_ONLY_SCOPES仅管理员可持有但不在?PRIVILEGE_SCOPES中。因此[mfa_management, connections]✅ 合法可以与普通 scope 共存[mfa_management, system]❌ 拒绝system是 privilege scope。测试用例t_user_mfa_mgmt_not_privilege/1精确覆盖了这对组合见上文 SUITE 文件第 781-787 行。namespaced admin 豁免对于命名空间管理员namespaced adminmutex不适用RBAC 分发是其权威闸门会拦截 privilege scope 本可触达的变更面且命名空间角色的 scope 兼容校验已先行收窄了可用集合继续套用互斥会破坏既有合法组合。对应测试为t_ns_admin_exempt_from_privilege_mutex/1与回归用例t_ns_admin_still_rejects_forbidden_scope/1见 SUITE 第 789-821 行——豁免 mutex 的同时越界的 scope 仍会被 400 拒绝。测试验证矩阵apps/emqx_dashboard/test/emqx_dashboard_user_scopes_SUITE.erl 以 CT 用例完整覆盖了本规则用例验证内容t_user_privilege_only_lists_pass纯 privilege 列表放行含四条全组合t_user_nonprivilege_only_lists_pass纯非 privilege 列表放行t_user_mixed_lists_rejected五组混合列表全部 400 拒绝t_user_non_explicit_lists_pass字段省略 / 显式空列表放行t_user_mfa_mgmt_not_privilegemfa_management 与普通 scope 可共存、与 privilege 不可共存t_ns_admin_exempt_from_privilege_mutex命名空间管理员豁免t_user_update_privilege_mutexPUT 更新路径混合 400、拆分后 200t_user_legacy_mixed_record历史遗留混合记录的读/写行为升级与兼容性历史遗留的混合 scope 记录规则上线前写入的、已存储为混合 scope 集的用户/API Key 记录继续正常运行读取不受影响——校验只发生在写入路径。但存在一个升级注意点下次更新该记录时如果请求仍提交同样的混合列表会被 400 拒绝t_user_update_privilege_mutex与t_user_legacy_mixed_record均验证了这一点更新请求必须拆分列表才能成功要么只保留 privilege scope管理员等价要么只保留普通 scope受限二选一写入。例如某历史用户持有[system, connections]升级后做一次 PUT 更新时# 拆分方式一仅保留 privilege scope管理员等价 PUT /api/v5/users/u_legacy { role: administrator, scopes: [system] } # 拆分方式二仅保留普通 scope受限 PUT /api/v5/users/u_legacy { role: administrator, scopes: [connections] }同样地API Key 更新PUT /api/v5/api_keys/:name若携带混合列表也会被check_privilege_scope_mutex/1拒绝需按同一原则拆分。实操建议新建账户时明确二选一需要管理员等价能力就用纯 privilege 列表如[system]或四条 privilege 的组合需要最小权限就用纯普通 scope 列表升级前审计存量记录通过GET /api/v5/users与GET /api/v5/api_keys拉取现有scopes对同时含 privilege 与普通 scope 的记录制定拆分计划可借助 emqx_scope_catalog.erl 中partition_privilege_scopes/1的分组逻辑人工判别牢记 mfa_management 的定位它虽仅限管理员但不是 privilege scope可与普通 scope 共享显式列表遵循显式意图才受检省略scopes字段或传[]都不触发互斥校验前者回落到角色默认能力后者是 deny-all。这一规则从机制上杜绝了privilege scope 受限 scope这一自相矛盾的配置形态让 scope 列表的语义在写入时即保持自洽避免账户实际权限远超列表表象的安全隐患。赞分享后端物联网消息队列通信【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址https://gitcode.com/gh_mirrors/em/emqx点击查看免费下载相关推荐atproto/oauth-scopesAT Protocol OAuth 作用域Scope解析与权限校验实战指南atproto/oauth scopesAT Protocol OAuth 作用域Scope解析与权限校验实战指南 本文以 atproto 仓库中 a后端社交EMQX API Keys 基于 Scope 的权限控制细粒度 API 访问管理实战指南EMQX API Keys 基于 Scope 的权限控制细粒度 API 访问管理实战指南 output文章 EMQX API Keys 基于 Scope 的后端物联网消息队列通信Hetty Scope API编程方式管理规则Hetty Scope API编程方式管理规则 引言突破手动配置的效率瓶颈 在网络安全测试与HTTP流量分析过程中如何精准界定测试范围Scope始终是网络安全应用安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考