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.

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.

1. Verify the smartIdentityProviders element is configured correctly.

2. Verify the authority string is correct. Ensure the authority string is the token authority for the identity provider that issued the access token.

3. 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 the aubrowser navigatesthority string, and then paste it into your browser. If the value is correct, the browser navigates to the openid-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
   
   

4. Verify the clientId string is correct. Ensure the clientId string matches the client ID (or application ID) of the resource application defined in the identity provider.

5. Verify the request method is GET. The only supported request type is GET, because the allowedDataActions values only support Read.

6. 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.

   

7. Verify the iss (issuer claim). Make sure the iss claim exactly matches the issuer value in your identity providers OpenId Configuration.

   Take the authority value from the smartIdentityProvider 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
   

8. Verify the azp or appid (authorized party or appid claim). The azp or appid claim must exactly match the clientId value provided in the smartIdentityProvider identity provider configuration.

9. Verify the aud (audience claim). The aud claim must exactly match the audience value provided in the smartIdentityProvider identity provider configuration.

10. 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 (*) with all. For example, an acceptable version of the SMART on FHIR scope patient/*.read is patient.all.read.

11. Verify the fhirUser or extension_fhirUser (FHIR user claim). The fhirUser or extension_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 a fhirUser or extension_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 resource application 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 the aud claim in access tokens.

• An array of allowedDataActions. The allowedDataActions array can only contain the string value Read.

{
  "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