你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

排查 FHIR 服务的标识提供者配置问题

项目
12/04/2024

Azure Health Data Services 中 FHIR® 服务的 API 版本 2023-12-01 除了 Microsoft Entra ID 之外，还支持两个标识提供者。若要向用户提供限定范围的访问权限，可以通过填充 authenticationConfiguration 对象的 smartIdentityProviders 部分来配置这两个标识提供者。

错误消息

下面是 FHIR 服务 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 标识提供者应用程序客户端 ID 都必须是唯一的。	一个或多个应用程序配置中的 `clientId` 值与另一个 `clientId` 值相同。	确保所有 `clientId` 值都是唯一的（包括在标识提供者配置之间）。
一个或多个 SMART 应用程序客户端 ID 值为 null、空或无效。	一个或多个应用程序配置中的 `clientId` 字符串为 null、空或格式不正确。	确保 `clientId` 字符串不为 null 或为空，并且值为字符串类型。
使用第三方标识提供者的 Azure Health Data Services FHIR API 授权失败。	FHIR SMART 用户角色会导致此问题，因为它添加了身份验证层。	确保未分配 FHIR SMART 用户角色。

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（或应用程序 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 元素是一个 JSON 数组，其中包含一个或两个 identity provider configurations。 identity provider configuration 包括

authority 字符串值，该值必须是标识提供者令牌颁发机构的完全限定 URL。
包含标识提供者资源 application configurations 的 applications 数组。

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

applications 元素是一个 JSON 数组，其中包含一个或两个 application configurations。

application configuration 包括：

标识提供者资源应用程序的客户端 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 服务的访问权限

配置多个标识提供者

注意

FHIR® 是 HL7 的注册商标，经 HL7 许可使用。

通过

排查 FHIR 服务的标识提供者配置问题

错误消息

FHIR API 请求错误

用于配置标识提供者的架构

后续步骤

反馈

其他资源