Credentials：从哪里来、如何保存与使用

Mqttable 不负责给 Broker 创建账号或签发证书。Credentials 是当前 Runtime 中的本地安全注册表：你把密码、CA、客户端证书或私钥录入一次，之后 Connection、Proxy 和 Benchmark 只绑定不透明引用。

完成本页后，你应该能判断手里的材料属于哪一类、从哪里取得、保存后在哪里选择，并且能在不复制原文的情况下完成连接验证。

先理解 Credentials

一条 Credential 有三个不同概念，不要混在一起：

1. 外部来源： 谁提供了材料，例如 Broker 管理员、云控制台、身份系统或企业 PKI。
2. 录入来源： 材料通过 Dashboard、MCP intake 或 CLI intake 进入哪个 Runtime。Credentials 页面显示的 Source 指这一项，不代表谁签发了证书。
3. 引用： 保存后得到的 SecretRef、CertRef 或 KeyRef。使用者绑定引用，不再读取原文。

Username、Client ID、SNI 和 ALPN 是连接配置，不是 Credential。System CA 是操作系统信任库，也不会出现在 Credentials 列表中。

判断需要哪种 Credential

最常见的云 Broker 只需要 Username、Password Secret 和 System CA。只有运营方明确要求私有 CA 或 mTLS 时，才需要 CA、Client Certificate 和 Private Key。证书角色仍不清楚时，先阅读看懂并配置 MQTT TLS 证书。

123

把原始材料保存成引用

1. 打开 Credentials，选择 Add credential。
2. 选择与材料匹配的 Type。
3. 使用环境和用途命名，例如 Production EMQX Password。Label 是可搜索 metadata，不能包含密码、Token、PEM 或 Private Key。
4. Password Secret 通过密码输入框录入；证书和私钥可以 Paste 或 Upload。
5. 保存后重新选择该条目，确认页面只显示掩码、证书 Subject、Issuer、Fingerprint、有效期、Key Type 和 Ref。

TLS 表单中的 Upload 或 Paste 也会把材料转换为本地 Ref。Connection 中的 Raw password 则是单一 Connection 的直接录入路径，不会成为可复用的 Credentials 条目。需要复用、查看 Usage 或受控轮换时，使用 Saved SecretRef。

123

页面中的 Source 可能是 Dashboard、MCP intake 或 CLI intake。它只说明录入通道；例如 Source 为 Dashboard 的 Client Certificate 仍然可能由企业 PKI 签发。

使用 Password Secret

Password Secret 绑定在具体的 MQTT Connection 上，而不是 Broker TLS 设置上：

1. 创建或编辑 Connection，填写 Username 和 Client ID。
2. 在 Password 中选择 Saved SecretRef。
3. 从下拉列表选择正确的 Password Secret。
4. 保存并连接，等待状态达到 Connected。
5. 使用获准的测试 Topic 完成一次订阅或发布，再从 Trace 检查结果。

123

Token 或 JWT 由 Broker 的 Password 字段承载时，也保存为 Password Secret。登录成功只证明身份被接受，不代表该身份有权访问所有 Topic；权限仍由 Broker ACL 决定。

使用 TLS Credentials

TLS Credentials 绑定在 Broker 定义上，供该 Broker 下的 Connection 使用：

• 公网或云 Broker： 使用 mqtts、wss 或指定的安全 Transport，保持验证服务器身份开启，选择 System CA，通常不需要保存证书。
• 私有 CA 或自签名 Broker： 选择 Custom CA，再从 Saved 选择 CA CertRef。
• mTLS Broker： 在服务器验证之外开启客户端认证（mTLS），分别选择 Client Certificate CertRef 和匹配的 Private Key KeyRef。

SNI 和 ALPN 只在运营方给出明确值时修改。它们是 TLS 参数，不是 Credential。不要通过关闭服务器验证来处理 Hostname、证书链或 CA 错误。

123

同一类 Ref 还可以在 Proxy 上游 TLS 或 Benchmark 配置中复用。回到 Credentials 选择条目，可以在 Usage 中确认 Connection、Proxy 和 Benchmark 的具体引用位置。

Mqttable 如何保护 Credential

Mqttable 通过多层边界减少原始材料暴露，而不是用“绝对安全”替代操作责任：

• 受控录入： Dashboard 只接受专用密码字段、Paste 或 Upload，不接受任意服务器文件路径。TLS 材料会检查大小和格式；证书与私钥必须能被解析。
• 认证加密： 保存的 Credential 使用 AES-256-GCM 认证加密，每个 Ref 使用独立上下文。数据目录和 Credential 文件使用受限权限。
• 密钥与数据分离： Desktop 的加密密钥由操作系统凭据存储保管，并通过标准输入交给本地 Runtime。Web 或 Remote Runtime 由部署管理员提供 Credential Key。
• Fail closed： 已有加密数据但密钥缺失或不匹配时，Runtime 不会静默生成新密钥并覆盖旧 Vault。
• 不回显、不导出： Registry、MCP 和 CLI 只返回掩码、安全 metadata 和 Ref；Dashboard/Agent Registry 没有 raw export 路径。
• 依赖保护： 删除前重新检查 Connection、Proxy 和 Benchmark Usage；仍被引用的 Credential 不允许删除。
• 审计与清理： 创建、删除和自动清理记录受限 metadata。未被引用的 TLS Ref 会进入 24 小时清理宽限期；Password Secret 不自动删除。

这些保护不覆盖已经离开安全录入边界的副本。源文件、剪贴板、截图、聊天、Issue 和备份仍需遵循组织策略。Ref 也属于当前 Runtime 的 capability，不能当成可跨 Runtime 搬运的秘密值。

Desktop 密钥恢复、数据目录和备份边界请参阅理解 Desktop 设置与数据边界。Agent 不应接触原始 Credential；对应流程见通过安全 Intake 绑定 TLS 凭据。

轮换与删除

轮换时不要覆盖旧材料或先删后测。按以下顺序操作：

1. 在旧 Credential 的 Usage 中列出所有 Connection、Proxy 和 Benchmark 使用者。
2. 从 Broker、身份系统或 PKI 取得新材料，创建一个新的 Ref。
3. 先把一个非关键 Connection 切换到新 Ref。
4. 连接后完成一次有边界的订阅或发布验证。
5. 再更新其余使用者，并在来源系统撤销旧密码、Token 或证书。
6. 确认旧 Ref 的 Usage 归零后，再从 Mqttable 删除它。

删除本地 Ref 不会撤销 Broker 端的密码、Token 或证书。材料泄露时，必须先在真正的签发或认证来源处轮换或撤销。

按失败阶段排查

每次只改一层，再重新测试。连接参数请参阅 MQTT Broker 与 Connection 设置；连接成功后，按照MQTT 快速入门完成消息闭环。