翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # HealthLake でサポートされている FHIR OAuth 2.0 スコープでの SMART HealthLake は認可プロトコルとして OAuth 2.0 を使用します。認可サーバーでこのプロトコルを使用すると、クライアントアプリケーションがアクセスできる FHIR リソースの HealthLake データストアのアクセス許可 (作成、読み取り、更新、削除、検索) を定義できます。 SMART on FHIR フレームワークは、認可サーバーからリクエストできる一連のスコープを定義します。例えば、患者が検査結果を表示したり、連絡先の詳細を表示したりできるようにのみ設計されたクライアントアプリケーションは、`read`スコープをリクエストする*権限*のみを持つ必要があります。 **注記** HealthLake は、以下で説明するように、FHIR V1 と V2 の両方で SMART をサポートします。SMART on FHIR [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)は、データストアの作成時に次の 3 つの値のいずれかに設定されます。 `SMART_ON_FHIR_V1` – (読み取り/検索) および `read` (`write`create/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 リファレンス*[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-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 を使用するには、 値を[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)データ型のメンバーであるメタデータ`capabilities`文字列[https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions)に渡す必要があります。 HealthLake はきめ細かなスコープをサポートしています。詳細については、*「FHIR 米国コア実装ガイド*[」の「サポートされている詳細なスコープ](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported)」を参照してください。 **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`に を追加します[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)。 ``` "capabilities": [ "launch-ehr", "sso-openid-connect", "client-public", "permission-v2", "permission-v2.2" ] ``` ##### 既存のデータストア 既存のデータストアで FHIR V2.2 で SMART を有効にするには、 の `Metadata`フィールドの `capabilities` 配列`permission-v2.2`に を追加[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](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`。 + ID プロバイダー設定を更新すると、ID プロバイダー設定が完全に置き換えられるため、既存のすべてのフィールドと機能を とともに含めます`permission-v2.2`。 変更はダウンタイムなしですぐに有効になります。確認するには、 を取得します [検出ドキュメント](reference-smart-on-fhir-discovery-document.md) (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 フィルター。この条件に一致するリソースのみにアクセスできます。 | | `¶m=value` | 追加のフィルター。複数のフィルターは ANDed です。すべて一致する必要があります。 | ルール: + フィルターは、スコープで指定されたリソースタイプにのみ適用されます。フィルター付きのワイルドカード (`*`) はサポートされていません。 + パラメータは、データストアの検索設定に従ってリソースタイプに対して有効である必要があります ( で確認`GET /r4/metadata`)。 + フルスコープ文字列 ( など`patient/Observation.rs?category=laboratory`) は、OAuth 2.0 スコープパラメータとアクセストークン`scp`クレームに表示されるリテラル値です。 + 認可リクエストの [RFC 6749 ](https://datatracker.ietf.org/doc/html/rfc6749)あたりの URL エンコード特殊文字 ( `|` → など`%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 スコープの例** | スコープ | 付与されたアクセス | | --- | --- | | `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 年以降の確定された検査結果のみが表示されます。 1. 認可サーバーは スコープでトークンを発行します。 ``` patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01 ``` 1. クライアントが HealthLake を呼び出します。 ``` GET {endpoint}/r4/Observation?patient=Patient/123 ``` 1. HealthLake はスコープフィルターを適用します。レスポンスには、クライアントがすべての観測値をリクエストしたにもかかわらず`category=laboratory`、AND `status=final` AND `date ≥ 2023-01-01` の`Observation`リソースのみが含まれます。