Deprecating Subdomains Effectively With Windows Azure and IIS

Written by Khalid Abuhakmeh

We are in the process of deprecating many smaller subdomain app services and serving the same content through our flagship site. This post will walk you through our strategy of decommissioning our subdomains, maintaining active redirects, and saving your Windows Azure credits for future endeavors.


In this post, we have to define all of our ingredients for a successful switch.

  • Subdomain usually * but could be any domain.
  • Primary domain is the final target.
  • DNS Records
  • IIS Web.config and Rewrite Rules

Our goal is to take a subdomain ( and redirect traffic to a page on your main domain ( successfully.

Step 1: Rewrite Rules On Main Domain

We first need to set up our primary domain to handle the traffic of our subdomain. In a later step, we will change our subdomain records to point to the main domain’s URL. To do this, we need an IIS web.config rewrite rule on our primary site.

<rule name="Subdomain redirect" enabled="true">
    <match url="(.*)" ignoreCase="true" />
      <!-- The subdomain you are deprecating -->
      <add input="{HTTP_HOST}" pattern="" />
    <!-- The new targeted page on the main domain -->
    <!-- redirectType can be Temporary or Permanent -->
    <action type="Redirect"
            appendQueryString="true" />

Be sure to deploy this change to your primary domain’s Azure App Service before moving on to step #2.

Note: It is essential to do this via IIS and not your DNS provider’s servers, especially if you are using HSTS. If you do use your DNS provider’s redirect, the serving SSL certificate will be theirs, and most modern browsers will fail the redirect. Again, DO NOT USE YOUR DNS’ Providers REDIRECT, IT MAY SEEM EASY BUT WILL MOST LIKELY RESULT IN PAIN.

Step 2: Switch DNS Record

In your DNS providers dashboard, add a CNAME record to the subdomain that points to your primary site’s azure app service. The change effectively makes your main domain also your subdomain.

Step 3: Setting Your Domains in Azure

Now that we’ve deployed the redirect rule, we need to change some domain settings in our Windows Azure settings.

  1. Login to Windows Azure and go to your App Service.
  2. Go to the Custom Domains blade.
  3. Add a Custom Domain of your subdomain (

Note: You may not be able to validate the custom domain until you verify the DNS record from Step #2.

Step 4: Decomission Subdomain App Service

You can now stop the App Service for your subdomain. It is no longer necessary since any traffic to the subdomain is going to your primary domain’s App Service. Additionally, the redirect rule will automatically redirect any subdomain URLs to the intended target URL.

Once you’ve confirmed all changes are working, you can delete the subdomain app service and count the money in your bank account.


When complete, you should have all subdomains redirecting to your main site, be down at least one App Service, still be using your SSL certificates, and everyone will be happy. This process takes a few steps, but its reproducible and reliable. Hopefully, you found this post helpful.

Published July 12, 2019 by

undefined avatar
Khalid Abuhakmeh Director of Software Development (Former)

Suggested Reading