HealthLake 支援的 FHIR OAuth 2.0 範圍上的 SMART

HealthLake 使用 OAuth 2.0 做為授權通訊協定。在授權伺服器上使用此通訊協定可讓您為用戶端應用程式可存取的 FHIR 資源定義 HealthLake 資料存放區許可（建立、讀取、更新、刪除和搜尋）。

FHIR 上的 SMART 架構定義一組可以從授權伺服器請求的範圍。例如，僅設計為允許患者檢視其實驗室結果或檢視其聯絡詳細資訊的用戶端應用程式，應僅獲授權請求read範圍。

注意

HealthLake 同時支援 FHIR V1 和 V2 上的 SMART，如下所述。建立資料存放區時，SMART on FHIR AuthorizationStrategy會設定為下列三個值之一：

SMART_ON_FHIR_V1 – 僅支援 FHIR V1 上的 SMART，其中包含 read（讀取/搜尋）和 write(create/update/delete許可。
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 授權請求中的參數，請求在授權回應中傳回該病患資料。

HealthLake 的 FHIR 資源範圍上的 SMART

HealthLake 在 FHIR 資源範圍上定義三個層級的 SMART。

patient 範圍會授予單一病患特定資料的存取權。
user 範圍會授予使用者可存取的特定資料的存取權。
system 範圍會授予 HealthLake 資料存放區中所有 FHIR 資源的存取權。

下列各節列出使用 FHIR V1 上的 SMART 或 FHIR V2 上的 SMART 建構 FHIR 資源範圍的語法。

注意

建立資料存放區時，會設定 FHIR 上的 SMART 授權策略。如需詳細資訊，請參閱 AWS HealthLake API 參考AuthorizationStrategy中的。

HealthLake 支援的 FHIR V1 範圍上的 SMART

在 FHIR V1 上使用 SMART 時，用於建構 HealthLake 的 FHIR 資源範圍的一般語法如下。若要在下列範例中檢視整個 URL 路徑，請捲動至複製按鈕。


('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')

FHIR v1 支援的授權範圍上的 SMART
範圍語法	範例範圍	結果
`patient/(fhir-resource \| '').('read' \| 'write' \| '')`	`patient/AllergyIntolerance.*`	病患用戶端應用程式具有所有記錄的區分的執行個體層級讀取/寫入存取權。
`user/(fhir-resource \| '').('read' \| 'write' \| '')`	`user/Observation.read`	使用者用戶端應用程式具有所有記錄觀察的執行個體層級讀取/寫入存取權。
`system/('read' \| 'write' \| *)`	`system/.`	系統用戶端應用程式具有所有 FHIR 資源資料的讀取/寫入存取權。

HealthLake 支援的 FHIR V2 範圍上的 SMART

在 FHIR V2 上使用 SMART 時，用於建構 HealthLake 的 FHIR 資源範圍的一般語法如下。若要在下列範例中檢視整個 URL 路徑，請捲動至複製按鈕。


('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')

注意

若要在 FHIR V2 上使用 SMART，您必須將值傳入permission-v2中繼資料capabilities字串，這是 IdentityProviderConfiguration 資料類型的成員。

HealthLake 支援精細範圍。如需詳細資訊，請參閱 FHIR 美國核心實作指南中支援的精細範圍。

FHIR V2 支援的授權範圍上的 SMART
範圍語法	範例 V1 範圍	結果
`patient/Observation.rs`	`user/Observation.read`	讀取和搜尋目前病患`Observation`資源的許可。
`system/*.cruds`	`system/.`	系統用戶端應用程式具有所有 FHIR 資源資料的完整create/read/update/刪除/搜尋存取權。

HealthLake 支援的 FHIR V2.2 範圍上的 SMART

V2.2 使用以搜尋參數為基礎的篩選來擴展 V2 範圍。授權伺服器現在可以發出限制特定資料特性存取的範圍，而不只是根據資源類型和 CRUDS 操作。

V2 的所有內容保持不變。V2.2 純粹是附加的：

現有的 V2 範圍（不含篩選條件）會繼續像以前一樣運作。
V2 文法是以選用的?param=value查詢字串延伸。
範圍層級 (patient/user/system)、資源類型或 CRUDS 字母沒有變更。

先決條件

在 FHIR V2.2 上啟用 SMART 之前，請確定下列事項：

您的資料存放區已建立，並將 AuthorizationStrategy 設為 SMART_ON_FHIR（同時支援 V1 和 V2)。使用 SMART_ON_FHIR_V1或 AWS_AUTH 的資料存放區不符合資格。
您的資料存放區已包含在capabilities陣列permission-v2中。V2.2 是擴充 V2 時的附加項目，無法獨立使用。
您的 IDP Lambda 已設定為驗證並傳遞 V2.2 範圍格式（包含?查詢語法的範圍）。

啟用 V2.2

啟用路徑取決於您要建立新的資料存放區或更新現有的資料存放區。

新的資料存放區

建立新的資料存放區時，請將 permission-v2.2新增至 Metadata欄位中的 capabilities陣列IdentityProviderConfiguration：


"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]

現有資料存放區

若要在現有資料存放區上啟用 FHIR V2.2 上的 SMART，請將 permission-v2.2新增至 Metadata欄位中的capabilities陣列，IdentityProviderConfiguration並使用提交變更UpdateFHIRDatastore。如需詳細資訊，請參閱更新 HealthLake 資料存放區。

使用要求：

permission-v2 必須保留在陣列中。V2.2 擴展 V2，無法單獨使用。
AuthorizationStrategy 必須是 SMART_ON_FHIR（不是 SMART_ON_FHIR_V1或 AWS_AUTH)。
更新身分提供者組態會將其完全取代，因此請包含所有現有的欄位和功能以及 permission-v2.2。

變更會立即生效，沒有停機時間。若要驗證，請擷取探索文件（需要 SigV4)：


GET {healthlake-endpoint}/r4/.well-known/smart-configuration

如果回應中的capabilities陣列包含 permission-v2.2，則 FHIR V2.2 上的 SMART 會處於作用中狀態。

延伸範圍語法

V2 文法是以選用的查詢字串延伸：


V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]

V2.2 範圍查詢字串元件
元件	說明
`?param=value`	Search-parameter 篩選條件。只有符合此條件的資源才能存取。
`&param=value`	其他篩選條件。多個篩選條件是 ANDed – 所有篩選條件都必須相符。

規則：

篩選條件僅適用於範圍中指定的資源類型。不支援萬用字元 (*) 搭配篩選條件。
參數必須根據您資料存放區的搜尋組態對資源類型有效（透過檢查GET /r4/metadata)。
完整範圍字串（例如 patient/Observation.rs?category=laboratory) 是出現在 OAuth 2.0 範圍參數和存取字符scp宣告中的常值。
授權請求中每個 RFC 6749 的 URL | 編碼特殊字元（例如 → %7C)。
對於日期、數字和數量參數，V2.2 支援字首比較器（例如 ?date=eq2023-01-01)。V2.2 也支援搜尋參數修改程式。

範圍範例

V2.2 範圍範例
Scope (範圍)	授予的存取
`patient/DiagnosticReport.rs?category=LAB`	只有 `category`為 `DiagnosticReport`的資源`LAB`。
`patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R`	只有具有安全標籤 `Observation`的資源`Restricted`。
`patient/Observation.rs?date=ge2023-01-01`	只有日期為 2023 年 1 月 1 日或之後`Observation`的資源。
`patient/Observation.rs?category=laboratory&status=final`	只有實驗室 AND 最終版`Observation`的資源。
`user/Condition.rs?clinical-status=active`	只有作用中`Condition`的資源。

強制執行行為

當字符包含 V2.2 範圍時，HealthLake 會套用每個操作的篩選條件：

每個操作的 V2.2 強制執行
作業	Behavior (行為)
讀取 (`r`)	只有在資源符合所有範圍篩選條件時，才會成功。否則會傳回 403。
搜尋 (`s`)	範圍篩選條件與查詢相交。只會傳回相符的資源。
建立/更新 (`c`/`u`)	資源必須符合範圍篩選條件才能寫入。否則會傳回 403。
刪除 (`d`)	目標資源必須符合範圍篩選條件。否則會傳回 403。

範圍優先順序

相同資源類型的多個 V2.2 範圍會聯集（跨範圍的 OR)。
沒有篩選條件的更廣泛 V2 範圍（例如 patient/Observation.rs) 會授予完整存取權，無論相同權杖中任何更窄的 V2.2 範圍為何。
未permission-v2.2啟用的資料存放區上的 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)。

疑難排解
徵狀	原因	修正
無法辨識字符範圍	資料存放區上未啟用 V2.2	透過支援票證檢查`/.well-known/smart-configuration`並請求啟用。
資源上存在的 403	資源不符合範圍篩選條件	根據範圍參數驗證資源值。
空的搜尋結果	範圍篩選條件比查詢更窄	結果是查詢和範圍篩選條件的交集。
`InvalidScope` 錯誤	範圍內的無效搜尋參數	透過 `/metadata` CapabilityStatement 確認參數。

端對端範例

案例：患者應用程式應僅顯示 2023 年以後的最終實驗室結果。

具有範圍的授權伺服器問題字符：


patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01

用戶端呼叫 HealthLake：


GET {endpoint}/r4/Observation?patient=Patient/123

HealthLake 會強制執行範圍篩選條件。回應僅包含 category=laboratory AND status=final 和 date ≥ 2023-01-01 – 即使用戶端請求所有觀察Observation。

文件慣用形式

身分驗證

字符驗證