SMART on FHIR を使用してアプリケーションに接続する

このページでは、SMART（Substittable Medical Applications、Reusable Technologies）on FHIR v1.1.0 標準を使用して Cloud Healthcare API の FHIR ストアにあるデータにアクセスする方法について説明します。

概要

SMART on FHIR は、アプリケーションが電子ヘルスレコード（EHR）システムの情報にアクセスできるようにするデータ標準規格です。アプリケーション デベロッパーは、標準を採用した EHR システムに接続する単一のアプリケーションを作成できます。

たとえば、Cloud Healthcare API の FHIR ストアに患者データが保存されている場合は、次のことを行うアプリケーションを開発できます。

  1. FHIR ストアに対して認証を行う。
  2. 患者のデータを取得する。
  3. 患者データをユーザー インターフェースに表示する。

SMART on FHIR は、認可と認証に対して OpenID と OAuth 2.0 の承認モデルをサポートしています。

SMART App Launch Framework、スコープ、起動コンテキスト

Cloud Healthcare API は、SMART App Launch Framework、スコープ、起動コンテキストを次のようにサポートしています。

SMART App Launch Framework

Cloud Healthcare API は、SMART App Launch Framework からのスタンドアロン起動シーケンスをサポートしています。

アプリは、既存の EHR システムまたは患者ポータルのセッション内から起動できます。これらはいずれも、「EHR リリース」またはスタンドアロン アプリと呼ばれます。

スコープ

臨床データスコープは、患者固有のアクセスとユーザーレベルのアクセスに対する読み取りと書き込みの権限を定義します。Cloud Healthcare API は、臨床データをリクエストするためのスコープで定義されている次のデータスコープをサポートしています。

  • patient
  • user
  • system
起動コンテキスト

リクエストが作成されている現在の患者、近接、またはその他のコンテキストについて説明します。Cloud Healthcare API は、コンテキスト データをリクエストするスコープからの患者の起動コンテキストをサポートしています。

SMART on FHIR 用認可サーバーの構成

Cloud Healthcare API は、入力 SMART 承認スコープと患者のコンテキストに基づいて、SMART on FHIR アクセス適用のための組み込みサポートを提供しています。FHIR ストア管理者は、SMART 承認スコープと患者コンテキストを許可する Cloud Healthcare API の外部で認可サーバーを作成、構成します。

クライアント アプリケーションが、許可された 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 承認スコープの形式を使用する 1 つ以上の承認スコープ。たとえば、認証スコープを user/Observation.read に設定すると、リクエストは Observation リソースのみを読み取ることができます。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 承認スコープと、必要に応じて患者コンテキストが含まれます。Cloud Healthcare API には、認可サーバーが SMART JWT トークンを作成する方法に関する特定の要件はありません。たとえば、アプリケーションがスコープのサブセットに登録されている場合や、患者コンテキストを設定するために患者選択ウィジェットが表示されている場合があります。

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 アクセス トークンを受け入れ、検証できる機能。
  • API の管理モデルと権限モデルの一環として、Cloud Healthcare API の FHIR 実装に SMART アクセス トークンを含めることができる機能。

SMARTProxy を介して Cloud Healthcare API からのデータ取得をリクエストすると、リクエストは次の手順を実行します。

  1. SMARTProxy は、クライアントからの SMART トークンを含むリクエストを受け入れます。
  2. SMARTProxy は、JWT 認可サーバーを介して SMART トークンを検証します。
  3. SMARTProxy は、SMART トークンからスコープと患者のコンテキストを読み取り、4 つの HTTP ヘッダーを使用して Cloud Healthcare API に渡します。
  4. Cloud Healthcare API はヘッダーを受け取り、検証して、リクエストでアクセス制御を適用します。その後、Cloud Healthcare API は SMARTProxy を介してクライアントにレスポンスを返します。

Google Cloud サービス アカウントを構成する

プロキシに含めることができる Google Cloud サービス アカウントは 1 つのみです。複数のクライアントが同じプロキシを使用する場合、クライアントは同じサービス アカウントを使用する必要があります。サービス アカウントを複数のクライアントと共有する場合は注意が必要です。理由は次のとおりです。

  • Cloud Healthcare API の FHIR データを読み取るために、サービス アカウントには幅広い読み取り権限と書き込み権限があります。

  • Cloud Audit Logs のプリンシパル メールアドレスは、サービス アカウントに結び付けられています。

    たとえば、認証に Google アカウントを使用して Cloud Healthcare API を呼び出した場合、Cloud Audit Logs はメールアドレスをプリンシパル メールアドレスとして記録します。プロキシを使用して Cloud Healthcare API を呼び出す場合、プロキシは独自のサービス アカウントを使用します。サービス アカウントのメールアドレスはプリンシパルのメールアドレスであるため、元の呼び出し元は難読化されます。エンドユーザーを監査ログのメタデータに保存するには、JWT トークンの sub フィールドにエンドユーザーのメールアドレスを渡します。

FHIR ストアを構成する

アクセスしている FHIR データを保持する FHIR ストアを構成する必要はありません。

SMART on FHIR リクエストの実行

このセクションでは、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 リクエストを実行すると、次の順序でアクセス制御が行われます。

  1. Cloud Healthcare API は、プロキシで構成された Google Cloud サービス アカウントの権限を確認します。サービス アカウントに FHIR ストアに対する正しい IAM 権限がある場合、リクエストは続行されます。
  2. Cloud Healthcare API は、リクエストが要求する　FHIR　リソースにアクセスするための適切な権限が SMART トークンにあるかどうかを確認します。

患者コンパートメントは、Cloud Healthcare API のアクセス適用ロジックにとって非常に重要です。SMART on FHIR には、患者コンパートメントに含めることができる FHIR リソースタイプのリストがあります。リソースタイプにも独自の包括基準があります。このセクションの残りの部分では、有効なリソースタイプを「患者コンパートメントが有効なリソースタイプ」と呼びます。有効でないリソースタイプは、「患者コンパートメントが無効なリソースタイプ」と呼びます。

FHIR ストアへの SMART on FHIR リクエストは、次の要件を満たす必要があります。

  • SMART 承認スコープで、patient、user、または system のロールを指定します。patient ロールを指定する場合は、患者コンテキストを指定する必要があります。患者のコンテキストは、患者リソースの論理 ID です。患者リソースは、FHIR ストアに存在しているか、リクエスト後に存在している必要があります。存在しない場合、Cloud Healthcare API はリクエストを拒否します。

  • リソースの作成、読み取り、更新、削除を行う場合、resourceType とオペレーションのタイプ（read または write）が一致する必要があります。一致しない場合、Cloud Healthcare API によってリクエストが拒否されます。

  • patient/Practitioner.* などの患者コンパートメントが有効なリソースタイプが含まれる patient スコープを指定した場合、スコープの検証確認が失敗し、Cloud Healthcare API によってスコープが拒否されます。

  • すべてのリソースタイプを user スコープで設定できます。患者コンテキストが user スコープにある場合、患者コンパートメントに適したリソースタイプは患者コンテキストに制限されます。残りのリソースタイプは、患者コンテキストを無視します。

  • 患者のコンテキストが存在する場合は、患患者コンパートメントが有効なリソースタイプを特定の患者に制限します。たとえば、特定の患者リソースが Observation にアクセスできるようにするには、Observation リソースに subject フィールド参照が存在する必要があります。患者コンパートメントのアクセスの種類については、リソース コンパートメントの定義 - コンテンツで、患者コンパートメント内のリソースを検討するために、各患者コンパートメントのリソースタイプでどのフィールドを特定の患者に参照する必要があるのかを示すリストをご確認ください。

  • リクエストには patient スコープと user スコープの両方を含めることができます。

  • 患者コンテキストとともに system スコープを使用しないでください。そうしないと、リクエストは失敗します。

  • system スコープを patient スコープまたは user スコープと一緒に使用しないでください。

  • 複数のリソースにアクセスするメソッドを呼び出す場合（例: fhir.Patient-everything、fhir.executeBundle、fhir.search）、それぞれ個別のリソースにアクセス制御が適用されます。