Introduction
Although Azure API for FHIR is relatively easy to provision, it is not always easy to configure permissions. In this article, I will show you how to troubleshoot some common reasons why a request might fail with a HTTP 401 or 403 error code.
Diagnose your issue using the following decision tree diagram.
401: No Token or Invalid Token
Possible Issues:
- No JWT bearer token sent with request.
- Invalid JWT bearer token.
If the response code is a HTTP 401, you most likely did not include a valid Bearer token with your request. There are several ways to get an access token from Azure Active Directory. To quickly generate an access token using the Azure CLI, follow the steps in this document: https://docs.microsoft.com/en-us/azure/healthcare-apis/azure-api-for-fhir/get-healthcare-apis-access.... If you are the person who setup this instance of Azure API for FHIR, then you should already have access. The CLI token is a quick way to fetch a token that can be used for debugging and troubleshooting API calls using tools like Postman.
For more information on how to obtain access tokens for use with Azure API for FHIR, see https://docs.microsoft.com/en-us/azure/healthcare-apis/azure-api-for-fhir/azure-active-directory-ide....
403: Unauthorized
Possible Issues:
- RBAC configuration
- Token validation
First, let's check the Authority value configured for your API. In the Azure Portal, browse to your FHIR API and switch to the Authentication tab. The authority will determine which instance or "tenant" of Azure Active Directory is being used as your identity provider. This value can either be the same tenant that contains the Azure Subscription where your FHIR API is provisioned, OR it can be a secondary/remote tenant. Here are two sample Authority values: https://login.microsoftonline.com/abfde7b2-df0f-47e6-aabf-2462b07508dc -or- https://login.microsoftonline.com/contoso.onmicrosoft.com.
Then, check your RBAC permissions depending on the tenant scenario you have configured.
Home Tenant
If you are using the same AAD tenant to secure the API, then RBAC permissions can be managed using the Access Control (IAM) blade on your FHIR API resource in the Azure Portal. You could also use any other standard mechanism of managing role assignments such as Azure PowerShell or the Azure CLI. Verify that the correct users, groups, and service principals have been assigned using Access Control (IAM).
Secondary/Remote Tenant
If you use a secondary tenant as your identity provider, you will NOT be able to use the Access Control (IAM) blade to control permissions. Instead, you will have to manually edit the list of Allowed Object IDs from the Authentication section of your FHIR API resource. This can be a bit tedious, especially if you have a large number of individual users who should have access. Also, when you update the allow list, it can take several minutes for the change to persist.
Pro Tip: Create a Group in your target AAD and add the Object ID of that group to the allow list. Then you can easily add/remove users to the group and not have to wait for the update on the FHIR API resource.
The Object ID for the User or Group can be found by browsing to Azure AD in the Azure Portal and viewing its details.
Take extra care when adding service principals (client credential flow) to the allow list. The Application ID of the app registration in AAD is NOT the same as the Object ID of the SPN required to grant access. The Object ID is available from the Overview tab on your app registration.
If your RBAC permissions appear to be configured correctly, proceed to the next section about Token Validation.
Token Validation
Token validation is the process by which Azure API for FHIR will determine if a request includes an appropriate JWT token and is authorized. For detailed information about the token validation process, see Access Token Validation.
When troubleshooting access issues, it is important for you to understand how to inspect the JWT token to determine if the claims being presented are correct. First, you will need to copy the token. The token can be found by inspecting the request's Authorization header value either in Postman or the Network tab of your browser's developer tools. Next, use jwt.ms to inspect the claims presented by your token.
Your decoded token should look similar to the image above. Check the highlighted claims:
- The Tenant ID in the iss claim MUST match the Tenant ID in the Authority value configured for your FHIR API instance. NOT the full URL, just the ID portion.
- Double-check that the Audience value configured on your FHIR API EXACTLY matches the value in the aud claim.
- The oid claim is the Object ID of the User/Group/Service Principal requesting access. If this Object ID has not been added using either Access Control (IAM) or to the Allowed Object IDs list (depending on your home/remote tenant scenario), you WILL receive a 403 error.
**Note that if you are granting users access via a group, then the User Object ID will not appear in the allow list. Only the Group Object ID needs to be added
Other problems
If your response code is not 401 or 403 the problem is most likely not related to authentication and authorization, and is outside the scope of this article.