Skip to content

登录身份与数据范围 ​

一个库里存着多家(多个医院、机构、门店)的数据时,嵌进宿主系统的报表必须只显示当前登录的人那一家的数据。这一篇讲怎么把「当前是谁」交给报表。

先记住一条:浏览器里的东西都不可信。租户 id 如果写在链接里、写在 postMessage 里、写在元素属性里,用户按 F12 就能改。所以报表只认宿主后端签发的凭证,前端只负责转交,从不「声明」自己是哪个租户。

整体流程 ​

宿主后端 ──① 换一张凭证──> 宿主前端 ──② 交给嵌入的报表──> 报表前端
                                                          │
                                ③ 每个请求都带 Authorization: Bearer <凭证>
                                                          ▼
                                报表服务:验签 → 从凭证取租户与范围 → 取数时强制过滤

凭证默认 10 分钟有效(最长 15 分钟),快过期时报表会自己向宿主再要一张,宿主不用管续期的时机。

① 宿主后端换凭证 ​

报表服务的 conch.config.json 里开启鉴权,并登记你们的系统:

json
{
  "auth": {
    "mode": "jwt",
    "clients": [
      { "id": "his", "secret": "env:CONCH_CLIENT_HIS", "tenant": "hospital-a" }
    ]
  }
}
  • secret 写 env:变量名 从环境变量取,别把明文写进配置文件。
  • tenant 是这个客户端能签的报表服务租户。请求里传的租户不作数,一个宿主签不出别家的凭证。
  • maxMinutes 可选,这个客户端签的凭证最长多少分钟,默认 15。给嵌入宿主的保持默认(报表会自己续);团队内部直接打开设计器用的客户端可以放宽,最多 480。

用户打开报表所在的页面时,宿主后端调一次换票接口(密钥不能出现在浏览器里):

http
POST /api/auth/exchange
Authorization: Basic base64(his:<密钥>)
Content-Type: application/json

{
  "sub": "u10086",
  "name": "张三",
  "role": "viewer",
  "scope": ["1001"]
}
json
{ "token": "eyJhbGciOiJFUzI1NiIs…", "expiresAt": "2026-09-23T10:38:53Z", "tenant": "hospital-a" }
字段说明
sub宿主里的用户标识,必填,只用于留痕
name显示名,可不填
roleviewer 只看已发布报表(默认);designer 能进设计器改报表;admin 还能管数据源与 AI 服务商
scope这个人能看的数据范围:一个数组,如 ["1001"];管几个机构就写几个。数据源按不同的列分(比如机构、科室)时写成对象:{ "org_ids": ["1001"], "dept_ids": ["07"] }
scopeAlltrue 表示不限范围(集团、运营端)。「全部」必须显式写,不写 scope 不等于看全部,而是什么都看不到
space可选。报表空间,见下面各家自己设计自己用
reports可选。只允许打开这几张报表的 id
minutes可选。有效期分钟数,不超过客户端的 maxMinutes(默认 15)

已经有 JWT 的宿主

宿主自己就签 JWT(比如 ABP)的,可以不走换票:报表服务配上你们的签发方与公钥,直接认你们的 token。见下面的宿主自己签 JWT。

② 把凭证交给报表 ​

iframe ​

报表发现没有凭证或凭证过期时,会向宿主发一条消息要;宿主回一条带凭证的消息。不要把凭证拼进 iframe 的链接,链接会进访问日志、浏览器历史,被人转发时一起带走。

js
const REPORT_ORIGIN = 'https://report.example.com'
const frame = document.getElementById('report')

window.addEventListener('message', async (e) => {
  if (e.origin !== REPORT_ORIGIN) return
  const msg = e.data
  if (msg?.source !== 'conch-report') return

  if (msg.type === 'authRequired') {
    // 找自己的后端要:后端去调 /api/auth/exchange
    const { token } = await fetch('/my-api/report-token').then((r) => r.json())
    frame.contentWindow.postMessage({ source: 'conch-report-host', type: 'auth', token }, REPORT_ORIGIN)
  }
})
  • authRequired 会在 ready 之前就发出来(报表要先有凭证才打得开),这条别像 setParams 那样等 ready 再处理。
  • 宿主也可以不等要、随时主动推一条 auth(比如用户在宿主里切换了机构)。
  • 10 秒内没收到凭证,报表显示打不开,并发 { type: 'error', code: 'auth_required' }。

自定义元素 ​

给元素设 tokenProvider——一个返回凭证的异步函数。报表在第一个请求前调一次,快过期或被服务端拒绝时再调:

html
<script type="module" src="https://report.example.com/embed.js"></script>
<conch-report id="r" report-id="r260922123456"></conch-report>
<script>
  document.getElementById('r').tokenProvider = async () => {
    const { token } = await fetch('/my-api/report-token').then((r) => r.json())
    return token
  }
</script>

它是 JS 属性,不是 HTML 属性:写在标签上的属性谁都能在 DOM 里读到,也没法续期。脚本加载之前先设也可以,元素升级时会接上。

独立页面 ​

运维或测试要直接打开报表服务(没有宿主)时,在地址后面加 #token=<凭证>。锚点部分不发给服务器,页面读到后立刻从地址栏抹掉,存在当前标签页里,关掉标签页就失效。在报表服务所在的机器上可以用命令行签一张:

bash
conch token --tenant hospital-a --role admin --minutes 120
# 然后打开 https://report.example.com/#token=<上面输出的那串>

账号密码登录 ​

报表服务也可以配几个账号,直接打开时弹登录框,不必每次签凭证。适合团队自己、客户的管理员进设计器与设置;被宿主嵌着(iframe、自定义元素)时不会弹,凭证照旧由宿主给。

在报表服务所在的机器上生成一段账号配置(口令输两遍,不回显):

bash
conch password --name admin --role admin --tenant default

把输出加进 conch.config.json 的 auth.users,重启生效:

json
"auth": {
  "mode": "jwt",
  "users": [
    { "name": "admin", "passwordHash": "pbkdf2-sha256$600000$…", "tenant": "default", "role": "admin", "scopeAll": true }
  ],
  "loginMinutes": 480
}
字段说明
name登录用的账号,不分大小写
passwordHashconch password 生成的口令哈希;写明文口令服务起不来
tenant / space / role登录后的身份,含义同换票;不写 role 就是 viewer
scopeAll / scope数据范围,写法同换票(数组落在 conch_scope,对象按声明名)
loginMinutes登录后多久要重登,默认也最多 480 分钟
  • 同一个账号连续输错 5 次,锁定 5 分钟(回 429,带 Retry-After)。
  • 登录得到的凭证存在浏览器本地,同一浏览器新开标签页不用再登;报表列表右上角「退出登录」清掉它。
  • 接口:GET /api/auth/login 回 { enabled },表示这台服务配没配账号;POST /api/auth/login,body { "username", "password" },成功回 { token, expiresAt, name }。

③ 报表服务怎么用这份身份 ​

  • 开了鉴权后,除初始化向导、换票与账号密码登录接口外,所有接口都要有效凭证,否则回 401。X-Conch-Tenant、X-Conch-Scope 这类请求头不再生效。
  • 凭证里的角色决定能调哪些接口:只看报表的账号只能按已发布版本取数、导出,看不到草稿,也不能写 SQL 试跑。
  • 报表归属于报表服务租户,别的租户的报表当作不存在。

数据范围:执行时强制过滤 ​

在数据源上配数据范围后,每条 SQL 执行前都会被改写成只查当前身份范围内的数据——报表是谁设计的、SQL 里写没写范围条件、写对没有,都不影响结果。

json
"scope": {
  "column": "org_id",
  "label": "机构",
  "claim": "conch_scope",
  "exempt": ["dict_status", "dict_region"],
  "via": { "order_item": { "fk": "order_id", "parent": "orders" } }
}
字段说明
column范围列。库里凡是有这一列的表都自动按它过滤
label这个范围怎么称呼(机构、门店、租户),用在提示语里
claim从凭证的哪个声明取范围值;换票时 scope 写数组就落在默认的 conch_scope 里
exempt没有范围列、所有机构共用的表(字典表之类),不过滤
via没有范围列、但经外键属于某张有范围列的表(明细属于订单),按归属过滤

没有范围列、也没写进 exempt 或 via 的表,在这个数据源里查不了,会提示「还没有说明属于哪个机构」。宁可少查一张表,也不让单查一张明细表把别家的数据带出来。

范围值拿不到时一律拒绝(403,code: scope_missing),不会退回去显示某个默认机构的数据。

各家自己设计自己用 ​

一个宿主系统服务多家机构、所有机构的数据在同一个库里,而且每家自己设计报表、只给自己用时,换票多传一个 space:

json
{ "sub": "u10086", "role": "designer", "space": "<机构 id>", "scope": ["<机构 id>"] }
  • space 管报表归谁:报表记在创建人的空间下,别的空间看不到、打不开、改不了,拿着报表 id 也不行。
  • scope 管数据归谁:取数时只查这家机构的行。
  • 两个通常填同一个机构 id。数据源、AI 服务商这些配置整个宿主只配一份,新开机构不用动报表服务。
  • 不带 space 的身份只看得到不属于任何空间的报表。

所有机构共用同一批报表(由宿主统一设计)时,不传 space 就行,每家照样只看到自己的数据。

宿主自己签 JWT ​

json
{
  "auth": {
    "mode": "jwt",
    "issuers": [
      {
        "issuer": "https://sso.example.com",
        "audience": "conch-report",
        "jwksUrl": "https://sso.example.com/.well-known/jwks.json",
        "tenant": "hospital-a",
        "claims": { "role": "roles" },
        "roleMap": { "report-admin": "admin", "report-maker": "designer" },
        "defaultRole": "viewer"
      }
    ]
  }
}
  • 公钥二选一:jwksUrl(会缓存 10 分钟,遇到新的 kid 会刷新)或 publicKey(PEM)。
  • 租户:tenant 写死;一个签发方服务多家时改用 tenantClaim 指定声明名,再用 tenants 列出允许的取值。
  • claims 把报表服务要的声明名映射到你们 token 里的名字:sub、name、role、reports、scopeAll、space。数据范围按数据源 scope.claim 指定的声明名直接取。
  • 角色值先查 roleMap,查不到再看它本身是不是 viewer / designer / admin;都不是就用 defaultRole。
  • 支持 ES256/384/512、RS256/384/512、PS256/384/512;不签名的 token 一律拒绝。

出错时服务端回什么 ​

状态code意思宿主怎么办
401auth_required没带凭证按上面把凭证交给报表
401auth_expired凭证过期报表会自己再要一次;一直这样说明宿主给的是旧凭证
401auth_invalid签名不对、签发方不认识、租户不在允许范围核对换票客户端或签发方配置
403forbidden角色不够,或凭证限定了报表换票时给对 role / reports
403scope_missing数据源开了范围,凭证里没有范围值换票时带上 scope(或显式 scopeAll: true)
400—请求参数里带了由系统决定的参数(如 conch_scope)去掉它;范围只能经凭证传
401login_invalid账号密码登录:账号或密码不对—
429login_locked账号密码登录:连续输错,账号暂时锁定等 Retry-After 秒后再试

给 AI 用的纯文本索引在 /llms.txt,每篇原文在 /md/ 下。