Troubleshoot identity provider configuration for the FHIR service
API version 2023-12-01 of the FHIR® service in Azure Health Data Services supports two identity providers in addition to Microsoft Entra ID. To provide scoped access to users, configure the two identity providers by populating the smartIdentityProviders
section of the authenticationConfiguration
object.
Error messages
Here are the error messages that occur if the FHIR service SMART identity providers fail, with recommended actions to take to resolve the issue.
Error | Cause | Fix |
---|---|---|
The maximum number of SMART identity providers is 2. | The number of identity providers configured is more than two. | Reduce the number of identity providers to two or less. |
One or more SMART identity provider authority values are null, empty, or invalid. | The authority element of the identity provider configuration must be a fully qualified URL. |
Ensure all authority values are fully qualified URLs. |
All SMART identity provider authorities must be unique. | The authority elements of the two identity provider configurations are identical. |
Ensure all authority values are unique, fully qualified URLs. |
The maximum number of SMART identity provider applications is 2. | The number of identity provider applications in an identity provider configuration is more than two. | Reduce the number of identity provider applications to one or two per identity provider. |
One or more SMART applications are null. | The applications element for one or more identity providers is null or contains no applications. |
Ensure all identity provider configurations have at least one application configured. |
One or more SMART application allowedDataActions contain duplicate elements. |
The allowedDataActions array in one or more application configurations contains duplicate values. |
Remove any duplicate values in the allowedDataActions arrays. |
One or more SMART application allowedDataActions values are invalid. |
The only acceptable value in the allowedDataActions array is Read . |
Remove any nonconforming values from the allowedDataActions arrays. |
One or more SMART application allowedDataActions values are null or empty. |
The allowedDataActions array in one or more application configurations is null or empty. |
The only acceptable value in the allowedDataActions array is Read . |
One or more SMART application audience values are null, empty, or invalid. |
The audience string in one or more application configurations is null, empty, or malformed. |
Ensure the audience string isn't null or empty and that the value is a string type. |
All SMART identity provider application client ids must be unique. | The clientId value in one or more application configurations is the same value as another clientId value. |
Ensure all clientId values are unique (including across identity provider configurations). |
One or more SMART application client id values are null, empty, or invalid. | The clientId string in one or more application configurations is null, empty, or malformed. |
Ensure the clientId string isn't null or empty and that the value is a string type. |
FHIR API request errors
When you use a token issued by a SMART identity provider to make requests to the FHIR service, you might encounter two common error codes: 401 Unauthorized
or 403 Forbidden
. To start troubleshooting, check the configuration of the smartIdentityProviders
element, especially if the FHIR service is new.
Follow these steps to verify the correct configuration of the smartIdentityProviders
element.
Verify the
smartIdentityProviders
element is configured correctly.Verify the
authority
string is correct. Ensure theauthority
string is the token authority for the identity provider that issued the access token.Verify the the
authority
string is a valid token authority. Make a request for the openid-connect configuration. Append/.well-known/openid-configuration
to the end of theaubrowser navigatesthority
string, and then paste it into your browser. If the value is correct, the browser navigates to theopenid-connect configuration
. If it doesn't, there's a problem with the string.Example:
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
Verify the
clientId
string is correct. Ensure theclientId
string matches the client ID (or application ID) of the resource application defined in the identity provider.Verify the request method is GET. The only supported request type is
GET
, because theallowedDataActions
values only supportRead
.Verify the JSON web token (JWT) claims. If the access token is available, decode it by using online tools such as jwt.ms. After the token is decoded, the claims can be inspected for correctness.
Verify the iss (issuer claim). Make sure the
iss
claim exactly matches theissuer
value in your identity providers OpenId Configuration.Take the
authority
value from thesmartIdentityProvider
identity provider configuration, append it with/.well-known/openid-configuration
, and then paste it in your browser. If the value is correct, the browser navigates to the openid-connect configuration.Example:
https://<YOUR_IDENTITY_PROVIDER_AUTHORITY>/authority/v2.0/.well-known/openid-configuration
Verify the azp or appid (authorized party or appid claim). The
azp
orappid
claim must exactly match theclientId
value provided in thesmartIdentityProvider
identity provider configuration.Verify the aud (audience claim). The
aud
claim must exactly match theaudience
value provided in thesmartIdentityProvider
identity provider configuration.Verify the scp (scope claim). The
scp
claim is required. If it's missing, the request fails. The format of the scp claim must conform to SMART on FHIR v1 Scopes. It's important to note that the FHIR service currently only supports Read scopes. An acceptable variation of SMART on FHIR v1 Scopes replaces any forward slash (/) with a period (.) and asterisk (*) withall
. For example, an acceptable version of the SMART on FHIR scopepatient/*.read
ispatient.all.read
.
Note
Only read
scopes are supported.
- Verify the fhirUser or extension_fhirUser (FHIR user claim). The
fhirUser
orextension_fhirUser
claim is required. If it's missing, the request fails. This claim links the user in the identity provider with a user resource in the FHIR service. The value must be the fully qualified URL of a resource in the FHIR service that represents the individual that the access token is issued to. For example, the access token issued to a patient that logged in should have afhirUser
orextension_fhirUser
claim that has the fully qualified URL of a patient resource in the FHIR service.
Schema for configuring identity providers
The smartIdentityProviders
element is a JSON array that contains one or two identity provider configurations
. An identity provider configuration
consists of
An
authority
string value that must be the fully qualified URL of the identity providers token authority.An
applications
array that contains identity provider resourceapplication configurations
.
{
"properties": {
"authenticationConfiguration": {
"authority": "string",
"audience": "string",
"smartProxyEnabled": "bool",
"smartIdentityProviders": [
{
"authority": "string",
"applications": [
{
"clientId": "string",
"allowedDataActions": "array",
"audience": "string"
}
]
}
]
}
}
}
The applications
element is a JSON array that contains one or two application configurations
.
The application configuration
consists of:
A
clientId
string value for the client ID (also known as application ID) of the identity provider resource application.An
audience
string used to validate theaud
claim in access tokens.An array of
allowedDataActions
. TheallowedDataActions
array can only contain the string valueRead
.
{
"authority": "string",
"applications": [
{
"clientId": "string",
"allowedDataActions": "array",
"audience": "string"
}
]
}
{
"clientId": "string",
"allowedDataActions": "array",
"audience": "string"
}
Next steps
Use Azure Active Directory B2C to grant access to the FHIR service
Configure multiple identity providers
Note
FHIR® is a registered trademark of HL7 and is used with the permission of HL7.