URL Rewrite Rules in web.config: HTTPS, www and 301 Redirects

On Windows Hosting, redirects and pretty URLs are handled by the IIS URL Rewrite module, configured with rules in web.config. It is the IIS equivalent of Apache's mod_rewrite and .htaccess rules, which IIS ignores.

All the rules below go inside <system.webServer><rewrite><rules>. If you are new to web.config, read web.config Essentials for Windows Hosting first.

How a rule is built

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Unique name" stopProcessing="true">
          <match url="regex matched against the path" />
          <conditions>
            <add input="{SERVER_VARIABLE}" pattern="regex" />
          </conditions>
          <action type="Redirect" url="new address" redirectType="Permanent" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

                        
                    

• match url is tested against the path without the leading slash and without the query string. For https://example.com/shop/item?id=5 it sees shop/item.
• {R:1} in the action inserts the first captured group from match; {C:1} inserts one from the last matched condition.
• redirectType="Permanent" sends a 301, which search engines follow and remember. Use Found (302) while testing so browsers don't cache a mistake.
• Rules run top to bottom. stopProcessing="true" stops further rules once one matches.
• The query string is kept by default on redirects (appendQueryString="true").

Force HTTPS

First activate your SSL certificate (see SSL and HTTPS on Windows Hosting). Then add:

<rule name="Force HTTPS" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
    <add input="{HTTPS}" pattern="^OFF$" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
</rule>

                        
                    

If you get “too many redirects”: on our platform, HTTPS can be handled in front of the web server, so IIS may see every request as plain HTTP. In that case, test the forwarded protocol header instead:

<rule name="Force HTTPS (behind proxy)" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
    <add input="{HTTP_X_FORWARDED_PROTO}" pattern="^http$" />
  </conditions>
  <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
</rule>

                        
                    

Use only one of the two rules. If StackCP shows a Force HTTPS switch on the SSL/TLS page for your site, you can use that instead of a rule; just don't use both, or you may create a loop.

Redirect non-www to www (or the reverse)

<rule name="Add www" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="^example\.com$" />
  </conditions>
  <action type="Redirect" url="https://www.example.com/{R:1}" redirectType="Permanent" />
</rule>

                        
                    

To go the other way (remove www):

<rule name="Remove www" stopProcessing="true">
  <match url="(.*)" />
  <conditions>
    <add input="{HTTP_HOST}" pattern="^www\.example\.com$" />
  </conditions>
  <action type="Redirect" url="https://example.com/{R:1}" redirectType="Permanent" />
</rule>

                        
                    

Replace example.com with your domain and escape each dot as \.. Because the target already uses https://, this also upgrades HTTP in one hop. Put the HTTPS rule after it.

Redirect a single page

<rule name="Old about page" stopProcessing="true">
  <match url="^about-us\.aspx$" />
  <action type="Redirect" url="/about" redirectType="Permanent" />
</rule>

                        
                    

Redirect a whole folder

<rule name="Blog moved" stopProcessing="true">
  <match url="^blog/(.*)" />
  <action type="Redirect" url="/news/{R:1}" redirectType="Permanent" />
</rule>

                        
                    

Many redirects: use a rewrite map

After a redesign you may have dozens of old URLs. A rewrite map keeps them in one list:

<rewrite>
  <rewriteMaps>
    <rewriteMap name="OldUrls">
      <add key="/products.asp" value="/shop" />
      <add key="/contact.htm" value="/contact" />
      <add key="/team.aspx" value="/about/team" />
    </rewriteMap>
  </rewriteMaps>
  <rules>
    <rule name="Old URL map" stopProcessing="true">
      <match url=".*" />
      <conditions>
        <add input="{OldUrls:{REQUEST_URI}}" pattern="(.+)" />
      </conditions>
      <action type="Redirect" url="{C:1}" redirectType="Permanent" appendQueryString="false" />
    </rule>
  </rules>
</rewrite>

                        
                    

Keys are compared against {REQUEST_URI}, which includes the leading slash (and the query string, if there is one).

Clean URLs: hide .html or .aspx

Serve /about from about.html without changing the address bar (a rewrite, not a redirect):

<rule name="Extensionless html" stopProcessing="true">
  <match url="^([^.]+)$" />
  <conditions>
    <add input="{REQUEST_FILENAME}.html" matchType="IsFile" />
  </conditions>
  <action type="Rewrite" url="{R:1}.html" />
</rule>

                        
                    

For ASP.NET Web Forms, Microsoft.AspNet.FriendlyUrls or routing in RouteConfig is usually a cleaner choice than rewrite rules. MVC sites already have clean URLs through routing.

Single-page app (React, Vue, Angular) fallback

Send every request that isn't a real file or folder to index.html, so deep links and page refreshes work:

<rule name="SPA fallback" stopProcessing="true">
  <match url=".*" />
  <conditions logicalGrouping="MatchAll">
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
    <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
    <add input="{REQUEST_URI}" pattern="^/api/" negate="true" />
  </conditions>
  <action type="Rewrite" url="/index.html" />
</rule>

                        
                    

Remove the /api/ line if your API lives elsewhere.

Testing tips

• Test with redirectType="Found" first, then switch to Permanent. Browsers cache 301s hard, so test in a private window.
• Check a redirect from a terminal: curl -I http://example.com/old-page shows the status code and Location header.
• The preview address (stackstaging.com) doesn't support HTTPS, so an HTTPS or domain redirect sends you to the live domain. Test those rules on the real domain.

Common problems

• HTTP 500.19 mentioning rewrite. The XML is malformed (check for an unescaped &; write it as &) or you have two <rewrite> sections. If the XML is valid and the error says the rewrite element isn't recognised, contact support.
• Redirect loop. Two rules undo each other, or HTTPS is forced both by a rule and elsewhere. Remove one.
• Rule never fires. Remember match url has no leading slash: use ^blog/, not ^/blog/.

Need help?

If something doesn't work as described, open a support ticket from your client area or message us on WhatsApp at 01818160926. Send us the rule, the URL you tested and what happened.