FHIR 서비스에 대한 ID 공급자 구성 문제 해결

아티클
02/12/2024

Azure Health Data Services의 FHIR® 서비스 API 버전 2023-12-01은 Microsoft Entra ID 외에 두 개의 ID 공급자를 지원합니다. 사용자에게 범위가 지정된 액세스를 제공하려면 authenticationConfiguration 개체의 smartIdentityProviders 섹션을 채워 두 ID 공급자를 구성합니다.

오류 메시지

다음은 FHIR 서비스 SMART ID 공급자가 실패할 경우 발생하는 오류 메시지이며, 이 문제를 해결하기 위해 수행할 권장되는 작업은 다음과 같습니다.

Error	원인	Fix
SMART ID 공급자의 최대 수는 2입니다.	구성된 ID 공급자 수가 3개 이상입니다.	ID 공급자 수를 2개 이하로 줄이십시오.
하나 이상의 SMART ID 공급자 권한 값이 null이거나 비어 있거나 잘못되었습니다.	ID 공급자 구성의 `authority` 요소는 정규화된 URL이어야 합니다.	모든 `authority` 값이 정규화된 URL인지 확인하십시오.
모든 SMART ID 공급자 권한은 고유해야 합니다.	두 ID 공급자 구성의 `authority` 요소는 동일합니다.	모든 `authority` 값이 고유하고 정규화된 URL인지 확인하십시오.
SMART ID 공급자 애플리케이션의 최대 수는 2입니다.	ID 공급자 구성의 ID 공급자 애플리케이션 수가 3개 이상입니다.	ID 공급자 애플리케이션 수를 ID 공급자당 1~2개로 줄이십시오.
하나 이상의 SMART 애플리케이션이 null입니다.	하나 이상의 ID 공급자에 대한 `applications` 요소가 null이거나 애플리케이션이 포함되어 있지 않습니다.	모든 ID 공급자 구성에 하나 이상의 애플리케이션이 구성되어 있는지 확인합니다.
하나 이상의 SMART 애플리케이션 `allowedDataActions`에 중복 요소가 포함되어 있습니다.	하나 이상의 애플리케이션 구성에 있는 `allowedDataActions` 배열에 중복 값이 포함되어 있습니다.	`allowedDataActions` 배열에서 중복 값을 제거하십시오.
하나 이상의 SMART 애플리케이션 `allowedDataActions` 값이 잘못되었습니다.	`allowedDataActions` 배열에서 허용되는 유일한 값은 `Read`입니다.	`allowedDataActions` 배열에서 부적합한 값을 제거하십시오.
하나 이상의 SMART 애플리케이션 `allowedDataActions` 값이 null이거나 비어 있습니다.	하나 이상의 애플리케이션 구성에서 `allowedDataActions` 배열이 null이거나 비어 있습니다.	`allowedDataActions` 배열에서 허용되는 유일한 값은 `Read`입니다.
하나 이상의 SMART 애플리케이션 `audience` 값이 null이거나 비어 있거나 잘못되었습니다.	하나 이상의 애플리케이션 구성에 있는 `audience` 문자열이 null이거나 비어 있거나 형식이 잘못되었습니다.	`audience` 문자열이 null이 아니거나 비어 있지 않고 값이 문자열 형식인지 확인하십시오.
모든 SMART ID 공급자 애플리케이션 클라이언트 ID는 고유해야 합니다.	하나 이상의 애플리케이션 구성에 있는 `clientId` 값은 다른 `clientId` 값과 동일한 값입니다.	ID 공급자 구성을 포함하여 모든 `clientId` 값이 고유한지 확인하십시오.
하나 이상의 SMART 애플리케이션 클라이언트 ID 값이 null이거나 비어 있거나 잘못되었습니다.	하나 이상의 애플리케이션 구성에 있는 `clientId` 문자열이 null이거나 비어 있거나 형식이 잘못되었습니다.	`clientId` 문자열이 null이 아니거나 비어 있지 않고 값이 문자열 형식인지 확인하십시오.
타사 ID 공급자를 사용하는 Azure Health Data Services FHIR API의 권한 부여 실패	FHIR SMART 사용자 역할은 인증 계층을 추가할 때 이 문제를 발생합니다.	FHIR SMART 사용자 역할이 할당되지 않았는지 확인합니다.

FHIR API 요청 오류

SMART ID 공급자가 발급한 토큰을 사용하여 FHIR 서비스를 요청하는 경우 두 가지 일반적인 오류 코드인 401 Unauthorized 또는 403 Forbidden이 발생할 수 있습니다. 문제 해결을 시작하려면 smartIdentityProviders 요소의 구성(특히 FHIR 서비스가 새로운 경우)을 확인합니다.

smartIdentityProviders 요소의 올바른 구성을 확인하려면 다음 단계를 수행합니다.

smartIdentityProviders 요소가 올바르게 구성되었는지 확인합니다.
authority 문자열이 올바른지 확인합니다. authority 문자열이 액세스 토큰을 발급한 ID 공급자의 토큰 인증 기관인지 확인합니다.
authority 문자열이 유효한 토큰 인증 기관인지 확인합니다. openid-connect 구성을 요청합니다. aubrowser navigatesthority 문자열의 끝에 /.well-known/openid-configuration을 추가한 다음 브라우저에 붙여넣습니다. 값이 올바르면 브라우저가 openid-connect configuration로 이동합니다. 그렇지 않은 경우 문자열에 문제가 있는 것입니다.

예시:
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
clientId 문자열이 올바른지 확인합니다. clientId 문자열이 ID 공급자에 정의된 리소스 애플리케이션의 클라이언트 ID(또는 애플리케이션 ID)와 일치하는지 확인합니다.
요청 메서드가 GET인지 확인합니다. allowedDataActions값은 Read을(를) 지원하므로 지원되는 유일한 요청 형식은 GET입니다.
JWT(JSON Web Token) 클레임을 확인합니다. 액세스 토큰을 사용할 수 있는 경우 jwt.ms 같은 온라인 도구를 사용하여 디코딩합니다. 토큰을 디코딩한 후 클레임의 정확성을 검사할 수 있습니다.
iss(발급자 클레임)를 확인합니다. iss 클레임이 ID 공급자 OpenId 구성의 issuer 값과 정확히 일치하는지 확인합니다.

authority ID 공급자 구성에서 smartIdentityProvider 값을 가져와서 /.well-known/openid-configuration을 추가한 다음 브라우저에 붙여넣습니다. 값이 올바르면 브라우저가 openid-connect 구성으로 이동합니다.

예시:
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
azp 또는 appid(권한 있는 당사자 또는 appid 클레임)를 확인합니다. azp 또는 appid 클레임은 smartIdentityProvider ID 공급자 구성에 제공된 clientId 값과 정확히 일치해야 합니다.
aud(대상 클레임)를 확인합니다. aud 클레임은 smartIdentityProvider ID 공급자 구성에 제공된 audience 값과 정확히 일치해야 합니다.
scp(범위 클레임)를 확인합니다. scp 클레임이 필요합니다. 누락된 경우 요청이 실패합니다. scp 클레임의 형식은 SMART on FHIR v1 범위를 준수해야 합니다. FHIR 서비스는 현재 읽기 범위만 지원한다는 점에 유의해야 합니다. SMART on FHIR v1 범위의 허용 가능한 변형은 슬래시(/)를 마침표(.)로 바꾸고 별표(*)를 all로 바꿉니다. 예를 들어 SMART on FHIR 범위 patient/*.read의 허용 가능한 버전은 patient.all.read입니다.

참고 항목

read 범위만 지원됩니다.

fhirUser 또는 extension_fhirUser(FHIR 사용자 클레임)를 확인합니다. fhirUser 또는 extension_fhirUser 클레임이 필요합니다. 누락된 경우 요청이 실패합니다. 이 클레임은 ID 공급자의 사용자를 FHIR 서비스의 사용자 리소스와 연결합니다. 값은 액세스 토큰이 발급된 개인을 나타내는 FHIR 서비스에서 리소스의 정규화된 URL이어야 합니다. 예를 들어 로그인한 환자에게 발급된 액세스 토큰에는 FHIR 서비스에 있는 환자 리소스의 정규화된 URL이 포함된 fhirUser 또는 extension_fhirUser 클레임이 있어야 합니다.

ID 공급자를 구성하기 위한 스키마

smartIdentityProviders 요소는 하나 또는 두 개의 identity provider configurations이 포함된 JSON 배열입니다. identity provider configuration은(는) 다음으로 구성됩니다.

ID 공급자 토큰 인증 기관의 정규화된 URL이어야 하는 authority 문자열 값입니다.
ID 공급자 리소스 application configurations을 포함하는 applications 배열입니다.

{
  "properties": {
    "authenticationConfiguration": {
      "authority": "string",
      "audience": "string",
      "smartProxyEnabled": "bool",
      "smartIdentityProviders": [
        {
          "authority": "string",
          "applications": [
            {
              "clientId": "string",
              "allowedDataActions": "array",
              "audience": "string"
            }
          ]
        }
      ]
    }
  }
}

applications 요소는 하나 또는 두 개의 application configurations이 포함된 JSON 배열입니다.

application configuration은 다음으로 구성됩니다.

ID 공급자 리소스 애플리케이션의 클라이언트 ID(애플리케이션 ID라고도 함)에 대한 clientId 문자열 값입니다.
액세스 토큰에서 aud 클레임의 유효성을 검사하는 데 사용되는 audience 문자열입니다.
allowedDataActions 배열입니다. allowedDataActions 배열은 문자열 값 Read만 포함할 수 있습니다.

{
  "authority": "string",
  "applications": [
    {
      "clientId": "string",
      "allowedDataActions": "array",
      "audience": "string"
    }
  ]
}

{
  "clientId": "string",
  "allowedDataActions": "array",
  "audience": "string"
}

다음 단계

Azure Active Directory B2C를 사용하여 FHIR 서비스에 대한 액세스 권한 부여

다중 ID 공급자 구성

참고 항목

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

다음을 통해 공유

FHIR 서비스에 대한 ID 공급자 구성 문제 해결

오류 메시지

FHIR API 요청 오류

ID 공급자를 구성하기 위한 스키마

다음 단계

피드백

추가 리소스