SMART on FHIR을 사용하여 애플리케이션에 연결

이 페이지에서는 FHIR v1.1.0 표준에서 SMART(대체 가능 의료 애플리케이션, 재사용 가능한 기술)을 사용하여 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 앱 실행 프레임워크, 범위, 실행 컨텍스트

Cloud Healthcare API는 다음과 같이 SMART 앱 실행 프레임워크, 범위, 실행 컨텍스트를 지원합니다.

SMART 앱 실행 프레임워크

Cloud Healthcare API는 SMART 앱 실행 프레임워크의 독립형 실행 시퀀스를 지원합니다.

앱은 기존 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 승인 범위 형식을 사용하는 하나 이상의 승인 범위입니다. 예를 들어 승인 범위를 user/Observation.read로 설정하면 요청이 관찰 리소스에 대해 읽기만 수행할 수 있습니다. Cloud Healthcare API는 이러한 액세스 제어를 적용합니다.
  • X-Authorization-Patient: 요청의 환자 컨텍스트입니다. 이 헤더를 설정한 경우 요청에서 환자 구획에 적격한 리소스 유형이 제공된 환자 ID의 환자 구획에 속해야 합니다. Cloud Healthcare API는 이러한 액세스 제어를 적용합니다.
  • X-Authorization-Subject: SMART on FHIR 클라이언트 애플리케이션에 액세스하는 최종 사용자에 대한 식별자입니다. 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 액세스 토큰을 수락하고 검증할 수 있도록 합니다.
  • Cloud Healthcare API의 FHIR 구현이 API 관리 및 권한 모델의 일부로서 SMART 액세스 토큰을 포함할 수 있게 합니다.

사용자가 SMARTProxy를 통해 Cloud Healthcare API에서 데이터를 검색하도록 요청하면, 요청은 다른 단계를 따릅니다.

  1. SMARTProxy가 클라이언트의 SMART 토큰이 포함된 요청을 수락합니다.
  2. SMARTProxy는 JWT 승인 서버를 통해 SMART 토큰을 검증합니다.
  3. SMARTProxy가 SMART 토큰의 범위와 환자 컨텍스트를 읽고 HTTP 헤더를 통해 Cloud Healthcare API로 전달합니다.
  4. Cloud Healthcare API는 헤더를 수신하고 이를 검증하여 요청에 대해 액세스 제어를 적용합니다. 그런 후 Cloud Healthcare API가 SMARTProxy를 통해 클라이언트에 응답을 반환합니다.

Google Cloud 서비스 계정 구성

프록시에는 Google Cloud 서비스 계정이 하나만 포함될 수 있습니다. 여러 클라이언트에 동일한 프록시가 사용되는 경우 클라이언트는 동일한 서비스 계정을 사용해야 합니다. 다음과 같은 이유로 여러 클라이언트와 서비스 계정을 공유할 때는 주의해야 합니다.

  • Cloud Healthcare API에서 FHIR 데이터를 읽기 위해 서비스 계정은 광범위한 읽기 및 쓰기 권한을 가집니다.

  • Cloud 감사 로그 기본 이메일 주소가 서비스 계정에 연결됩니다.

    예를 들어 인증을 위해 Google 계정을 사용하여 Cloud Healthcare API를 호출할 경우 Cloud 감사 로그가 이메일 주소를 기본 이메일 주소로 로깅합니다. 프록시를 사용하여 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는 SMART 토큰의 권한이 해당 요청의 각 FHIR 리소스에 액세스하기에 적합한지 여부를 확인합니다.

환자 구획은 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 범위에 제공된 경우 환자 구획 적격 리소스 유형이 환자 컨텍스트로 제한됩니다. 남은 리소스 유형은 환자 컨텍스트를 무시합니다.

  • 환자 컨텍스트가 있으면 환자 구획 적격 리소스 유형을 지정된 환자로 제한합니다. 예를 들어 관찰 리소스에 액세스하기 위해서는 지정된 환자 리소스를 참조하는 subject 필드가 관찰에 존재해야 합니다. 각 환자 구획 리소스 유형에서 주어진 환자에 대해 환자 구획 내의 어떤 필드를 참조해야 할지 목록을 보려면 Resource CompartmentDefinition - Content를 확인하세요.

  • 요청은 patient 및 user 범위를 모두 포함할 수 있습니다.

  • 환자 컨텍스트에는 system 범위를 사용하지 마세요. 그러지 않으면 요청이 실패합니다.

  • system 범위는 patient 범위 또는 user 범위와 함께 사용하지 마세요.

  • 여러 리소스(예를 들어 fhir.Patient-everything, fhir.executeBundle, 또는 fhir.search 메서드)에 액세스하는 메서드를 호출하는 경우 액세스 제어가 개별 리소스에 적용됩니다.