Custom domain name configuration for APIM endpoints in Microsoft Azure
When you create an Azure API Management service instance, Azure assigns it a sub domain of *.azure-api.net (for example, <apim-service-name>.azure-api.net).
However, you can expose your API Management endpoints using your own custom domain name, such as theoots.com. This tutorial shows you how to map an existing custom DNS name to endpoints exposed by an API Management instance.
There are a number of endpoints to which you can assign a custom domain name. Currently, the following endpoints are available:
Gateway (default is: <apim-service-name>.azure-api.net),
Developer Portal (Legacy) (default is: <apim-service-name>.portal.azure-api.net),
Developer Portal (default is: <apim-service-name>.developer.azure-api.net)
Management (default is: <apim-service-name>.management.azure-api.net),
SCM (default is: <apim-service-name>.scm.azure-api.net).
Please note <apim-service-name> above is a place holder that takes the name used when creating your APIM instance in Microsoft Azure portal. See image below for reference.
For the purpose of this guide, I will be configuring custom domain on only the Gateway and Developer Portal (Legacy) endpoints.
Prerequisites
• An active Azure subscription.
• An API Management instance. See link for more information on how to Create an Azure API Management instance.
• A custom domain name that is owned by you or your organization. For this tutorial, the portal endpoint is portal.theoots.com and the gateway endpoint is api.theoots.com
• A CNAME record hosted on a DNS server that maps the custom domain name to the default domain name of your API Management instance. This tutorial will cover instructions on how to map the custom domain name to the default domain name of your APIM endpoints.
• You must have a valid certificate with a public and private key (.PFX). Subject or subject alternative name (SAN) must match the domain name (this enables API Management instance to securely expose URLs over SSL).
Let’s get started!
My domain was bought on Microsoft Azure as such the CNAME mapping will be done there, depending on who your domain name registrar is, proceed to create a CNAME record and map your endpoints first:
Gateway
api.theoots.com — oauth2–0.azure-api.net
Developer Portal (Legacy)
portal.theoots.com — oauth2–0.portal.azure-api.net
As part of the prerequisite, endeavor to have a valid certificate with a public and private key (.pfx), as that will be required in the next step of the configuration. So if you do not already have that, please grab it and proceed to the next step.
Once that is done, you can now proceed to the Custom domains blade of your API Management service and Click on + Add.
Populate the settings as below:
At the point where you need to select a certificate file, navigate to where you saved the valid .pfx certificate, then input the password. When it gets uploaded, you will receive an upload completed notification.
After that, repeat same procedure for the other endpoint. Once done for both endpoints, then proceed to click on save and wait for the changes to take effect.
Please note that you can only use the same certificate for both endpoints if it was purchased as a Wild Card certificate.
If the above steps are done properly, again you will get a notification with a success message.
Navigate to the overview blade of your APIM Service, you will notice that the Gateway URL must have changed as seen in the image below.
Now you can reach the Developer Portal (Legacy) by visiting the configured URL portal.theoots.com from a browser.
Conclusion
With the steps highlighted above, we have been able to configure custom domains on the Gateway and Developer Portal (Legacy) endpoints of an API Management services. The same can be achieved on other endpoints as well.
If you found this guide helpful, please consider following me on Twitter and connecting on LinkedIn. Don’t forget to give this article a 👏 if you enjoyed reading it as a show of support. Thanks! ✌️
