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.
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....
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.
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).
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 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:
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.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.