針對 FHIR 服務的識別提供者設定進行疑難排解

發行項
10/16/2024

Azure 健康資料服務中 FHIR® 服務的 API 版本 2023-12-01 除了 Microsoft Entra ID之外，還支援兩個識別提供者。若要提供使用者的範圍存取，請填入 authenticationConfiguration 物件的 smartIdentityProviders 區段，以設定兩個身分識別提供者。

錯誤訊息

以下是 FHIR service SMART 身分識別提供者失敗會出現的錯誤訊息，以及解決該問題建議採取的動作。

錯誤	原因	Fix
SMART 識別提供者的最大數目是 2。	設定的識別提供者數目超過兩個。	將識別提供者的數目減少到兩個或更少。
一或多個 SMART 識別提供者授權單位值為 Null、空白或無效。	識別提供者組態的 `authority` 元素必須是完整 URL。	確定所有 `authority` 值都是完整 URL。
所有 SMART 識別提供者授權單位都必須是唯一的。	兩個識別提供者組態的 `authority` 元素完全相同。	請確定所有 `authority` 值都是唯一、完整的 URL。
SMART 識別提供者應用程式的最大數目是 2。	識別提供者組態中的識別提供者應用程式數目超過兩個。	將識別提供者應用程式數目減少為每個識別提供者一或兩個。
一或多個 SMART 應用程式為 Null。	一或多個識別提供者的 `applications` 元素為 Null，或不包含任何應用程式。	請確定所有識別提供者組態都已設定至少一個應用程式。
一或多個 SMART 應用程式 `allowedDataActions` 包含重複元素。	一或多個應用程式組態中的 `allowedDataActions` 陣列包含重複的值。	請移除 `allowedDataActions` 陣列中的任何重複值。
一或多個 SMART 應用程式 `allowedDataActions` 值無效。	`allowedDataActions` 陣列中唯一可接受的值為 `Read`。	從 `allowedDataActions` 陣列中移除任何不符合格式的值。
一或多個自我監控分析與報告技術系統 (SMART) 應用程式 `allowedDataActions` 值為 null 或空白。	一或多個應用程式組態中的 `allowedDataActions` 陣列為 null 或空白。	`allowedDataActions` 陣列中唯一可接受的值為 `Read`。
一或多個 SMART 應用程式 `audience` 值是 Null、空白或無效。	一或多個應用程式組態中的 `audience` 字串為 Null、空白或格式錯誤。	請確定 `audience` 字串不是 Null 或空白，而且值是字串類型。
所有 SMART 識別提供者應用程式用戶端識別碼都必須是唯一的。	一或多個應用程式組態中的 `clientId` 值與另一個 `clientId` 值相同。	請確定所有 `clientId` 值都是唯一的 (包括跨識別提供者組態)。
一或多個 SMART 應用程式用戶端識別碼值為 Null、空白或無效。	一或多個應用程式組態中的 `clientId` 字串為 Null、空白或格式錯誤。	請確定 `clientId` 字串不是 Null 或空白，而且值是字串類型。

FHIR API 要求錯誤

您使用 SMART 識別提供者發出的權杖向 FHIR 服務提出要求時，可能會遇到兩個常見的錯誤碼：401 Unauthorized 或 403 Forbidden。若要開始疑難排解，請檢查 smartIdentityProviders 元素的組態，特別是 FHIR 服務是否為新的。

請依照下列步驟驗證 smartIdentityProviders 元素的正確組態。

確認 smartIdentityProviders 元素已正確設定。
確認 authority 字串正確無誤。請確定 authority 字串是發出存取權杖之識別提供者的權杖授權單位。
驗證 authority 字串是有效的權杖授權單位。提出 openid-connect 組態的要求。將 /.well-known/openid-configuration 附加至 aubrowser navigatesthority 字串的結尾，然後將其貼上至瀏覽器中。如果值正確，瀏覽器會瀏覽至 openid-connect configuration。如果沒有，就是字串有問題。

範例：
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
確認 clientId 字串正確無誤。請確定 clientId 字串符合識別提供者中定義之資源應用程式的用戶端識別碼 (或應用程式 ID)。
驗證要求方法為 GET。唯一支援的要求類型是 GET，因為 allowedDataActions 值僅支援 Read。
驗證 JSON Web 權杖 (JWT) 宣告。如果存取權杖可用，請使用線上工具 (例如 jwt.ms) 來解碼。解碼權杖後，即可檢查宣告的正確性。
驗證 iss (簽發者宣告)。請確定 iss 宣告完全符合識別提供者 OpenId 組態中的 issuer 值。

從 smartIdentityProvider 識別提供者組態取得 authority 值，為其附加 /.well-known/openid-configuration，並將其貼上至瀏覽器。如果值正確，瀏覽器會瀏覽至 openid-connect 組態。

範例：
```
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
```
驗證 azp 或 appid (授權方或 appid 宣告)。 azp 或 appid 宣告必須完全符合 smartIdentityProvider 識別提供者組態中提供的 clientId 值。
驗證 aud (對象宣告)。 aud 宣告必須完全符合 smartIdentityProvider 識別提供者組態中提供的 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 宣告是必要的。如果遺漏，要求會失敗。此宣告會將識別提供者中的使用者與 FHIR 服務中的使用者資源連結。此值必須是 FHIR 服務中資源的完整 URL，代表存取權杖簽發對象的個人。例如，向登入的病患發出的存取權杖應該具有 FHIR 服務中病患資源之完整 URL 的 fhirUser 或 extension_fhirUser 宣告。

設定識別提供者的結構描述

smartIdentityProviders 元素是包含一或兩個 identity provider configurations 的 JSON 陣列。 identity provider configuration 包含：

authority 字串值，必須是識別提供者權杖授權單位的完整 URL。
applications 陣列，包含識別提供者資源 application configurations。

{
  "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) 的 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 服務的存取權授與

設定多個識別提供者

注意

FHIR® 是 HL7 的註冊商標，在 HL7 的許可下使用。

共用方式為

針對 FHIR 服務的識別提供者設定進行疑難排解

錯誤訊息

FHIR API 要求錯誤

設定識別提供者的結構描述

下一步

意見反應

其他資源