Azure API Management Developer Portal Troubleshooting

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Tech Community.


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. 





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. 

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: 



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 request was targeted for APIM MAPI endpoint  
  • The request didn’t reach APIM MAPI endpoint  
  • The reason why request failed to reach APIM MAPI endpoint is because SSL for custom domain for APIM MAPI endpoint are not trusted. 



The error message indicated that the certificate is not valid, which means the certificate used here is not trusted. Some possible causes as below:   

  • The certificate is self-signed 
  • The certificate is a CA cert, but the root certificate of certificate chain is not trusted by Microsoft 


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: 



REMEMBER: these articles are REPUBLISHED. Your best bet to get a reply is to follow the link at the top of the post to the ORIGINAL post! BUT you're more than welcome to start discussions here:

This site uses Akismet to reduce spam. Learn how your comment data is processed.