Advanced Data Solutions : Azure API Management Developer Portal Troubleshooting

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:

Build an APIM service: tutorial
Understand how APIM developer portal works: https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-developer-portal

Introduction:

When we are using the developer portal, there are some dependencies with the following entities:

Management API on port 443,

Storage

SQL database

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.

Call the Developer portal status API: https://yourdeveloperportal.developer.azure-api.net/internal-status-0123456789abcdef

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:

You can also navigate to Azure portal Revisions blade to get the version information. Snapshot below:

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:

The request was targeted for APIM Management API (MAPI) endpoint

The request didn’t reach APIM Management API (MAPI) endpoint

The reason why request failed to reach APIM Management API (MAPI) endpoint is because TCP connection to APIM Management API (MAPI) endpoint on port 443 failed

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:

The request was targeted for APIM MAPI endpoint

APIM MAPI endpoint on port 443 was blocked

The reason why request failed to reach APIM MAPI endpoint is because custom domain for APIM MAPI endpoint cannot be resolved

This message indicates that the custom domain cannot be resolved. Possibilities are:

Custom domain of Management API(MAPI) is not registered in any DNS server

The client machine is located in a VNET where it uses a customized DNS server and it cannot resolve Management API(MAPI) custom domain

The APIM is deployed in an internal VNET, but the domain name is not registered in the DNS zone.

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=stv2#dns-configuration

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: