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）、それぞれ個別のリソースにアクセス制御が適用されます。