SMART 앱 실행 설명: 범위, 실행, PKCE

간단 요약: SMART App Launch (SMART on FHIR)는 FHIR 서버에 대한 앱의 사용자 대신 권한 있는 액세스 방법을 정의하는 HL7의 명세입니다. 이는 FHIR별 규칙이 적용된 OAuth 2.0 및 OpenID Connect로, .well-known/smart-configuration에 있는 디스커버리 문서, 두 가지 실행 모드(EHR 실행 - EHR이 현재 환자 컨텍스트에서 앱을 실행, 독립 실행 - 사용자가 앱을 실행하고 환자를 선택), FHIR 인식 구문의 범위(patient/Observation.rs는 컨텍스트 내 환자의 관찰 기록을 읽고 검색함을 의미), 토큰과 함께 반환되는 실행 컨텍스트(환자, 진료과), 그리고 서명된 JWT 클라이언트 인증을 통한 시스템 간 액세스를 위한 백엔드 서비스를 포함합니다. SMART v2(2021년 이후)는 PKCE를 필수로 하고, 세분화된 범위와 비대칭 클라이언트 인증을 추가했으며, 국가 프로그램에서 요구하는 버전입니다.

1단계: 디스커버리

SMART 앱 실행 디스커버리는 앱이 FHIR 서버의 .well-known/smart-configuration 문서를 가져오는 것으로 시작됩니다. 이 문서에는 인증 및 토큰 엔드포인트, 지원되는 기능(EHR 실행, 독립 실행형 실행, 공개 및 비공개 클라이언트, OpenID Connect, 환자 및 사용자 권한), 지원되는 범위, PKCE 코드 챌린지 방법 및 부여 유형이 나열되어 있어 앱이 사용자에게 어디로 보낼지 알 수 있습니다.

GET https://fhir.example-hospital.org/.well-known/smart-configuration

{
  "issuer": "https://auth.example-hospital.org",
  "authorization_endpoint": "https://auth.example-hospital.org/authorize",
  "token_endpoint": "https://auth.example-hospital.org/token",
  "introspection_endpoint": "https://auth.example-hospital.org/introspect",
  "capabilities": ["launch-ehr", "launch-standalone", "client-public", "client-confidential-asymmetric", "sso-openid-connect", "context-ehr-patient", "context-standalone-patient", "permission-patient", "permission-user", "permission-v2", "permission-offline"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "patient/*.rs", "user/*.rs", "offline_access"],
  "code_challenge_methods_supported": ["S256"],
  "grant_types_supported": ["authorization_code", "client_credentials"]
}

앱은 사용자에게 어디로 보내야 하는지, 그리고 서버가 무엇을 지원하는지 파악합니다.

2단계: 실행

SMART 앱 실행에는 두 가지 실행 모드가 있습니다. EHR 실행의 경우, 의사가 EHR 내에서 앱을 열면 EHR이 iss 매개변수(FHIR 서버)와 현재 환자 및 진료를 인코딩하는 불투명한 실행 토큰을 전달합니다. 독립 실행형 실행의 경우, 사용자가 앱을 직접 열면 인증 서버에서 환자를 선택하거나 확인하도록 요청합니다.

EHR 실행. 의료진이 EHR 내에서 앱을 클릭하면, EHR은 두 개의 매개변수(iss(FHIR 서버) 및 launch(현재 환자와 진료과를 인코딩하는 불투명 토큰))와 함께 앱의 실행 URL을 엽니다. 앱은 launch 범위와 함께 인증 요청에 launch를 에코해야 합니다.

독립 실행. 사용자가 앱을 직접 실행하면, 앱은 FHIR 서버(선택 또는 구성됨)를 알고 launch/patient로 컨텍스트를 요청합니다. 인증 서버는 사용자에게 환자를 선택하거나 확인하도록 요청합니다.

3단계: PKCE를 사용한 인증 코드

SMART 인증 단계는 PKCE를 사용한 OAuth 2.0 인증 코드 흐름입니다. 앱은 범위, FHIR 서버의 aud, 코드 챌린지를 포함하여 사용자를 인증 엔드포인트로 보냅니다. 사용자는 인증하고 승인합니다. 앱은 반환된 코드와 코드 검증자를 교환하여 액세스 토큰을 받으며, 이 토큰은 실행 컨텍스트와 함께 도착합니다.

GET https://auth.example-hospital.org/authorize?
  response_type=code&client_id=my-app&redirect_uri=https://app.example.org/cb
  &scope=openid%20fhirUser%20launch%20patient/Observation.rs%20patient/Condition.rs%20offline_access
  &state=af0ifjsldkj&aud=https://fhir.example-hospital.org
  &launch=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

사용자는 인증(병원 신원 제공업체 사용)하고 범위를 승인하면, 서버는 code와 함께 다시 리디렉션합니다. 앱은 이를 교환합니다.

POST https://auth.example-hospital.org/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://app.example.org/cb&client_id=my-app&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid fhirUser launch patient/Observation.rs patient/Condition.rs offline_access",
  "refresh_token": "a8c3...",
  "id_token": "eyJhbGciOi...",
  "patient": "Patient/123",
  "encounter": "Encounter/456",
  "fhirUser": "Practitioner/42",
  "need_patient_banner": true,
  "smart_style_url": "https://ehr.example.org/styles/smart.json"
}

실행 컨텍스트(patient, encounter, fhirUser)는 토큰과 함께 도착합니다. 공개 클라이언트(모바일 및 브라우저 앱)는 PKCE를 사용하며 클라이언트 비밀은 사용하지 않습니다. 기밀 클라이언트는 비밀 또는 선호되는 서명된 JWT(private_key_jwt)를 비대칭 방식으로 인증합니다.

범위

SMART on FHIR v2 범위는 context/resource.permissions 구문을 사용합니다. 여기서 context는 patient, user 또는 system이며, permissions는 c, r, u, d, s를 결합하여 생성, 읽기, 업데이트, 삭제 및 검색을 나타냅니다(예: patient/Observation.rs). 세분화된 범위는 필터를 추가하고, openid와 fhirUser는 사용자의 신원을 제공하며, launch 범위는 컨텍스트를 요청하고, offline_access는 새로고침 토큰을 요청합니다.

SMART v2 구문: <context>/<resource>.<permissions> 여기서 context는 patient(컨텍스트 내 환자), user(사용자가 볼 수 있는 모든 것) 또는 system(백엔드)이며, permissions는 c 생성, r 읽기, u 업데이트, d 삭제, s 검색 순서대로입니다: patient/Observation.rs, user/Patient.rs, system/*.cruds. 세분화된 범위는 필터를 추가합니다: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs. openid fhirUser는 ID 토큰과 사용자의 FHIR 신원을 제공합니다. launch, launch/patient, launch/encounter는 컨텍스트를 요청합니다. offline_access는 사용자가 없을 때 사용할 수 있는 새로고침 토큰이며, online_access는 세션 중에만 유효합니다. v1 구문(patient/Observation.read)은 여전히 많은 서버에서 허용됩니다.

백엔드 서비스

사용자 없이 작동하는 시스템(야간 내보내기, 통합 엔진)의 경우, SMART 백엔드 서비스는 서명된 JWT 어설션(클라이언트의 공개 키가 JWKS URL에 게시됨)과 system/ 범위를 사용하는 client_credentials를 사용합니다. 사용자도 없고 실행 컨텍스트도 없으며 엄격한 등록이 필요합니다.

안전하게 실행하기

SMART 앱 실행을 안전하게 실행하려면 정확한 리디렉션 URI를 등록하고, 암시적 흐름을 절대 사용하지 않으며, 새로고침 토큰을 안전하게 저장하고 순환하며, ID 토큰의 state와 aud를 검증하고, 모든 API 호출 시 토큰을 확인하며, 데이터 계층에서 범위와 환자 컨텍스트를 모두 적용하여 한 환자에 대한 토큰이 다른 환자의 데이터를 읽지 않도록 하고, 모든 액세스를 기록해야 합니다.

정확한 리디렉션 URI를 등록하십시오. 암시적 흐름은 절대 사용하지 마십시오. 새로고침 토큰은 안전하게 저장하고 순환하십시오. state를 검증하십시오. ID 토큰의 aud를 확인하십시오. 모든 API 호출 시 토큰을 검증하십시오(인트로스펙션 또는 JWT 검증). 데이터 계층에서 범위 및 환자 컨텍스트를 강제 적용하십시오. Patient/123에 대한 토큰은 절대 Patient/124를 읽어서는 안 됩니다. 모든 액세스를 기록하십시오(보안 및 신원: 지도). SMART는 또한 환자 액세스 브랜드를 정의하여 앱이 사용자가 연결할 수 있는 조직을 표시하는 방법을 제공하며, 환자 주도 공유를 위한 SMART Health Links와 상호 운용됩니다.

요구되는 곳

미국 환자 액세스 규칙은 인증된 EHR이 SMART App Launch 및 백엔드 서비스를 지원하도록 요구합니다. 유럽의 국가 프로그램은 앱 액세스를 위해 이를 채택합니다(네덜란드의 MedMij는 동등한 규칙으로 OAuth 2.0을 사용). IPS 및 많은 구현 가이드에서 이를 가정합니다. TEFCA 및 국가 전자 건강 기록을 참조하십시오.

Anpheros에서

Anpheros Platform은 앱의 경우 PKCE를 사용하고 백엔드의 경우 서명된 JWT 클라이언트 인증을 사용하며, 모든 요청에서 강제 적용되는 환자 컨텍스트 및 개인의 동의에서 파생된 범위를 사용합니다. 개발자 사이트에는 이를 기반으로 구축하기 위한 인증 및 SMART on FHIR 백엔드 패턴이 문서화되어 있습니다.

출처

자주 묻는 질문

SMART on FHIR는 OAuth 2.0과 같은 것인가요?

FHIR별 추가 기능(디스커버리, 실행 컨텍스트, 범위 구문 및 백엔드 서비스)이 포함된 OAuth 2.0 및 OpenID Connect입니다. 모든 OAuth 라이브러리가 작동하며, SMART 규칙이 앱을 FHIR 서버 간에 이식 가능하게 만듭니다.

서버 측 앱에 PKCE가 필요한가요?

SMART v2에서는 인증 코드 흐름을 사용하는 모든 클라이언트에 대해 그렇습니다. 기밀 클라이언트는 클라이언트 인증(비밀 또는 서명된 JWT)을 추가로 사용합니다.

patient/ 및 user/ 범위의 차이점은 무엇인가요?

patient/는 실행 컨텍스트 내 단일 환자에 대한 액세스를 제한합니다. user/는 인증된 사용자가 볼 수 있는 모든 환자에 대한 액세스 권한을 부여합니다. 환자 대면 앱은 patient/를 사용하고, 의료진 앱은 종종 컨텍스트와 함께 user/를 사용합니다.

SMART 앱이 기록에 쓸 수 있나요?

범위에서 생성 또는 업데이트 권한(c, u)이 부여되고 서버에서 허용하는 경우 가능합니다. 많은 배포에서는 환자 앱에 읽기 및 검색만 허용하고 QuestionnaireResponse와 같은 특정 리소스를 통해 쓰기를 라우팅합니다.

Anpheros Platform

샌드박스에서 무료로 사용해 보세요

5분 만에 첫 FHIR 호출. 환자의 동의가 내장된 HL7 FHIR R4 API: 샌드박스에서 먼저 사용해보고, 자체 앱 또는 병원 시스템을 연결하세요.

무료 샌드박스 만들기 샘플 앱 실행 →스타터 코드(Python) →Postman 컬렉션 →개발자 가이드 읽기 →

무료 · 합성 환자 30명 · 카드 불필요

이 가이드는 정보 제공 목적으로 의료 조언을 대체하지 않습니다. 건강 관련 결정은 의사와 상담하십시오. 응급 상황에서는 현지 응급 번호(유럽은 112)로 전화하세요.

작성자

Anpheros 팀

Anpheros는 환자가 직접 관리하고 어떤 병원과도 공유할 수 있는 의료 기록을 EU 기반의 HL7 FHIR R4 플랫폼에서 구축합니다. 이 가이드들은 건강 정보를 이해하고 정리하는 데 도움을 드리며, 의사의 진료를 대체하지 않습니다.

Anpheros 소개 →

SMART 앱 실행 설명: 범위, 실행 컨텍스트, PKCE 및 환자 중심 흐름

1단계: 디스커버리

2단계: 실행

3단계: PKCE를 사용한 인증 코드

범위

백엔드 서비스

안전하게 실행하기

요구되는 곳

Anpheros에서

관련 페이지

출처

자주 묻는 질문

SMART on FHIR는 OAuth 2.0과 같은 것인가요?

서버 측 앱에 PKCE가 필요한가요?

patient/ 및 user/ 범위의 차이점은 무엇인가요?

SMART 앱이 기록에 쓸 수 있나요?

샌드박스에서 무료로 사용해 보세요

SMART 앱 실행 설명: 범위, 실행 컨텍스트, PKCE 및 환자 중심 흐름

1단계: 디스커버리

2단계: 실행

3단계: PKCE를 사용한 인증 코드

범위

백엔드 서비스

안전하게 실행하기

요구되는 곳

Anpheros에서

관련 페이지

출처

자주 묻는 질문

SMART on FHIR는 OAuth 2.0과 같은 것인가요?

서버 측 앱에 PKCE가 필요한가요?

patient/ 및 user/ 범위의 차이점은 무엇인가요?

SMART 앱이 기록에 쓸 수 있나요?

샌드박스에서 무료로 사용해 보세요

핵심 용어

다음 글 읽기

비타민과 미네랄: 각 영양소의 역할, 섭취 방법 및 보충제가 필요한 경우

체온 조절: 우리 몸이 37°C를 유지하는 방법, 땀과 떨림의 역할, 그리고 더위나 추위가 위험해지는 때

수면과 생체 리듬: 우리 몸의 시계는 어떻게 작동하며 더 잘 자려면 어떻게 해야 할까요?