SMART on FHIR 개요

아티클
10/31/2024

Important

Azure API for FHIR은 2026년 9월 30일에 사용 중지됩니다. 해당 날짜까지 마이그레이션 전략에 따라 Azure Health Data Services FHIR® 서비스로 전환합니다. Azure API for FHIR의 사용 중지로 인해 2025년 4월 1일부터 신규 배포가 허용되지 않습니다. Azure Health Data Services FHIR 서비스는 고객이 다른 Azure 서비스에 통합하여 FHIR, DICOM 및 MedTech 서비스를 관리할 수 있도록 하는 Azure API for FHIR의 진화된 버전입니다.

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

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

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

필수 조건

FHIR 서비스의 인스턴스
.NET SDK 6.0
CORS(원본 간 리소스 공유) 사용
Microsoft Entra ID에 공용 클라이언트 애플리케이션 등록
- 애플리케이션을 등록한 후 클라이언트 애플리케이션에 applicationId 대한 메모를 작성합니다.
리소스를 만들고 역할 할당을 추가하기 위해 Azure 구독 FHIR 서비스에 액세스할 수 있는지 확인합니다.

샘플 OSS를 사용한 SMART on FHIR(SMART on FHIR(Enhanced))

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

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

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

Azure Health Data 및 AI 샘플 OSS에 있는 단계를 따릅니다. 이렇게 하면 FHIR 서버를 다른 Azure 서비스(예: APIM, Azure 함수 등)와 통합할 수 있습니다.

참고 항목

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

SMART on FHIR 프록시

클릭하여 펼치기!

참고 항목

이것은 언급된 대로 SMART on FHIR(고급)의 또 다른 경로입니다. SMART on FHIR 프록시 옵션은 EHR 시작 시퀀스만 사용하도록 설정합니다.

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

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

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

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

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

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

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

Azure API for FHIR 인스턴스에 대한 인증 설정에서 SMART on 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.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을 추가합니다.

공용 클라이언트에 대한 회신 URL을 구성하는 방법을 보여 주는 스크린샷.

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

Azure API for 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.azurehealthcareapis.com",
    "ClientId": "APP-ID",
    "DefaultSmartAppUrl": "/sampleapp/launch.html"
}

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

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

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

dotnet run

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

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

SMART on FHIR 앱 시작 관리자의 스크린샷.

환자, 만남 또는 개업의 정보를 입력하면 시작 컨텍스트가 업데이트됩니다. Azure API for 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(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의 사용 허가 하에 사용됩니다.

다음을 통해 공유

SMART on FHIR 개요

필수 조건

샘플 OSS를 사용한 SMART on FHIR(SMART on FHIR(Enhanced))

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

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

SMART on FHIR 프록시

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

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

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

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

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

마이그레이션 단계

다음 단계

피드백

추가 리소스

다음을 통해 공유

SMART on FHIR 개요

필수 조건

샘플 OSS를 사용한 SMART on FHIR(SMART on FHIR(Enhanced))

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

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

SMART on FHIR 프록시

1단계: 클라이언트 애플리케이션에 대한 관리자 동의 설정

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

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

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

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

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

마이그레이션 단계

다음 단계

피드백

추가 리소스