Background:
For Azure API Management (APIM) developer portal users, there are some common troubleshooting scenarios. This blog is going to introducing the developer design and dependencies first, and then going to explain the most common scenarios and errors you might meet, and how you can troubleshoot by yourself.
Pre-requirements:
Introduction:
When we are using the developer portal, there are some dependencies with the following entities:
By mentioning these dependencies, it means that we must make sure the connection between APIM service and these entities are success.
Troubleshooting Scenarios:
Scenario 1: AAD changes not reflected in the Developer portal
If you have some recent changes in the Developer portal in an admin mode, but when you come back and check in a regular user mode, you are not able to see the changes after your modification. This might be caused by the changes has not been saved/published.
Example 1: I have added the sign in button to Authorize developer accounts by using Azure Active Directory in Azure API Management but there is not yet an AAD sign-in button when the consumers visits the portal even though I added it on the admin side.
In this case, you can start with your changes again, then make sure you click that Save button at the left bottom side. After saving the changes, click on the publish button on the left side. Finally, verify your changes by logging in with a regular user mode.
To verify your publishment success or not, there are two ways you can do.
You could check the PortalVersion and the Version number, and see if they match your publishment. The PortalVersion is in the format of YYYYMMDDTT, so you can compare the time with your pulish time.
At the same time, you would need to make sure the PortalVersion should be later than CodeVersion, otherwise, it wouldn’t be supported.
An example here:
Example 2: I have followed the following article to protect my backend APIs with OAuth 2.0 AAD but the developer console still does not show the AAD Auth option under the Authorization section
In this example, first of all, I am going to check my publish status and make sure it has been completed successfully. The reason is that these AAD configuration changes need to be published before I can use them.
Please also notice that a click on the Save button in the developer portal is not required, as I have done in Example 1. Because the AAD configuration change wouldn’t affect the developer portal UI.
Scenario 2: Connectivity Issues
If you cannot load your developer portal page, and you find some 500 errors when you try to open the developer portal with both user mode and admin mode.
For example, screenshots below.
In this case, it could be related to the network connectivity. We can navigate to the Network connectivity status blade, check the connectivity status of all the types. If we find some error, such as the storage connectivity error, we could go back to check the VNet setting, like the NSG, route table, etc..
Scenario 3: Missing Custom Domain for the Management API
If I want to access my developer portal in admin mode to do some UI editing but I couldn’t. As result, I got the error message ‘unable to start the portal’, like the screenshot below:
We could start with reproducing the issue and collecting the network trace from the browser debug panel.
If we find some error from browser trace basically indicates:
In this case, if my APIM is deployed in internal VNET and I am using app gateway to expose it to public. Then I need to check my App GW setting, and make sure I have exposed my APIM proxy, developer portal and Management API to public. The reason we need to expose Management API(MAPI) is that the developer portal has dependencies on Management API on port 443, as what I have mentioned in the introduction part.
For the snapshot below, I could see that I have only exposed the proxy and the developer portal, but not my MAPI.
Scenario 4: Missing Custom Domain for the Management API – continued (403 forbidden)
Once we have exposed the custom domain of our Management API, some extra steps are needed if you have enabled the Web Application Firewall(WAF).
As documented in this link, we would need to disable the rules 931130, 942260, 942200, 942100 and 942110 as these would block MAPI calls from the developer portal and return a 403 Forbidden error.
We can navigate to the App Gateway, and then uncheck the relative rules of the WAF as below:
Scenario 5: DNS Resolution Issue for the Management API
If I want to access my developer portal in admin mode to do some UI editing but I couldn’t. As result, I got the error message “unable to start the portal”, like the screenshot below:
At this time, we would collect the network trace of browser debug panel first.
If the error from browser trace basically indicates:
This message indicates that the custom domain cannot be resolved. Possibilities are:
In this scenario, we would need to check the DNS server or the Azure DNS server. And make sure we have registered the domains/ custom domains as required.
Here is an example how you can configure the Azure DNS private zone for your APIM in internal VNet: https://docs.microsoft.com/en-us/azure/api-management/api-management-using-with-internal-vnet?tabs=s...
Scenario 6: Invalid SSL certificate for the Management API
If I want to access my developer portal in admin mode to do some UI editing but I couldn’t. As result, I got error message “unable to start the portal” , like the screenshot below:
At this time, we would collect the network trace of browser debug panel first.
If the error from browser trace basically indicates:
The error message indicated that the certificate is not valid, which means the certificate used here is not trusted. Some possible causes as below:
In this case, we can go to APIM Certificates blade, upload the certificate to the APIM certificate store, so it can be trusted by APIM in the future.
Other FAQs:
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.