기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# HealthLake에서 지원하는 FHIR OAuth 2.0 범위의 SMART
<a name="reference-smart-on-fhir-oauth-scopes"></a>

HealthLake는 OAuth 2.0을 권한 부여 프로토콜로 사용합니다. 권한 부여 서버에서이 프로토콜을 사용하면 클라이언트 애플리케이션이 액세스할 수 있는 FHIR 리소스에 대한 HealthLake 데이터 스토어 권한(생성, 읽기, 업데이트, 삭제 및 검색)을 정의할 수 있습니다.

SMART on FHIR 프레임워크는 권한 부여 서버에서 요청할 수 있는 범위 집합을 정의합니다. 예를 들어, 환자가 랩 결과를 보거나 연락처 세부 정보를 볼 수 있도록 설계된 클라이언트 애플리케이션은 `read` 범위를 요청할 수 있는 *권한*만 부여해야 합니다.

**참고**  
HealthLake는 아래 설명된 대로 FHIR V1 및 V2에서 모두 SMART를 지원합니다. 데이터 스토어가 생성될 때 FHIR의 SMART[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)는 다음 세 가지 값 중 하나로 설정됩니다.  
`SMART_ON_FHIR_V1` - (읽기/검색) 및 `read` (`write`create/update/delete) 권한을 포함하는 FHIR V1의 SMART만 지원합니다.
`SMART_ON_FHIR` - , , `create`, 및 `search` 권한을 포함하는 FHIR V1 `delete`및 V2의 SMART`read``update`를 모두 지원합니다.
`AWS_AUTH` - default AWS HealthLake 권한 부여 전략으로, FHIR의 SMART와 관련이 없습니다.

## 독립 실행형 시작 범위
<a name="smart-on-fhir-scopes-launch"></a>

HealthLake는 독립 실행형 시작 모드 범위를 지원합니다`launch/patient`.

독립 실행형 시작 모드에서 클라이언트 애플리케이션은 사용자와 환자를 클라이언트 애플리케이션에 알 수 없기 때문에 환자의 임상 데이터에 대한 액세스를 요청합니다. 따라서 클라이언트 애플리케이션의 권한 부여 요청은 환자 범위를 반환하도록 명시적으로 요청합니다. 인증에 성공하면 권한 부여 서버는 요청된 시작 환자 범위가 포함된 액세스 토큰을 발급합니다. 필요한 환자 컨텍스트는 권한 부여 서버의 응답에서 액세스 토큰과 함께 제공됩니다.


**지원되는 시작 모드 범위**  

| Scope | 설명 | 
| --- | --- | 
| `launch/patient` | OAuth 2.0 권한 부여 요청의 파라미터로, 권한 부여 응답에서 환자 데이터를 반환하도록 요청합니다. | 

## HealthLake의 FHIR 리소스 범위에 대한 SMART
<a name="smart-on-fhir-scopes-rest"></a>

HealthLake는 FHIR 리소스 범위에서 SMART의 세 가지 수준을 정의합니다.
+ `patient` 범위는 단일 환자의 특정 데이터에 대한 액세스 권한을 부여합니다.
+ `user` 범위는 사용자가 액세스할 수 있는 특정 데이터에 대한 액세스 권한을 부여합니다.
+ `system` 범위는 HealthLake 데이터 스토어에 있는 모든 FHIR 리소스에 대한 액세스 권한을 부여합니다.

다음 섹션에서는 FHIR V1의 SMART 또는 FHIR V2의 SMART를 사용하여 FHIR 리소스 범위를 구성하는 구문을 나열합니다.

**참고**  
데이터 스토어가 생성될 때 SMART on FHIR 권한 부여 전략이 설정됩니다. 자세한 내용은 HealthLake API 참조[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html#HealthLake-Type-IdentityProviderConfiguration-AuthorizationStrategy)의 섹션을 참조하세요. *AWS HealthLake *

### HealthLake에서 지원하는 FHIR V1 범위의 SMART
<a name="reference-smart-on-fhir-v1"></a>

FHIR V1에서 SMART를 사용하는 경우 HealthLake에 대한 FHIR 리소스 범위를 구성하기 위한 일반적인 구문은 다음과 같습니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.

```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('read' | 'write' | '*')
```


**FHIR v1에서 지원되는 권한 부여 범위에 대한 SMART**  

| 범위 구문 | 범위 예 | 결과 | 
| --- | --- | --- | 
| `patient/(fhir-resource \| '*').('read' \| 'write' \| '*')` | patient/AllergyIntolerance.\* | 환자 클라이언트 애플리케이션에는 기록된 모든 알러지에 대한 인스턴스 수준의 읽기/쓰기 액세스 권한이 있습니다. | 
| `user/(fhir-resource \| '*').('read' \| 'write' \| '*')` | user/Observation.read | 사용자 클라이언트 애플리케이션에는 기록된 모든 관측치에 대한 인스턴스 수준의 읽기/쓰기 액세스 권한이 있습니다. | 
| system/('read' \| 'write' \| \*) | system/\*.\* | 시스템 클라이언트 애플리케이션은 모든 FHIR 리소스 데이터에 대한 읽기/쓰기 액세스 권한이 있습니다. | 

### HealthLake에서 지원하는 FHIR V2 범위의 SMART
<a name="reference-smart-on-fhir-v2"></a>

FHIR V2에서 SMART를 사용하는 경우 HealthLake에 대한 FHIR 리소스 범위를 구성하기 위한 일반적인 구문은 다음과 같습니다. 다음 예제에서 전체 URL 경로를 보려면 **복사** 버튼을 스크롤합니다.

```
('patient' | 'user' | 'system') '/' (fhir-resource | '*') '.' ('c' | 'r' | 'u' | 'd' | 's')
```

**참고**  
FHIR V2에서 SMART를 사용하려면 [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 값을 데이터 형식의 멤버인 [https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions](https://hl7.org/fhir/smart-app-launch/STU2/conformance.html#permissions) 메타데이터 `capabilities` 문자열에 전달해야 합니다.  
HealthLake는 세분화된 범위를 지원합니다. 자세한 내용은 *FHIR US Core 구현 안내서*에서 [지원되는 세분화된 범위를 참조하세요](https://hl7.org/fhir/us/core/scopes.html#the-following-granular-scopes-shall-be-supported).


**FHIR V2에서 지원되는 권한 부여 범위에 대한 SMART**  

| 범위 구문 | 예제 V1 범위 | 결과 | 
| --- | --- | --- | 
| `patient/Observation.rs` | user/Observation.read | 현재 환자의 Observation 리소스를 읽고 검색할 수 있는 권한. | 
| `system/*.cruds` | system/\*.\* | 시스템 클라이언트 애플리케이션에는 모든 FHIR 리소스 데이터에 대한 전체 create/read/update/삭제/검색 액세스 권한이 있습니다. | 

### HealthLake에서 지원하는 FHIR V2.2 범위의 SMART
<a name="reference-smart-on-fhir-v2-2"></a>

V2.2는 검색 파라미터 기반 필터링으로 V2 범위를 확장합니다. 이제 권한 부여 서버는 리소스 유형 및 CRUDS 작업뿐만 아니라 특정 데이터 특성에 따라 액세스를 제한하는 범위를 발급할 수 있습니다.

V2의 모든 내용은 변경되지 않습니다. V2.2는 순수하게 추가됩니다.
+ 기존 V2 범위(필터 없음)는 이전과 같이 계속 작동합니다.
+ V2 문법은 선택적 `?param=value` 쿼리 문자열로 확장됩니다.
+ 범위 수준(`patient`/`user`/`system`), 리소스 유형 또는 CRUDS 문자는 변경되지 않습니다.

#### 사전 조건
<a name="smart-on-fhir-v2-2-prerequisites"></a>

FHIR V2.2에서 SMART를 활성화하기 전에 다음을 확인하세요.
+ 데이터 스토어가를 로 `AuthorizationStrategy` 설정하여 생성되었습니다`SMART_ON_FHIR`(V1 및 V2 모두 지원). `SMART_ON_FHIR_V1` 또는를 사용하는 데이터 스토어`AWS_AUTH`는 사용할 수 없습니다.
+ 데이터 스토어는 이미 `capabilities` 배열`permission-v2`에를 포함합니다. V2.2는 V2를 확장하므로 애디티브이며 독립적으로 사용할 수 없습니다.
+ IDP Lambda는 V2.2 범위 형식(`?`쿼리 구문이 포함된 범위)을 검증하고 전달하도록 구성됩니다.

#### V2.2 활성화
<a name="smart-on-fhir-v2-2-enabling"></a>

활성화 경로는 새 데이터 스토어를 생성하는지 아니면 기존 데이터 스토어를 업데이트하는지에 따라 달라집니다.

##### 새 데이터 스토어
<a name="smart-on-fhir-v2-2-new-data-stores"></a>

새 데이터 스토어를 생성할 때 `permission-v2.2`의 `Metadata` 필드에 있는 `capabilities` 배열에를 추가합니다. [https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html) 

```
"capabilities": [
  "launch-ehr",
  "sso-openid-connect",
  "client-public",
  "permission-v2",
  "permission-v2.2"
]
```

##### 기존 데이터 스토어
<a name="smart-on-fhir-v2-2-existing-data-stores"></a>

기존 데이터 스토어에서 FHIR V2.2에서 SMART를 활성화하려면의 `Metadata` 필드에 있는 `capabilities` 배열에 `permission-v2.2`를 추가[https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html](https://docs.aws.amazon.com/healthlake/latest/APIReference/API_IdentityProviderConfiguration.html)하고를 사용하여 변경 사항을 제출합니다`UpdateFHIRDatastore`. 자세한 내용은 [HealthLake 데이터 스토어 업데이트](managing-data-stores-update.md) 단원을 참조하십시오.

요구 사항:
+ `permission-v2`는 배열에 남아 있어야 합니다. V2.2는 V2를 확장하며 자체적으로 사용할 수 없습니다.
+ `AuthorizationStrategy`는 `SMART_ON_FHIR` ( `SMART_ON_FHIR_V1` 또는 아님`AWS_AUTH`)여야 합니다.
+ 자격 증명 공급자 구성을 업데이트하면 전체가 대체되므로 모든 기존 필드와 기능을와 함께 포함합니다`permission-v2.2`.

변경 사항은 가동 중지 없이 즉시 적용됩니다. 확인하려면를 가져옵니다[검색 문서](reference-smart-on-fhir-discovery-document.md)(SigV4 필요).

```
GET {healthlake-endpoint}/r4/.well-known/smart-configuration
```

응답의 `capabilities` 배열에가 포함된 경우 FHIR V2.2의 `permission-v2.2`SMART가 활성화됩니다.

#### 확장 범위 구문
<a name="smart-on-fhir-v2-2-extended-scope-syntax"></a>

V2 문법은 선택적 쿼리 문자열로 확장됩니다.

```
V2:   (patient|user|system) / resource . cruds
V2.2: (patient|user|system) / resource . cruds [? param=value [& param=value ...]]
```


**V2.2 범위 쿼리 문자열 구성 요소**  

| 구성 요소 | 설명 | 
| --- | --- | 
| `?param=value` | Search-parameter 필터. 이 기준과 일치하는 리소스만 액세스할 수 있습니다. | 
| `&param=value` | 추가 필터. 여러 필터가 ANDed됩니다. 모두 일치해야 합니다. | 

규칙:
+ 필터는 범위에 지정된 리소스 유형에만 적용됩니다. 필터가 있는 와일드카드(`*`)는 지원되지 않습니다.
+ 파라미터는 데이터 스토어의 검색 구성에 따라 리소스 유형에 대해 유효해야 합니다(를 통해 확인`GET /r4/metadata`).
+ 전체 범위 문자열(예: `patient/Observation.rs?category=laboratory`)은 OAuth 2.0 범위 파라미터 및 액세스 토큰 `scp` 클레임에 나타나는 리터럴 값입니다.
+ 권한 부여 요청에서 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)에 따라 특수 문자를 URL 인코딩합니다(예: `|` → `%7C`).
+ 날짜, 수 및 수량 파라미터의 경우 V2.2는 접두사 [비교기](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-comparators)(예: `?date=eq2023-01-01`)를 지원합니다. V2.2는 [검색 파라미터 한정자](https://docs.aws.amazon.com/healthlake/latest/devguide/reference-fhir-search-parameters.html#search-parameter-modifiers)도 지원합니다.

#### 범위 예제
<a name="smart-on-fhir-v2-2-scope-examples"></a>


**V2.2 범위 예제**  

| Scope | 액세스 권한 부여 | 
| --- | --- | 
| `patient/DiagnosticReport.rs?category=LAB` | `category`가 인 `DiagnosticReport` 리소스만 해당됩니다`LAB`. | 
| `patient/Observation.rs?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality\|R` | 보안 레이블이 인 `Observation` 리소스만 해당됩니다`Restricted`. | 
| `patient/Observation.rs?date=ge2023-01-01` | 2023년 1월 1일 이후 날짜의 `Observation` 리소스만 해당됩니다. | 
| `patient/Observation.rs?category=laboratory&status=final` | 랩 및 최종 `Observation` 리소스만 해당됩니다. | 
| `user/Condition.rs?clinical-status=active` | 활성 `Condition` 리소스만 해당됩니다. | 

#### 적용 동작
<a name="smart-on-fhir-v2-2-enforcement"></a>

토큰에 V2.2 범위가 포함된 경우 HealthLake는 작업당 필터를 적용합니다.


**작업당 V2.2 적용**  

| 연산 | 동작 | 
| --- | --- | 
| 읽기(`r`) | 리소스가 모든 범위 필터와 일치하는 경우에만 성공합니다. 그렇지 않으면 403을 반환합니다. | 
| 검색(`s`) | 범위 필터는 쿼리와 교차합니다. 일치하는 리소스만 반환됩니다. | 
| 생성/업데이트(`c`/`u`) | 리소스는 작성할 범위 필터를 충족해야 합니다. 그렇지 않으면 403을 반환합니다. | 
| 삭제(`d`) | 대상 리소스는 범위 필터와 일치해야 합니다. 그렇지 않으면 403을 반환합니다. | 

##### 범위 우선 순위
<a name="smart-on-fhir-v2-2-scope-precedence"></a>
+ 동일한 리소스 유형에 대한 여러 V2.2 범위가 결합됩니다(또는 범위 간).
+ 필터가 없는 더 넓은 V2 범위(예: `patient/Observation.rs`)는 동일한 토큰의 더 좁은 V2.2 범위에 관계없이 전체 액세스 권한을 부여합니다.
+ `permission-v2.2` 활성화되지 않은 데이터 스토어의 V2.2 범위는 자동으로 무시됩니다.

#### 제한 사항
<a name="smart-on-fhir-v2-2-limitations"></a>

V2.2 범위 필터에서는 다음이 지원되지 않습니다.
+ 복합 검색 파라미터(예: `code-value-quantity`).
+ 연결된 검색 파라미터(예: `subject:Patient.name=Smith`).
+ `_include` / `_revinclude` 검색 파라미터.
+ `$export` / `$davinci-data-export` (벌크 데이터) - V2.2 필터는 적용되지 않습니다. 대량 내보내기는 V2 범위를 사용합니다.
+ 와일드카드 리소스 유형을 필터와 결합합니다(예: `patient/*.rs?category=LAB`가 유효하지 않음). 검색 파라미터 필터를 사용할 때는 명시적 리소스 유형을 지정해야 합니다(예: `patient/Observation.rs?category=LAB`).


**문제 해결**  

| 증상 | 원인 | 수정 | 
| --- | --- | --- | 
| 토큰 범위가 인식되지 않음 | 데이터 스토어에서 V2.2가 활성화되지 않음 | 지원 티켓을 통해 활성화를 `/.well-known/smart-configuration` 확인하고 요청합니다. | 
| 존재하는 리소스의 403 | 리소스가 범위 필터와 일치하지 않음 | 범위 파라미터와 비교하여 리소스 값을 확인합니다. | 
| 빈 검색 결과 | 범위 필터가 쿼리보다 좁음 | 결과는 쿼리 필터와 범위 필터의 교차점입니다. | 
| `InvalidScope` 오류 | 범위의 검색 파라미터가 잘못되었습니다. | `/metadata` CapabilityStatement를 통해 파라미터를 확인합니다. | 

#### 종합 예제
<a name="smart-on-fhir-v2-2-end-to-end-example"></a>

시나리오: 환자 앱은 2023년부터 완료된 랩 결과만 표시해야 합니다.

1. 권한 부여 서버는 다음과 같은 범위의 토큰을 발급합니다.

   ```
   patient/Observation.rs?category=laboratory&status=final&date=ge2023-01-01
   ```

1. 클라이언트가 HealthLake를 호출합니다.

   ```
   GET {endpoint}/r4/Observation?patient=Patient/123
   ```

1. HealthLake는 범위 필터를 적용합니다. 응답에는 클라이언트가 모든 관찰을 요청했더라도 `category=laboratory` `status=final` AND `date ≥ 2023-01-01`-인 `Observation` 리소스만 포함됩니다.