如何在 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 使用。这段响应没有说明如何提交它,也没有提供后端应用可调用的解锁端点。
后端应用应如何处理
-
检查应用是否使用
client_credentials,确认出现问题的环境、FHIR 端点和应用 Client ID。应用有后端服务,并不代表所有请求都使用后台授权模式。如果请求使用的是代表临床用户的授权令牌,应按相应的用户访问流程排查。 -
请医院管理员检查后台应用的敏感数据访问配置,并提供脱敏后的请求、资源类型、时间、Client ID,以及包含
4134的OperationOutcome。管理员需查阅 Galaxy 中的Optional Setup: Allow Backend Apps Access to Sensitive Data,核对当前应用和 Interconnect 实例的配置。具体菜单、字段和权限项以医院所用版本的文档为准。 -
配置完成后,使用相同的应用身份和查询条件复测原请求,确认预期资源是否返回,以及是否仍有 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 写入普通日志。
- 反复重试同一响应对应的请求不会获得访问权限。应先解决医院端配置,再验证读取结果。
备注:内容仅供参考。
