角色与访问控制

TrustMint 是一个**无头后端服务** —— 它没有自己的 UI。它提供 REST API（api.flexgalaxy.com/licensing/v1/...），供多个前端应用和外部合作伙伴系统调用。启动时，它通过调用 Keycloak Admin API（创建 scope 和 OIDC 客户端）以及 DotID Authorization Service API（注册操作命名空间和托管策略）向 DotID 自注册。

本文档描述角色模型、权限边界、审批工作流委托，以及使用 TrustMint API 的前端应用。

角色

角色	职责	访问方式
**设备制造商**	配置设备、将设备注册到平台、管理设备库存	ThingHub（console.flexgalaxy.com/thinghub/）+ API
**许可证管理员**（可选）	拦截审批工作流以审核和批准 OFFICIAL 许可证请求	合作伙伴构建的外部应用，调用 FlexGalaxy API
**许可证签发方**	按需签发软件许可证，在平台层面管理设备注册	FlexGalaxy.AI 平台（TrustMint 服务本身）

单个账户**可以同时拥有**设备制造商和许可证管理员两种角色。

许可证管理员角色是**可选的** —— 它是一个外部合作伙伴（例如 WHITE），通过订阅 TrustMint webhook 插入审批工作流。如果没有许可证管理员，平台将直接处理审批（参见下文 审批工作流委托）。

权限边界模型

TrustMint 使用自动配置的权限边界。当账户订阅 TrustMint 并声明其角色时，平台会自动分配相应的权限边界 —— 常规情况下无需手动设置。

Account subscribes to TrustMint
     │
     ├── Declares role: Device Manufacturer
     │     └── Auto-assign: devices.read, devices.write, events.read, certificates.read
     │
     ├── Declares role: License Manager
     │     └── Auto-assign: approvals.read, approvals.write, devices.read, licenses.read
     │
     └── Declares both roles
           └── Auto-assign: union of both permission sets

权限边界映射到 DotID 基于策略的访问控制模型 —— 每次角色声明都会触发相应托管策略集的分配。不需要 RBAC 实体；"角色"只是一个决定适用哪些策略的标签。

平台管理员可以通过 **SuperCrew**（stargate.flexgalaxy.com/supercrew）手动覆盖权限边界，以处理特殊情况。

IAM 分离

TrustMint **不**处理身份或访问管理：

• Access Key 和 Secret Key 由用户通过 **AdminCenter**（console.flexgalaxy.com/admincenter/）的服务用户页面自助创建和管理。

• **认证**由 Keycloak（DotID）处理 —— TrustMint 是纯粹的 OAuth2 Resource Server。

• Authorization policies are managed centrally by the platform IAM service.

这种分离确保 IAM 关注点集中在 DotID 中，而 TrustMint 专注于许可证生命周期管理。

审批工作流委托

许可证审批工作流支持**可配置的委托**。许可证管理员角色是可选的中间环节 —— 平台在有或没有许可证管理员的情况下均可运行。

场景	TRIAL 许可证	OFFICIAL 许可证
**未配置许可证管理员**	自动审批（平台自动签发）	自动审批，或由平台管理员通过 BoardingPass 审核
**已注册许可证管理员**（例如 WHITE）	自动审批（平台自动签发）	Webhook → 合作伙伴的外部应用 → 通过 API 回调决策

当许可证管理合作伙伴为某个账户注册 webhook 订阅者时，他们会**拦截** license_upgrade.requested 事件并回调决策结果。这是审批权限的委托 —— 合作伙伴使用 FlexGalaxy API 构建自己的审批 UI。

当没有注册 webhook 订阅者时，平台直接处理：

• TRIAL 请求始终自动审批

• OFFICIAL 请求根据 applet 分类类别自动审批，或排队等待平台管理员在 BoardingPass 中审核

OFFICIAL license request arrives
     │
     ├── Webhook subscriber registered?
     │     │
     │     ├── YES → Send license_upgrade.requested webhook
     │     │         Partner reviews in their own app
     │     │         Partner calls POST /.../decision
     │     │
     │     └── NO  → Queue for platform admin
     │               Admin reviews in BoardingPass
     │               Admin approves/refuses
     │
     └── Decision received
           ├── APPROVE → Issue certificate + JWT, update subscription
           └── REFUSE  → Mark as refused

租户和平台工具

ThingHub

URL:

console.flexgalaxy.com/thinghub/

KC 客户端:

thinghub

受众:

设备制造商、许可证管理员

ThingHub 是覆盖完整设备生命周期的统一租户应用 —— 包括注册、许可和软件更新。它将这些紧密耦合的功能整合到一个基于选项卡导航的应用中。

选项卡：

• **设备** —— 注册（单个和批量）、包含状态和元数据的设备清单、注册历史和配置事件。注册设备会触发 TrustMint 自动签发 TRIAL 许可证。

• **许可证** —— 查看所有已签发的许可证（TRIAL、OFFICIAL）及其状态和到期时间、请求许可证升级（TRIAL 到 OFFICIAL）、跟踪审批状态（PENDING、APPROVED、REFUSED）、证书和令牌详情。

• 更新（OTA） —— 软件更新管理、推送状态、更新历史。

注册流程：

Manufacturer enrolls device in ThingHub (Devices tab)
     │
     ├── TrustMint creates device record
     ├── Auto-issues TRIAL license (X.509 cert + JWT token)
     ├── Records issuance in license ledger
     ├── Sends device.provisioned webhook (if subscriber registered)
     │
     └── Manufacturer views license in ThingHub (Licenses tab)

BoardingPass

URL:

stargate.flexgalaxy.com/boardingpass

KC 客户端:

``boardingpass``（master realm）

受众:

平台管理员

BoardingPass 是平台管理员查看许可证世界的窗口。它提供跨账户的所有许可证操作可见性，并在没有配置外部许可证管理员时作为备用审批 UI。

主要功能：

• 许可证签发分析（按类型、按账户、按时间）

• 跨所有账户的设备注册统计

• 使用趋势和容量规划

• OFFICIAL 许可证的备用审批工作流（当无 webhook 订阅者时）

• 平台级许可证审计追踪

BoardingPass 与 SuperCrew 分离，因为 SuperCrew 专注于 IAM 管理，而 BoardingPass 专注于许可证运维。

DeckLoader

URL:

stargate.flexgalaxy.com/deckloader

KC 客户端:

``deckloader``（master realm）

受众:

平台管理员

DeckLoader 是平台管理员用于跨所有账户设备管理的工具。ThingHub 为租户提供其自身设备的视图，而 DeckLoader 提供平台级的可见性和控制。

主要功能：

• 跨账户设备清单和搜索

• 跨所有租户的设备状态监控

• 平台级注册统计

• 设备生命周期管理（暂停、撤销、转移）

工具总结

工具	网关	受众	职责
ThingHub	Console	租户	设备生命周期：注册、许可证、OTA 更新
AdminCenter	Console	租户	IAM 自助服务：用户、用户组、策略、访问密钥
DeckLoader	StarGate	平台管理员	跨所有账户的平台级设备管理
BoardingPass	StarGate	平台管理员	许可证分析、备用审批、审计
SuperCrew	StarGate	平台管理员	IAM 平台管理、权限边界覆盖