你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
排查 FHIR 服务的标识提供者配置问题
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 或为空,并且值为字符串类型。 |
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 许可使用。