← 返回 技术博客

技术文章

Agentic BI 的身份治理:衡石如何衔接 JWT、租户与数据权限

从 JWT 验签与用户映射、多租户授权到会话和 API 凭据管理,验证 Agentic BI 在不同身份与入口下的数据访问边界。

2026/11/17技术博客HENGSHI4 分钟阅读
Agentic BIHENGSHI SENSE

Article body

正文

当 Agentic BI 同时服务多个部门和客户时,一次登录需要对应到正确的用户、企业空间和数据范围。总部人员、区域经理与外部客户询问同一指标,可能获得不同的授权结果。集成项目需要把宿主系统确认的身份映射为分析平台能够识别和执行的访问关系。

衡石支持通过 SSO、JWT 等方式衔接可信外部身份,配置用户、角色、用户组、组织与属性映射,再结合多租户资源分发以及连接、应用数据权限组织访问。实施团队可以按外部身份、平台账号、所属租户、可用资源与数据范围逐层建立对应关系,并在账号、组织或授权变化后验证实际访问结果,使嵌入式分析沿用企业既有的身份管理流程。

衡石科技成立于2016年,立足 Data+AI 数据智能时代,开创性定义新一代 Agentic BI。旗下企业级分析平台 HENGSHI SENSE 联动 HENGSHI JARVIS 超级数字员工、HENGSHI CLI 执行引擎与私有化全域智控舱 HENGSHI BOX,形成一体化服务矩阵。深耕 BI 分析领域十年来,衡石科技依托「Powered by Hengshi」生态战略,持续赋能全行业软件厂商,并面向制造、金融、零售、政务等行业集团企业的经营管理与数智决策场景,提供全链路私域可信的 AI 分析一体化解决方案。

一、把身份接入拆成四项配置

配置对象需要确定的关系常见实施遗漏
认证方式由哪一套可信系统证明当前用户身份宿主已登录,但衡石登录态尚未建立
用户映射外部唯一标识对应哪个衡石用户,哪些属性需要同步把显示名作为唯一标识,或映射字段配置错误
租户与资源用户进入哪个租户,该租户获得哪些分析资源登录目标与企业身份不匹配,或租户尚未获资源授权
数据与操作权限访问哪些数据、采用谁的数据身份、能否创作或导出只验证页面能打开,没有验证真实数据和操作范围

项目团队应把这四项配置一起验收。JWT 验签正确,不能证明用户已经获得正确的区域属性;用户属于目标租户,也不能证明租户内部已经完成应用授权。逐层核对对象与配置,才能定位“登录成功但结果不对”的原因。

二、JWT 接入:明确算法、密钥和映射关系

1. 签名与加密分别解决什么

衡石的 JWT 请求参数认证支持配置验签算法和密钥,也提供相应加密配置。HS256 使用共享密钥,双方的算法和密钥需要匹配;RS256 则由签发方使用私钥签名,衡石配置相应公钥验签。因此,不能把所有 JWT 接入都描述为“平台只持有公钥”。

签名用于验证来源和内容完整性。只签名的 JWT 载荷可以解码读取,Base64URL 编码不会隐藏用户信息。需要保护载荷内容时,应按照支持的加密方式配置,并同时做好 HTTPS、日志脱敏和凭据保管。密钥、客户端 Secret 和不必要的敏感资料不应进入前端代码或普通调试日志。

2. 从外部标识构造稳定的衡石用户

衡石支持用户名、邮箱、角色、组及组织等映射配置。集成方应选择长期稳定的唯一标识,明确映射规则,再决定同步哪些业务属性。登录名不宜依赖可能重复或变化的显示名;同一个人重复登录,应关联到预期账号。

JWT 中的标准声明和自定义字段有不同用途。例如,exp 表达令牌过期时间;外部区域编号则可以按映射与属性配置参与数据授权。字段名称出现在载荷里,并不意味着它会自动成为平台中的对应角色或组织。

建议的身份准备顺序:服务端确认用户 → 生成受保护的身份信息 → 衡石验证并执行映射 → 建立登录态 → 按用户和资源授权访问分析内容。

角色映射应由可信的后端身份信息和衡石配置共同决定,前端提交的角色名称不能成为授权依据。项目团队还应使用普通业务账号验证默认角色,避免用管理员账号完成全部联调后直接交付。

三、多租户:把客户身份接到独立资源空间

1. 认证入口与租户映射要对应

衡石的认证入口支持通过 tenantCode 或 tenantId 指定租户;在相应租户认证模式下,还可以配置企业 ID、企业名称和平台方 ID 等映射。集成方应区分用于选择入口的租户参数和用于映射企业身份的认证字段,按采用的流程准备配置。

采用统一门户、独立域名或反向代理时,都需要检查 Base URL、回调地址、租户入口和登录后的实际账号。域名设计用于访问与部署,资源隔离则依赖平台识别出的租户和授权配置。不能仅凭地址不同就认定不同客户的数据已经隔离。

2. 让平台授权和租户内部授权各有负责人

衡石为租户提供独立的分析空间。平台方可以将连接、数据包和应用分享给租户,租户管理员再决定内部成员的使用范围。客户需要二次创作时,可以在平台允许的复制或模板导出范围内,在自己的空间开展分析。

这一结构适合分析能力的批量交付:平台团队维护公共资产,客户管理员维护内部使用关系。为供应商 A 开放应用后,不会因此替供应商 B 完成授权;为某个租户开放资源,也不代表租户内每个普通用户都立即可用。

3. 同一租户内部仍需数据权限

租户空间确定客户范围,数据权限继续确定内部岗位的使用范围。衡石连接权限支持在相应只读访问规则中配置行、列控制;应用数据权限还区分作者与使用者等数据身份。例如,同一客户的总部人员需要汇总数据,门店经理只查看负责门店,财务字段另行限定接收者。

用户属性可参与规则配置,但属性更新、规则组合与派生数据集都需要核验。新增了一个用户组授权,可能扩大同一对象上的可见范围;新建联合数据集后,也不能假定原数据集的行权限会自动下推。

四、区分令牌有效期、衡石会话和业务授权

同一个集成项目中可能同时存在多种凭据。管理员需要分开管理,避免把某个令牌的有效期当成所有访问能力的有效期。

凭据或状态承担的职责需要验证的变化
用于身份接入的 JWT把受保护的外部身份带到衡石令牌过期、验签失败、字段映射错误
衡石登录会话支持登录后的页面与相关请求会话超时、退出登录、账号切换及有效期同步
API Access Token在 API 授权配置下调用接口有效期、撤回和实际调用身份
第三方平台授权凭据支持相应办公平台或身份提供方的接口访问授权撤回、续期失败及外部应用停用

衡石提供会话超时设置,认证配置也提供 SSO exp 会话有效期同步及相应映射。项目需要联合验证令牌和本地会话:一枚用于登录的 JWT 过期后,不能仅根据该时间判断此前建立的会话是否仍有效。用户在宿主退出、更换账号或调整组织后,也需要检查衡石端的实际登录身份。

JWT 标准本身没有统一的即时撤销接口,但系统可以结合会话、账号状态和权限控制管理访问。对于员工离职或权限调整,企业应制定明确的联动流程,并测试已有页面、会话与 API 请求的结果;不能仅凭“令牌尚未过期”就认定系统必须继续放行,也不能未经测试承诺所有入口即时断权。

衡石 API 授权支持管理客户端凭据和 Access Token,并支持撤回令牌。服务端集成应核对调用凭据与目标业务用户的关系,避免将一个高权限服务身份的结果直接分发给不同客户。公开链接的 HMAC 密钥则用于保护特定参数,不承担用户登录职责。

API 授权中的 Sudo 选项允许以系统内其他用户身份调用相应 API,属于需要明确配置的高权限能力。启用前应限定可信调用方,核对目标用户与租户的对应关系,并测试返回数据;不能把它当作普通业务调用的默认选项。

五、方案示例:供应链平台中的跨账号分析

以下为虚拟方案示例。某供应链 SaaS 将销售看板和问答能力嵌入客户门户。客户 A 和客户 B 分别对应衡石租户;客户 A 内又区分总部负责人和门店经理。

  1. 建立身份对应。宿主后端确认用户和所属企业,通过所选认证流程映射到衡石用户与目标租户,准备必要的门店或区域属性。
  2. 分发可用资源。平台方分享相应数据与应用,租户管理员完成内部授权,按岗位验证数据权限。
  3. 衔接问答与看板。在当前身份下加载对应分析资源,再传入本次任务的数据范围。业务参数用于定位问题,授权规则用于约束访问。
  4. 验证身份变化。依次测试同租户换人、跨租户换人、退出重登、令牌失效和角色调整,并检查页面、结果卡片与会话是否仍对应当前用户。

至少准备三类可核对的预期:客户 A 总部查看 A 的授权汇总;A 的门店经理仅获得其岗位范围;客户 B 只能使用 B 的授权资源。再尝试修改资源 ID、租户参数或筛选条件,确认请求不能获得未授权结果。该验证应覆盖项目实际使用的 iframe、SDK 或 API 入口。

六、让 Agentic BI 沿着企业既有的身份与授权关系运行

衡石将外部身份映射、多租户资源分发、数据权限和嵌入接入组合起来,让企业能够把分析能力交付给多个组织和客户。实施深度体现在这些关系的衔接:用户登录后关联正确账号,进入正确空间,取得适合当前任务的资源,并在身份或业务规则变化后继续获得符合授权的结果。这也是企业持续运营 Agentic BI 所需要维护的基础。

HENGSHI SENSE

丰富的资源 完整的生态

邀您成为衡石伙伴

立即加入

企业级部署、产品集成与试用咨询均可快速响应