スタンドアロン起動スコープ HealthLake の FHIR リソーススコープに関する SMART

HealthLake でサポートされている FHIR OAuth 2.0 スコープでの SMART

HealthLake は認可プロトコルとして OAuth 2.0 を使用します。認可サーバーでこのプロトコルを使用すると、クライアントアプリケーションがアクセスできる FHIR リソースの HealthLake データストアのアクセス許可 (作成、読み取り、更新、削除、検索) を定義できます。

SMART on FHIR フレームワークは、認可サーバーからリクエストできる一連のスコープを定義します。例えば、患者が検査結果を表示したり、連絡先の詳細を表示したりできるようにのみ設計されたクライアントアプリケーションは、readスコープをリクエストする権限のみを持つ必要があります。

注記

HealthLake は、以下で説明するように、FHIR V1 と V2 の両方で SMART をサポートします。SMART on FHIR AuthorizationStrategyは、データストアの作成時に次の 3 つの値のいずれかに設定されます。

SMART_ON_FHIR_V1 – (読み取り/検索) および read (writecreate/update/delete) アクセス許可を含む FHIR V1 での SMART のみをサポートします。
SMART_ON_FHIR – 、、、create、およびアクセスsearch許可を含む FHIR V1 deleteおよび V2 での SMART read updateのサポート。
AWS_AUTH – default AWS HealthLake 認可戦略。FHIR 上の SMART とは関連していません。

スタンドアロン起動スコープ

HealthLake は、スタンドアロン起動モードスコープをサポートしていますlaunch/patient。

スタンドアロン起動モードでは、ユーザーと患者がクライアントアプリケーションに知られていないため、クライアントアプリケーションは患者の臨床データへのアクセスをリクエストします。したがって、クライアントアプリケーションの認可リクエストは、患者スコープが返されることを明示的に要求します。認証が成功すると、認可サーバーはリクエストされた起動患者スコープを含むアクセストークンを発行します。必要な患者コンテキストは、認可サーバーのレスポンスでアクセストークンとともに提供されます。

サポートされている起動モードスコープ
スコープ	説明
`launch/patient`	OAuth 2.0 認可リクエストのパラメータ。認可レスポンスで患者データが返されるように要求します。

HealthLake の FHIR リソーススコープに関する SMART

HealthLake は、FHIR リソーススコープで 3 つのレベルの SMART を定義します。

patient スコープは、単一の患者に関する特定のデータへのアクセスを許可します。
user スコープは、ユーザーがアクセスできる特定のデータへのアクセスを許可します。
system スコープは、HealthLake データストアにあるすべての FHIR リソースへのアクセスを許可します。

以下のセクションでは、SMART on FHIR V1 または SMART on FHIR V2 を使用して FHIR リソーススコープを構築するための構文を一覧表示します。

注記

SMART on FHIR 認可戦略は、データストアの作成時に設定されます。詳細については、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 を使用するには、値をIdentityProviderConfigurationデータ型のメンバーであるメタデータcapabilities文字列permission-v2に渡す必要があります。

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 の有効化

有効化パスは、新しいデータストアを作成するか、既存のデータストアを更新するかによって異なります。

新しいデータストア

新しいデータストアを作成するときは、の Metadataフィールドのcapabilities配列permission-v2.2にを追加しますIdentityProviderConfiguration。


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

既存のデータストア

既存のデータストアで FHIR V2.2 で SMART を有効にするには、の Metadataフィールドの capabilities 配列permission-v2.2にを追加IdentityProviderConfigurationし、で変更を送信しますUpdateFHIRDatastore。詳細については、「HealthLake データストアの更新」を参照してください。

要件:

permission-v2 は配列にとどまる必要があります。V2.2 は V2 を拡張し、単独で使用することはできません。
AuthorizationStrategy は SMART_ON_FHIR ( SMART_ON_FHIR_V1またはではなく) である必要がありますAWS_AUTH。
ID プロバイダー設定を更新すると、ID プロバイダー設定が完全に置き換えられるため、既存のすべてのフィールドと機能をとともに含めますpermission-v2.2。

変更はダウンタイムなしですぐに有効になります。確認するには、を取得します検出ドキュメント (SigV4 が必要です）。


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

レスポンスのcapabilities配列にが含まれている場合permission-v2.2、SMART on FHIR 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 フィルター。この条件に一致するリソースのみにアクセスできます。
`&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 スコープの例
スコープ	付与されたアクセス
`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`	ラボと最終の`Observation`リソースのみ。
`user/Condition.rs?clinical-status=active`	アクティブな`Condition`リソースのみ。

強制動作

トークンに V2.2 スコープが含まれている場合、HealthLake はオペレーションごとにフィルターを適用します。

オペレーションあたりの V2.2 の適用
運用	動作
読み取り (`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)。

トラブルシューティング
症状	原因	Fix
トークンスコープが認識されない	データストアで 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 AND date ≥ 2023-01-01 のObservationリソースのみが含まれます。

ドキュメントの表記規則

認証

トークンの検証