在 FHIR 上使用 SMART 连接到应用

本页面介绍了如何在 FHIR v1.1.0 标准上使用 SMART（可替换医疗应用、可重复使用的技术）来访问 Cloud Healthcare API 中的 FHIR 存储区中的数据。

概览

SMART on FHIR 是一种数据标准，可让应用访问电子健康记录 (EHR) 系统中的信息。应用开发者可编写单个可连接到任何采用该标准的 EHR 系统的应用。

例如，如果您在 Cloud Healthcare API 的 FHIR 存储区中存储患者数据，则可以开发执行以下操作的应用：

向 FHIR 存储区进行身份验证。
检索该患者的数据。
在界面中显示该患者的数据。

SMART on FHIR 支持使用 OpenID 和 OAuth 2.0 授权模型进行授权和身份验证。

SMART 应用启动框架、范围和启动上下文

Cloud Healthcare API 按以下方式支持 SMART 应用启动框架、范围和启动上下文：

SMART 应用启动框架

Cloud Healthcare API 支持 SMART 应用启动框架中的独立发布序列。

应用可以从现有的 EHR 系统或患者门户会话内启动，两者都称为“EHR 启动”，也可以作为独立应用启动。

权限范围

临床数据范围定义了患者特定级别和用户级访问权限的读取和写入权限。Cloud Healthcare API 支持请求临床数据的范围中定义的以下数据范围：

patient
user
system

启动上下文

描述当前的患者、遇到的患者或正在发出请求的其他情境。Cloud Healthcare API 支持请求上下文数据的范围中的患者启动上下文。

为 SMART on FHIR 配置授权服务器

Cloud Healthcare API 基于输入 SMART 授权范围和患者上下文对 SMART on FHIR 访问权限强制执行提供内置支持。FHIR 存储区管理员可在 Cloud Healthcare API 之外创建和配置授权服务器，以授予 SMART 授权范围和患者上下文。

如果客户端应用获取表示已授予的 SMART 授权范围和患者上下文的访问令牌，则 Cloud Healthcare API 不会指定客户端应用需要与外部授权服务器搭配使用哪个启动工作流。

设置和验证 SMART 授权范围

如果您使用的是 SMARTProxy，可以跳过本部分。 SMARTProxy 会自动设置并验证 SMART 授权范围。

SMART 授权范围采用以下格式：

( 'patient' | 'user' | 'system') '/' ( resourceType | '*' ) '.' ( 'read' | 'write' | '*' )

SMART 授权范围和患者上下文使用 X-Authorization- HTTP 标头传递给 Cloud Healthcare API。Cloud Healthcare API 使用这些标头来强制执行 FHIR 存储区中的数据访问权限控制。

您的授权服务器会授予 SMART 授权范围和患者上下文，并在访问令牌中对其进行编码。然后，代理会读取访问令牌中的信息，并将其传递给 FHIR 请求标头。

如果您没有授权服务器，可以在 Apigee 上使用基于 Apigee 的互操作性加速器 HealthAPIx。

从代理发出请求时，请使用以下 SMART on FHIR HTTP 标头。客户端应用无需设置这些标头，因为它们仅从代理传递到 Cloud Healthcare API。

X-Authorization-Scope：使用标准 SMART 授权范围格式的一个或多个授权范围。例如，将授权范围设置为 user/Observation.read 就表示，请求只能读取观察资源。Cloud Healthcare API 会强制实施此访问权限控制。
X-Authorization-Patient：请求的患者上下文。设置此标头时，请求中任何有资格进入患者隔离区的任何资源类型都必须属于所提供的患者 ID 的患者隔离区。Cloud Healthcare API 会强制实施此访问权限控制。
X-Authorization-Subject：在 FHIR 客户端应用上访问 SMART 的最终用户的标识符。Cloud Healthcare API 将主题记录在审核日志中。
X-Authorization-Issuer：SMART 访问令牌颁发者。Cloud Healthcare API 在审核日志中记录颁发者。

配置授权服务器访问令牌

要发出 JWT 令牌，您必须配置授权服务器。JWT 令牌包含 SMART 授权范围和（可选）患者上下文。对于授权服务器如何创建 SMART JWT 令牌的方式，Cloud Healthcare API 没有特定要求。例如，您的应用可能注册了某个范围子集，或者该应用可能提供了一个患者选择微件来设置患者上下文。

如果您没有配置 SMART JWT 令牌的授权服务器，可以使用 Apigee 上基于 Apigee 的互操作性加速器 HealthAPIx 来设置对 JWT 令牌签名的身份验证服务器。

访问令牌示例

以下示例展示了用 base64 编码的访问令牌：

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzM4NCJ9.eyJpc3MiOiJzbWFydC50b2tlbi5vcmciLCJpYXQiOjE2MTI4ODQwODUsImV4cCI6MTY0NDQyMDA4NSwiYXVkIjoid3d3LmV4YW1wbGUuY29tIiwic3ViIjoiZG9jdG9yLmpvZUBleGFtcGxlLmNvbSIsInNjb3BlIjoidXNlci9QcmFjdGl0aW9uZXIucmVhZCBwYXRpZW50LyouKiIsInBhdGllbnQiOiJwYXRpZW50MTIzIn0.lC0ouNuXNcj7FxQ83NU_MInULWo0wvyiNuaMt2RbFzBOnnMP_IXJdCeNnw3SQzUV

对访问令牌进行解码后，它会包含以下载荷：

{
  "iss": "smart.token.org",
  "iat": 1612884085,
  "exp": 1644420085,
  "aud": "www.example.com",
  "sub": "doctor.gabriela@example.com",
  "scope": "user/Practitioner.read patient/*.*",
  "patient": "patient123"
}

在 Cloud Healthcare API 中配置 SMART on FHIR

本部分介绍在 Cloud Healthcare API 中将 SMART on FHIR 与数据搭配使用所需执行的步骤。

配置 SMARTProxy

如果您使用的是自己的授权服务器，而不是 SMARTProxy，请跳过此部分并继续配置 Google Cloud 服务帐号。

SMARTProxy 是 Google 的开源代理，可提供以下功能：

允许 Cloud Healthcare API 接受并验证 SMART 访问令牌。
允许 Cloud Healthcare API 中的 FHIR 实现在 API 管理和权限模型中包含 SMART 访问令牌。

当您通过 SMARTProxy 从 Cloud Healthcare API 请求检索数据时，该请求会执行以下步骤：

SMARTProxy 接受来自客户端的包含 SMART 令牌的请求。
SMARTProxy 通过您的 JWT 授权服务器验证 SMART 令牌。
SMARTProxy 从 SMART 令牌中读取范围和患者上下文，并使用四个 HTTP 标头将它们传递给 Cloud Healthcare API。
Cloud Healthcare API 收到标头并进行验证，以对请求强制执行访问权限控制。然后，Cloud Healthcare API 会通过 SMARTProxy 向客户端返回响应。

配置 Google Cloud 服务账号

一个代理只能有一个 Google Cloud 服务帐号。如果多个客户端使用同一代理，则这些客户端必须使用相同的服务帐号。与多个客户端共享服务账号时，请务必小心，原因如下：

为了在 Cloud Healthcare API 中读取 FHIR 数据，服务账号具有广泛的读写权限。
Cloud Audit Logs 主电子邮件地址与服务账号相关联。

例如，如果您使用自己的 Google 帐号进行身份验证来调用 Cloud Healthcare API，则 Cloud Audit Logs 会将您的电子邮件地址记录为主帐号电子邮件地址。当您使用代理调用 Cloud Healthcare API 时，代理使用自己的服务帐号，且服务帐号的电子邮件地址是主帐号电子邮件地址，因此原始调用方会被遮盖。如需将最终用户保存到审核日志的元数据中，请在 JWT 令牌的 sub 字段中传入最终用户的电子邮件地址。

配置 FHIR 存储区

您无需配置包含您要访问的 FHIR 数据的 FHIR 存储区。

对 FHIR 请求发出 SMART 请求

本部分概述了 Cloud Healthcare API 中支持的 SMART on FHIR 方法，以及当您发出 SMART on FHIR 请求时如何强制执行资源访问权限。

发出请求时，您的授权服务器负责生成具有相关 SMART 授权范围和启动上下文的访问令牌。

支持的方法

Cloud Healthcare API 对所有 projects.locations.datasets.fhirStores.fhir 方法都支持 SMART on FHIR，但以下情况除外：

资源访问权限强制执行

向 FHIR 存储区发出 SMART on FHIR 请求时，访问权限控制按以下顺序实现：

Cloud Healthcare API 会检查代理中配置的 Google Cloud 服务账号的权限。如果该服务账号在 FHIR 存储区中具有正确的 IAM 权限，请求将继续。
Cloud Healthcare API 会验证 SMART 令牌是否具有适当的权限来访问请求请求的每个 FHIR 资源。

患者房间对 Cloud Healthcare API 中的访问强制执行逻辑至关重要。SMART on FHIR 具有有资格纳入患者隔离区的 FHIR 资源类型列表。资源类型也有自己的包含条件。在本节的其余部分中，符合条件的资源类型称为“符合患者隔离区条件的资源类型”。不符合条件的资源类型称为“不符合患者隔离区条件的资源类型”。

向 FHIR 存储区发出的 FHIR 请求 SMART 必须满足以下要求：

提供 SMART 授权范围内提的patient、user 或 system 角色。如果您提供 patient 角色，则必须提供患者上下文。患者上下文是患者资源逻辑 ID。患者资源必须已存在于 FHIR 存储区中，或者在请求发出后存在，否则 Cloud Healthcare API 会拒绝请求。
创建、读取、更新或删除资源时，resourceType 和操作类型（read 或 write）必须匹配，否则 Cloud Healthcare API 会拒绝请求。
如果您提供的 patient 范围包含不符合患者隔离区条件的资源类型（例如 patient/Practitioner.*），则范围验证检查会失败，并且 Cloud Healthcare API 会拒绝该范围。
您可以使用 user 范围设置所有资源类型。如果患者上下文存在 user 范围，则符合患者隔室条件的资源类型将局限于患者上下文。其余资源类型会忽略患者上下文。
如果存在患者上下文，则系统会将符合患者隔离区条件的资源类型限定用于给定患者。例如，观察对象资源必须具有 subject 字段引用给定患者资源，观察对象才能访问。请参阅 Resource CompartmentDefinition - Content（资源室定义 - 内容）中的患者隔室访问权限类型，了解每个病房内资源类型中的哪些字段必须引用给定患者，才能将资源视为病房内。
请求可以包含 patient 和 user 范围。
请勿将 system 范围与患者上下文一起使用，否则请求会失败。
请勿将 system 范围与 patient 范围或 user 范围一起使用。
如果您调用的方法访问多个资源（例如 fhir.Patient-everything、fhir.executeBundle 或 fhir.search），则访问权限控制适用于各个资源。