PAYATHON 2026

如何在 Epic 的后端 FHIR 应用中使用 Break-the-Glass?

排障赵师傅

结论

医院可以通过 Epic 配置,允许后端应用访问受 Break-the-Glass(BTG)限制的数据。应用开发者不能仅凭响应中的 fhir-btg-token 为应用授予访问权限。

如果应用使用 client_credentials 进行后台访问,应请医院的 Epic 管理员检查应用的 BTG 配置。eHealth Exchange 的 Epic 接入资料明确要求,后端应用需要访问 BTG 患者数据时,医院应参照 Epic Galaxy 中的 Optional Setup: Allow Backend Apps Access to Sensitive Data 完成配置。接入资料,第 52 页

是否允许访问、允许访问哪些数据,取决于医院的安全策略和部署配置。即使客户已同意应用读取这些记录,管理员仍需配置相应权限。

这段响应说明了什么

这次搜索没有返回匹配资源,同时提示可能有数据因 BTG 限制而未返回:

响应内容 含义
<total value="0" /> 本次搜索返回的匹配资源数量为零,不能据此断定患者没有相关记录
4101 请求没有返回结果
4134 存在 BTG 访问限制,可能还有当前身份无法读取的数据
fhir-btg-token Epic 扩展中的值,仅凭该扩展无法确定后端应用应如何使用它
<mode value="outcome" /> 该条目用于报告处理结果,其中的 OperationOutcome 不是搜索到的临床记录

Epic 的错误码说明将 4134 列为与受限患者数据有关的信息级提示,并说明相关安全检查由各医院配置。Epic FHIR 错误码说明

即使 HTTP 请求成功,应用也需要检查 OperationOutcome,避免将这类响应直接判定为“患者没有数据”。

fhir-btg-token 名称中虽然含有 token,也不能将它当作 OAuth access_token 使用。这段响应没有说明如何提交它,也没有提供后端应用可调用的解锁端点。

后端应用应如何处理

  1. 检查应用是否使用 client_credentials,确认出现问题的环境、FHIR 端点和应用 Client ID。应用有后端服务,并不代表所有请求都使用后台授权模式。如果请求使用的是代表临床用户的授权令牌,应按相应的用户访问流程排查。

  2. 请医院管理员检查后台应用的敏感数据访问配置,并提供脱敏后的请求、资源类型、时间、Client ID,以及包含 4134 的 OperationOutcome。管理员需查阅 Galaxy 中的 Optional Setup: Allow Backend Apps Access to Sensitive Data,核对当前应用和 Interconnect 实例的配置。具体菜单、字段和权限项以医院所用版本的文档为准。

  3. 配置完成后,使用相同的应用身份和查询条件复测原请求,确认预期资源是否返回,以及是否仍有 BTG 提示。如果仍受限,应由管理员继续核查相关记录的访问策略。

响应中的 “User can break the glass” 不能证明当前后台调用具备交互式解锁能力。对于无人值守的后端集成,“让医生手动解锁一次”能否作为长期授权方案,尚未得到确认。

代码示例:识别 BTG 限制

下面的 Python 示例解析题目中的 XML,检测到 4134 后转入权限排查流程。代码不执行解锁,也不使用返回的 BTG token。

import xml.etree.ElementTree as ET

FHIR_NS = {"f": "http://hl7.org/fhir"}


def has_btg_restriction(xml_body: str) -> bool:
    root = ET.fromstring(xml_body)

    if root.tag == "{http://hl7.org/fhir}OperationOutcome":
        outcomes = [root]
    else:
        outcomes = root.findall(
            ".//f:OperationOutcome", FHIR_NS
        )

    for outcome in outcomes:
        for issue in outcome.findall("f:issue", FHIR_NS):
            codes = issue.findall(
                "f:details/f:coding/f:code", FHIR_NS
            )
            if any(code.get("value") == "4134" for code in codes):
                return True

    return False


# response_xml 为 FHIR 接口返回的 XML 响应正文。
if has_btg_restriction(response_xml):
    raise PermissionError(
        "Epic 返回 BTG 限制提示,请联系医院管理员检查应用权限。"
    )

该示例针对题目中的 Epic 响应。生产实现中,如果已知 details.coding.system,应同时匹配编码系统和 code,避免将其他编码系统中的同名代码误判为 Epic 错误码。

注意事项

  • 4134 提示“可能还有数据”,不保证配置权限后一定能获得符合查询条件的资源。
  • 不要自行猜测 BTG 请求头、参数或解锁 URL。如果需要额外协议,应取得适用于该医院部署和应用类型的明确说明。
  • 保留必要的排查信息,但不要将完整患者信息、OAuth token 或 BTG token 写入普通日志。
  • 反复重试同一响应对应的请求不会获得访问权限。应先解决医院端配置,再验证读取结果。

备注:内容仅供参考。