深色模式
登录身份与数据范围
一个库里存着多家(多个医院、机构、门店)的数据时,嵌进宿主系统的报表必须只显示当前登录的人那一家的数据。这一篇讲怎么把「当前是谁」交给报表。
先记住一条:浏览器里的东西都不可信。租户 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 | 显示名,可不填 |
role | viewer 只看已发布报表(默认);designer 能进设计器改报表;admin 还能管数据源与 AI 服务商 |
scope | 这个人能看的数据范围:一个数组,如 ["1001"];管几个机构就写几个。数据源按不同的列分(比如机构、科室)时写成对象:{ "org_ids": ["1001"], "dept_ids": ["07"] } |
scopeAll | true 表示不限范围(集团、运营端)。「全部」必须显式写,不写 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 | 登录用的账号,不分大小写 |
passwordHash | conch 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 | 意思 | 宿主怎么办 |
|---|---|---|---|
| 401 | auth_required | 没带凭证 | 按上面把凭证交给报表 |
| 401 | auth_expired | 凭证过期 | 报表会自己再要一次;一直这样说明宿主给的是旧凭证 |
| 401 | auth_invalid | 签名不对、签发方不认识、租户不在允许范围 | 核对换票客户端或签发方配置 |
| 403 | forbidden | 角色不够,或凭证限定了报表 | 换票时给对 role / reports |
| 403 | scope_missing | 数据源开了范围,凭证里没有范围值 | 换票时带上 scope(或显式 scopeAll: true) |
| 400 | — | 请求参数里带了由系统决定的参数(如 conch_scope) | 去掉它;范围只能经凭证传 |
| 401 | login_invalid | 账号密码登录:账号或密码不对 | — |
| 429 | login_locked | 账号密码登录:连续输错,账号暂时锁定 | 等 Retry-After 秒后再试 |
