<TLDR> Want to add a custom domain to your APIM instance? Using Cloudflare? Generate a free SSL certificate in minutes.
When new API Management instance is created it's reachable with a default hostname from Azure:
If you add a
CNAME record pointing to that hostname (e.g.
api.your-company.com) and query the cname, you will get the
HTTP Error 503. The service is unavailable. error. That's because APIM uses the hostname to route the request internally (to the gateway / developer portal / management portal). And at this point it doesn't know anything about
In order to add a custom domain to APIM you need to present a valid SSL certificate for that domain.
If you have the certificate (purchased or generated with LetsEncrypt) you can upload that (and you're done).
In case you don't have it yet, and in case you use Cloudflare as a caching/protection layer (orange cloud ON) on top of your API it's very easy to generate a SSL certificate for API Management.
It takes 3 steps.
- Log in to Cloudflare dashboard
- Go to SSL/TLS tab
- Go to Origin Certificates / Create Certificate
- Check if you need to add anything to the hostnames list, otherwise keep the default settings. Click Next
PEMkey format. Save Origin Certificate to
api.your-company.com.pemfile and Private Key to
Cloudflare lets you export a certificate in
PEM format (common file extensions are
Azure wants the binary
PFX certificate format (common file extensions are
You can convert between these 2 formats using
openssl command line tool (available in OS X and *nix).
In the folder where you saved
.key files run:
openssl pkcs12 -export -out api.your-company.com.pfx -inkey api.your-company.com.key -in api.your-company.com.pem
Optionally provide a password.
- In Azure Portal, go to the API Management instance.
- Go to Custom Domains / Add
- Select the APIM component you're adding custom domain to (API Gateway / Management Portal / Developer Portal)
- Provide the hostname:
- Certificate: Custom / Select the pfx file.
It will take a few minutes to process the upload. Confirm
api.your-company.com no longer returns 503 but responds with valid APIM responses.
If you like this type of content you can follow me on Twitter for the latest updates.