다음을 통해 공유

SMART on FHIR

  • 아티클

대체 가능한 의료 애플리케이션 및 재사용 가능한 기술(SMART on FHIR)은 애플리케이션이 데이터 저장소를 통해 임상 정보에 액세스할 수 있는 의료 표준입니다. OAuth2 및 OpenID Connect를 비롯한 개방형 표준을 기반으로 하는 보안 계층을 FHIR® 인터페이스에 추가하여 EHR 시스템과 통합할 수 있도록 합니다. SMART on FHIR을 사용하면 다음 세 가지 이상의 중요한 이점이 제공됩니다.

  • 애플리케이션에는 FHIR 리포지토리에 대한 인증/권한을 얻는 알려진 방법이 있습니다.
  • SMART on FHIR을 사용하여 FHIR 리포지토리에 액세스하는 사용자는 리포지토리의 모든 데이터에 액세스하지 않고 사용자와 연결된 리소스로 제한됩니다.
  • 사용자는 SMART 임상 범위를 사용하여 애플리케이션에 제한된 데이터 집합에 대한 액세스 권한을 부여할 수 있습니다.

다음 자습서에서는 FHIR 서비스에서 SMART on FHIR 애플리케이션을 사용하도록 설정하는 단계를 제공합니다.

필수 조건

Azure Health Data Services 샘플을 사용하는 SMART on FHIR(SMART on FHIR(Enhanced))

1단계: FHIR SMART 사용자 역할 설정

사용자 관리: 역할 사용자 할당 섹션에 나열된 단계를 따릅니다. 이 역할에 추가된 모든 사용자는 요청이 SMART on FHIR 구현 가이드를 준수하는 경우 FHIR 서비스에 액세스할 수 있습니다. 이 역할의 사용자에게 부여된 액세스 권한은 fhirUser 구획과 관련된 리소스 및 임상 범위의 제한에 의해 제한됩니다.

참고 항목

SMART on FHIR 구현 가이드는 범위를 사용하여 FHIR 리소스 종류에 대한 액세스를 정의합니다. 이러한 범위는 애플리케이션이 FHIR 리소스에 대해 가질 수 있는 액세스에 영향을 줍니다. SMART 사용자 역할이 있는 사용자는 FHIR 서비스에서 읽기 API 상호 작용을 수행할 수 있습니다. SMART 사용자 역할은 FHIR 서비스에 대한 쓰기 권한을 부여하지 않습니다.

2단계: 샘플과 FHIR 서버 통합

이 링크를 클릭하여 Azure Health Data 및 AI 샘플 오픈 소스 솔루션으로 이동합니다. 문서에 나열된 단계를 통해 다른 Azure 서비스(예: APIM, Azure 함수 등)와 FHIR 서버를 통합할 수 있습니다.

참고 항목

샘플은 오픈 소스 코드이며 사용하기 전에 GitHub에서 정보 및 라이선스 사용 약관을 검토해야 합니다. Azure Health Data Service의 일부가 아니며 Microsoft 지원에서 지원되지 않습니다. 이러한 샘플은 Microsoft Entra ID를 ID 공급자 워크플로로 사용하여 AHDS(Azure Health Data Services) 및 기타 오픈 소스 도구를 함께 사용하여 환자 및 인구 서비스 기준 규정 준수에 대한 §170.315(g)(10) 표준화된 API를 시연하는 방법을 보여 주는 데 사용됩니다.

SMART on FHIR 프록시

클릭하여 펼치기!

참고 항목

앞에서 언급한 AHDS 샘플을 사용하여 SMART on FHIR(고급)에 대한 또 다른 옵션입니다. SMART on FHIR(Enhanced)을 채택하는 것이 좋습니다. SMART on FHIR 프록시 옵션은 레거시 옵션입니다. SMART on FHIR(Enhanced)은 SMART on FHIR 프록시에 추가된 기능을 제공합니다. SMART on FHIR(Enhanced)은 환자 및 인구 서비스 기준 SMART on FHIR 구현 가이드(v 1.0.0) 및 §170.315(g)(10) 표준화된 API의 요구 사항을 충족합니다.

SMART on FHIR을 사용하려면 먼저 앱을 인증하고 권한을 부여해야 합니다. SMART on FHIR을 처음 사용할 때 앱이 FHIR 리소스에 액세스할 수 있도록 관리 동의를 받아야 합니다.

앱에 소유권 역할이 없는 경우 앱 소유자에게 문의하고 앱에서 관리자 동의를 부여하도록 요청합니다.

관리자 권한이 있는 경우 다음 단계를 완료하여 관리자에게 직접 동의를 부여합니다. (나중에 앱에서 메시지가 표시되면 관리자 동의를 부여할 수도 있습니다.) 동일한 단계를 사용하여 다른 사용자를 소유자로 추가하여 앱 등록을 보고 편집할 수 있습니다.

본인 또는 다른 사용자를 앱의 소유자로 추가하려면 다음을 수행합니다.

  1. Azure Portal에서 Microsoft Entra ID로 이동합니다.
  2. 왼쪽 메뉴에서 앱 등록을 선택합니다.
  3. 만든 앱 등록을 검색한 다음, 선택합니다.
  4. 왼쪽 메뉴의 관리 아래에서 소유자를 선택합니다.
  5. 소유자 추가를 선택한 다음 관리자 동의를 구하려는 사용자 또는 본인을 추가합니다.
  6. 저장을 선택합니다.

2단계: SMART on FHIR 프록시 사용

SMART on FHIR를 사용하려면 Audience의 식별자 URI가 FHIR 서비스의 URI와 동일해야 합니다. FHIR 서비스의 표준 구성은 https://fhir.azurehealthcareapis.com의 Audience 값을 사용합니다. 그러나 FHIR 서비스의 특정 URL과 일치하는 값을 설정할 수도 있습니다(예: https://MYFHIRAPI.fhir.azurehealthcareapis.com). 이 설정은 SMART on FHIR 프록시를 작업할 때 필요합니다.

FHIR 인스턴스의 인증 설정에서 SMART on FHIR 프록시를 사용 설정하려면 SMART on FHIR 프록시 확인란을 선택하세요.

SMART on FHIR 프록시는 SMART on FHIR 앱과 Microsoft Entra ID 간의 중개자 역할을 합니다. 인증 회신(인증 코드)은 앱 자체가 아닌 SMART on FHIR 프록시로 이동해야 합니다. 그러면 프록시가 앱에 회신을 전달합니다.

인증 코드의 이 2단계 릴레이로 인해 Microsoft Entra 클라이언트 애플리케이션의 회신 URL(콜백)을 SMART on FHIR 프록시의 회신 URL과 SMART on FHIR 앱의 회신 URL을 조합한 URL로 설정해야 합니다. 결합된 회신 URL은 다음 형식을 사용합니다.

https://MYFHIRAPI.azurehealthcareapis.com/AadSmartOnFhirProxy/callback/aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA

회신에서 aHR0cHM6Ly9sb2NhbGhvc3Q6NTAwMS9zYW1wbGVhcHAvaW5kZXguaHRtbA은(는) SMART on FHIR 앱에 대한 회신 URL의 URL로부터 안전한 base64로 인코딩된 버전입니다. SMART on FHIR 앱 시작 관리자의 경우 앱이 로컬로 실행되면 회신 URL은 https://localhost:5001/sampleapp/index.html입니다.

다음과 같은 스크립트를 사용하여 결합된 회신 URL을 생성할 수 있습니다.

$replyUrl = "https://localhost:5001/sampleapp/index.html"
$fhirServerUrl = "https://MYFHIRAPI.fhir.azurewebsites.net"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($ReplyUrl)
$encodedText = [Convert]::ToBase64String($bytes)
$encodedText = $encodedText.TrimEnd('=');
$encodedText = $encodedText.Replace('/','_');
$encodedText = $encodedText.Replace('+','-');

$newReplyUrl = $FhirServerUrl.TrimEnd('/') + "/AadSmartOnFhirProxy/callback/" + $encodedText

이전에 Microsoft Entra ID에 대해 만든 공용 클라이언트 애플리케이션에 회신 URL을 추가합니다.

3단계: 테스트 환자 가져오기

FHIR 서비스 및 SMART on FHIR 프록시를 테스트하려면 데이터베이스에 환자가 한 명 이상 있어야 합니다. 아직 API를 사용하지 않았고 데이터베이스에 데이터가 없는 경우 Postman을 사용하여 FHIR 서비스에 액세스하여 환자를 로드합니다. 특정 환자의 ID를 적어 둡니다.

4단계: SMART on FHIR 앱 시작 관리자 다운로드

오픈 소스인 Azure 리포지토리용 FHIR 서버에는 간단한 SMART on FHIR 앱 시작 관리자와 SMART on FHIR 앱 샘플이 포함되어 있습니다. 이 자습서에서는 이 SMART on FHIR 앱 시작 관리자를 로컬로 사용하여 설정을 테스트합니다.

다음 명령을 사용하여 GitHub 리포지토리를 복제하고 애플리케이션으로 이동합니다.

git clone https://github.com/Microsoft/fhir-server
cd fhir-server/samples/apps/SmartLauncher

애플리케이션에서 몇 가지 구성을 설정해야 하며 appsettings.json에서 설정할 수 있습니다.

{
    "FhirServerUrl": "https://MYFHIRAPI.fhir.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

다음 dotnet user-secrets 기능을 사용하는 것이 좋습니다.

dotnet user-secrets set FhirServerUrl https://MYFHIRAPI.fhir.azurehealthcareapis.com
dotnet user-secrets set ClientId <APP-ID>

다음 명령을 사용하여 애플리케이션을 실행합니다.

dotnet run

5단계: SMART on FHIR 프록시 테스트

SMART on FHIR 앱 시작 관리자를 시작한 후 브라우저에서 https://localhost:5001을(를) 가리키면 다음이 표시됩니다.

SMART on FHIR 앱 시작 관리자를 보여 주는 스크린샷

환자, 방문 기록 또는 의사 정보를 입력하면 시작 컨텍스트가 업데이트되는 것을 볼 수 있습니다. FHIR 서비스를 사용하는 경우 시작 컨텍스트는 환자, 의사 등에 대한 정보를 포함하는 JSON 문서입니다. 이 시작 컨텍스트는 base64로 인코딩되어 SMART on FHIR 앱에 launch 쿼리 매개 변수로 전달됩니다. SMART on FHIR 사양에 따라 이 변수는 SMART on FHIR 앱에 대해 불투명하며 ID 공급자에게 전달됩니다.

SMART on FHIR 프록시는 이 정보를 사용하여 토큰 응답의 필드를 채웁니다. SMART on FHIR 앱이 이 필드를 사용할 수 있어 데이터를 요청하는 환자와 화면에서 애플리케이션을 렌더링하는 방법을 제어할 수 있습니다. SMART on FHIR 프록시는 다음 필드를 지원합니다.

  • patient
  • encounter
  • practitioner
  • need_patient_banner
  • smart_style_url

이러한 필드는 앱에 대한 지침을 제공하는 것이 그 목적이지만 보안 정보를 전달하지는 않습니다. SMART on FHIR 애플리케이션에서는 이러한 필드를 무시해도 됩니다.

SMART on FHIR 앱 시작 관리자는 페이지 맨 아래에 있는 시작 URL 정보를 업데이트합니다. 시작을 선택하여 샘플 앱을 시작하면 다음과 같이 표시됩니다.

SMART on FHIR 앱을 보여 주는 스크린샷

토큰 응답을 검사하여 시작 컨텍스트 필드가 어떤 방식으로 앱에 전달되는지 확인합니다.

SMART on FHIR 프록시에서 SMART on FHIR(Enhanced)로 마이그레이션

Important

SMART on FHIR 프록시는 2026년 9월에 사용 중지되고 해당 날짜까지 SMART on FHIR(Enhanced)으로 전환됩니다. 2026년 9월부터 SMART on FHIR 프록시를 사용하는 애플리케이션은 FHIR 서비스에 액세스할 때 오류를 보고합니다.

SMART on FHIR(Enhanced)은 SMART on FHIR 프록시에 비해 더 많은 기능을 제공합니다. SMART on FHIR(Enhanced)은 SMART on FHIR 구현 가이드(v 1.0.0) 및 §170.315(g)(10) Standardized API for patient and population services 기준의 요구 사항을 충족하는 것으로 간주될 수 있습니다. 다음 표에는 SMART on FHIR 프록시와 SMART on FHIR(Enhanced)의 차이점이 나열되어 있습니다.

기능 SMART on FHIR(Enhanced) SMART on FHIR 프록시
독립 실행형 시작 지원 예 아니요
EHR 시작 지원 예 예
범위 제한 지원 예 아니요
자사 Azure 제품에 의존 예, APIM(Azure API Management)과 같은 Azure 제품을 통합해야 합니다. 아니요
Microsoft 지원 FHIR 서비스에 지원됩니다. 오픈 소스 샘플 지원은 GitHub를 통해 보고 및 모니터링해야 합니다. FHIR 서비스에 지원됨

마이그레이션 단계

  • 1단계: FHIR SMART 사용자 역할 설정 사용자 관리: 역할에 사용자 할당 섹션에 나열된 단계를 따릅니다. SMART 사용자 역할에 추가된 모든 사용자는 요청이 SMART on FHIR 구현 가이드를 준수하는 경우 FHIR 서비스에 액세스할 수 있습니다.
  • 2단계: Azure Health Data 및 AI OSS 샘플에 SMART on FHIR 샘플 배포
  • 3단계: FHIR 서비스 URL의 엔드포인트를 '{{BASEURL_FROM_APIM}}/smart'로 업데이트합니다.
  • 4단계: FHIR 서비스에 대한 인증 블레이드 아래에서 SMART on FHIR 프록시 설정을 선택 취소합니다.

질문이 있는 경우 Microsoft Q&A에서 커뮤니티 전문가의 답변을 얻을 수 있습니다. 기술 지원을 받으려면 지원 요청을 작성할 수도 있습니다.

다음 단계

SMART on FHIR 기능을 사용하도록 설정하는 방법을 알아보았습니다. 검색 매개 변수, 한정자 및 기타 FHIR 검색 방법을 사용하여 검색하는 방법에 대한 자세한 내용은 검색 샘플 페이지를 참조하세요.

FHIR 검색 예제

참고 항목

FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.