本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # SMART on FHIR OAuth 2.0 瞄准镜支持 HealthLake HealthLake 使用 OAuth 2.0 作为授权协议。在授权服务器上使用此协议可以定义客户端应用程序有权访问的 FHIR 资源 HealthLake 的数据存储权限（创建、读取、更新、删除和搜索）。 SMART on FHIR 框架定义了一组可以向授权服务器请求的范围。例如，仅允许患者查看实验室结果或查看其联系方式的客户端应用程序应仅被*授权*申请`read`示波器。 **注意** HealthLake 为 FHIR V1 和 V2 上的 SMART 提供支持，如下所述。创建数据存储时，FH [`AuthorizationStrategy`](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)IR 上的 SMART 设置为以下三个值之一： `SMART_ON_FHIR_V1`— 在 FHIR V1 上仅支持 SMART，其中包括 `read` (read/search) 和 `write` (create/update/删除) 权限。 `SMART_ON_FHIR`— 在 FHIR V1 和 V2 上支持 SMART，其中包括`create`、、`read``update``delete`、和权限。`search` `AWS_AUTH`— 默认 AWS HealthLake 授权策略；与 FHIR 上的 SMART 无关。 ## 独立发布范围 HealthLake 支持独立启动模式范围`launch/patient`。 在独立启动模式下，客户端应用程序请求访问患者的临床数据，因为客户端应用程序不知道用户和患者。因此，客户端应用程序的授权请求明确要求返回患者范围。成功进行身份验证后，授权服务器会发出包含请求的启动患者范围的访问令牌。所需的患者环境与访问令牌一起在授权服务器的响应中提供。 **支持的启动模式范围** | Scope | 说明 | | --- | --- | | `launch/patient` | OAuth 2.0 授权请求中的一个参数，请求在授权响应中返回患者数据。 | ## SMART 对 FHIR 的资源范围适用于 HealthLake HealthLake 在 FHIR 资源范围上定义了三个级别的 SMART。 + `patient`范围允许访问有关单个患者的特定数据。 + `user`作用域授予用户可以访问的特定数据的访问权限。 + `system`作用域授予对在 HealthLake 数据存储中找到的所有 FHIR 资源的访问权限。 以下各节列出了在 FHIR V1 上使用 SMART 或在 FHIR V2 上使用 SMART 构建 FHIR 资源范围的语法。 **注意** SMART on FHIR 授权策略是在创建数据存储时设置的。有关更多信息，请参阅《AWS HealthLake API Reference》**中的 [`AuthorizationStrategy`](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)。 ### 支持 FHIR V1 瞄准镜的 SMART HealthLake 在 FHIR V1 上使用 SMART 时，构建 FHIR 资源范围的通用语法如下。 HealthLake 要查看以下示例中的整个 URL 路径，请滚动到 “**复制**” 按钮。 ``` ('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*') ``` **SMART on FHIR v1 支持的授权范围** | 作用域语法 | 示例：作用域 | 结果 | | --- | --- | --- | | `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\* | 患者客户端应用程序具有对所有记录的过敏症的实例级 read/write访问权限。 | | `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | 用户客户端应用程序具有对所有记录的观察结果的实例级 read/write 访问权限。 | | system/('read' \| 'write' \| \*) | system/\*.\* | 系统客户端应用程序 read/write 可以访问所有 FHIR 资源数据。 | ### 支持 FHIR V2 瞄准镜的 SMART HealthLake 在 FHIR V2 上使用 SMART 时，构建 FHIR 资源范围的通用语法如下。 HealthLake 要查看以下示例中的整个 URL 路径，请滚动到 “**复制**” 按钮。 ``` ('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's') ``` **注意** 要在 FHIR V2 上使用 SMART，必须[`permission-v2`](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)将值传递到元数据`capabilities`字符串中，该字符串是[`IdentityProviderConfiguration`](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)数据类型的成员。 HealthLake 支持精细作用域。有关更多信息，请参阅《*FHIR 美国核心实施*指南》中[支持的粒度范围](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported)。 **SMART on FHIR V2 支持的授权范围** | 作用域语法 | 示例 V1 作用域 | 结果 | | --- | --- | --- | | `patient/Observation.rs` | user/Observation.read | 允许读取和搜索当前患者的Observation资源。 | | `system/*.cruds` | system/\*.\* | 系统客户端应用程序对所有 FHIR 资源数据具有完全 create/read update/delete //search访问权限。 | ### 支持 FHIR V2.2 瞄准镜的 SMART HealthLake V2.2 通过基于搜索参数的筛选扩展了 V2 范围。授权服务器现在可以发布通过特定数据特征而不仅仅是资源类型和 CRUDS 操作来限制访问的范围。 V2 中的所有内容都保持不变。 V2.2 纯粹是添加剂： + 现有的 V2 作用域（不带过滤器）继续像以前一样工作。 + 使用可选的`?param=value`查询字符串对 V2 语法进行了扩展。 + 范围级别 (`patient`/`user`/`system`)、资源类型或 CRUDS 字母没有变化。 #### 先决条件 在 FHIR 上启用 SMART 之前 V2.2，请确保满足以下条件： + 您的数据存储是在`AuthorizationStrategy`设置为`SMART_ON_FHIR`（同时支持 V1 和 V2）的情况下创建的。使用`SMART_ON_FHIR_V1`或`AWS_AUTH`不符合条件的数据存储。 + 您的数据存储已包含`permission-v2`在`capabilities`数组中。 V2.2 是可加的，因为它扩展了 V2，不能单独使用。 + 您的 IDP Lambda 已配置为验证和传递 V2.2范围格式（`?`包含查询语法的范围）。 #### 正在启用 V2.2 启用路径取决于您是在创建新的数据存储还是更新现有数据存储。 ##### 新的数据存储 创建新的数据存储时，请将以下`Metadata`字段`permission-v2.2`添加到`capabilities`数组中 [`IdentityProviderConfiguration`](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)： ``` "capabilities": [ "launch-ehr", "sso-openid-connect", "client-public", "permission-v2", "permission-v2.2" ] ``` ##### 现有数据存储 要在现有数据存储上启用 SMART V2.2 on FHIR，请在的`Metadata`字段中添加`permission-v2.2``capabilities`数组[`IdentityProviderConfiguration`](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)并使用`UpdateFHIRDatastore`提交更改。有关更多信息，请参阅 [更新 HealthLake 数据存储](managing-data-stores-update.md)。 要求： + `permission-v2`必须保留在数组中。 V2.2 扩展了 V2，不能单独使用。 + `AuthorizationStrategy`必须是`SMART_ON_FHIR`（不是`SMART_ON_FHIR_V1`或`AWS_AUTH`）。 + 更新身份提供商配置会将其全部替换，因此请同时包括所有现有字段和功能`permission-v2.2`。 更改会立即生效，无需停机。要进行验证，请获取[发现文档](reference-smart-on-fhir-discovery-document.md)（需要 Sigv4）： ``` GET {healthlake-endpoint}/r4/.well-known/smart-configuration ``` 如果响应中的`capabilities`数组包括`permission-v2.2`，则 FHIR 上的 SMART V2.2 处于活动状态。 #### 扩展作用域语法 V2 语法使用可选的查询字符串进行了扩展： ``` V2: (patient|user|system) / resource . cruds V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]] ``` **V2.2 作用域查询字符串组件** | 组件 | 说明 | | --- | --- | | `?param=value` | Search-parameter 过滤器。只有符合此标准的资源才可访问。 | | `¶m=value` | 其他过滤器。多个过滤器采用 AND 运算 — 所有过滤器都必须匹配。 | 规则： + 过滤器仅适用于作用域中指定的资源类型。不支持带过滤器的通配符 (`*`)。 + 根据数据存储的搜索配置，参数必须对资源类型有效（通过`GET /r4/metadata`）。 + 完整的作用域字符串（例如`patient/Observation.rs?category=laboratory`）是出现在 OAuth 2.0 范围参数和访问令牌声明中的文字值。`scp` + URL-encode 授权请求中符合 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) 的特殊字符（例如，`|`→`%7C`）。 + 对于日期、数字和数量参数， V2.2 支持前缀[比较器](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators)（例如，`?date=eq2023-01-01`）。 V2.2 还支持[搜索参数修饰符](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers)。 #### 作用域示例 **V2.2 作用域示例** | Scope | 已授予访问权限 | | --- | --- | | `patient/DiagnosticReport.rs?category=LAB` | 只有`DiagnosticReport`资源在`category`哪里`LAB`。 | | `patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R` | 仅限带有安全标签的`Observation`资源`Restricted`。 | | `patient/Observation.rs?date=ge2023-01-01` | 仅限日期`Observation`为 2023 年 1 月 1 日当天或之后的资源。 | | `patient/Observation.rs?category=laboratory&status=final` | 仅限实验室和最终版本的`Observation`资源。 | | `user/Condition.rs?clinical-status=active` | 仅限活跃`Condition`资源。 | #### 执法行为 当令牌包含 V2.2 作用域时，会按操作 HealthLake 应用筛选条件： **V2.2 每次行动强制执行** | 操作 | 行为 | | --- | --- | | 阅读 (`r`) | 仅当资源与所有作用域过滤器匹配时才会成功。否则返回 403。 | | 搜索 (`s`) | 范围过滤器与查询相交。仅返回匹配的资源。 | | Create/Update (`c`/`u`) | 资源必须满足作用域过滤器才能写入。否则返回 403。 | | 删除 (`d`) | 目标资源必须与范围过滤器匹配。否则返回 403。 | ##### 作用域优先级 + 同一资源类型的多个 V2.2 作用域已合并（或者跨作用域）。 + 不带过滤器的更宽的 V2 作用域（例如`patient/Observation.rs`），无论同一个令牌中的 V2.2 范围是否较窄，都将授予完全访问权限。 + V2.2 未`permission-v2.2`启用的数据存储上的作用域将被静默忽略。 #### 限制 V2.2 作用域过滤器不支持以下内容： + 复合搜索参数（例如，`code-value-quantity`）。 + 链式搜索参数（例如，`subject:Patient.name=Smith`）。 + `_include`/`_revinclude`搜索参数。 + `$export`/`$davinci-data-export`（批量数据）- V2.2 筛选器不适用；批量导出使用 V2 范围。 + 与过滤器组合的通配符资源类型（例如，`patient/*.rs?category=LAB`无效）。使用搜索参数筛选器时，必须指定明确的资源类型（例如）。`patient/Observation.rs?category=LAB` **问题排查** | 症状 | 原因 | Fix | | --- | --- | --- | | 无法识别令牌范围 | V2.2 未在数据存储上启用 | 通过支持票证检查`/.well-known/smart-configuration`并申请启用。 | | 在存在的资源上使用 403 | 资源与作用域过滤器不匹配 | 根据范围参数验证资源值。 | | 搜索结果为空 | 范围过滤器比查询更窄 | 结果是查询和范围筛选器的交集。 | | `InvalidScope`错误 | 范围内的搜索参数无效 | 通过确认参数`/metadata` CapabilityStatement。 | #### End-to-end 示例 场景：患者应用程序应仅显示 2023 年以后的最终实验室结果。 1. 授权服务器发布的令牌的作用域为： ``` patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01 ``` 1. 客户来电 HealthLake： ``` GET {endpoint}/r4/Observation?patient=Patient/123 ``` 1. HealthLake 强制使用范围过滤器。尽管客户端请求了所有观测值，但响应仅包含 AND `category=laboratory` `status=final` 和 `date ≥ 2023-01-01` AND 的`Observation`资源。