Apps

URL rewriting with IIS's URL Rewrite module

Justin James shows you how to use IIS's URL rewriting module and how to create your own rules.

I recently wrote about how to use Apache's mod_rewrite module to perform URL rewriting. Today, I am going to give you an introduction to doing the same thing, but with IIS' URL Rewrite module. While the ideas are the same, IIS's implementation is GUI driven (although you can edit the configuration directly, of course), and has a few unique ways of doing things of its own.

The first thing that you will need to do, is to install URL Rewrite. You can download it directly, or install it through the Web Platform Installer (Web PI). Once it is installed, you will see a new "Url Rewrite" icon in the IIS management console (Figure A).

Figure A: The IIS Management Console with URL Rewrite added

You can manage URL Rewrite at the server level or for individual sites as you see fit. Through the URL Rewrite module, you will see "patterns" used. The patterns are in one of three modes: exact match, wildcards (where an asterisk is used to mean "anything here" and is captured when matched), and ECMAScript regular expressions, which are Perl compatible regular expressions.

There are two rule types, inbound and outbound. Inbound rules look at the request URLs and change them. Outbound rules inspect the traffic sent out, look for URLs within it, and rewrite them as needed. This is great when the content may use an absolute URL that is not what the user should be receiving (especially handy in reverse proxy scenarios).

One of the nice things about URL Rewrite is that it supports a number of different built-in rules (Figure B) which make life easy when you want to do a common rewrite. The full list of built-in rules is:
  • Rule with rewrite map: allows you to define a set of paths and their replacements as a simple list.
  • Request blocking: disallow access to a path.
  • User-friendly URL: quickly creates rules to map path segments (separated by slashes) to query strings.
  • Reverse Proxy: allows the current server to reverse proxy another.
  • Enforce lowercase URLs: makes the client always use lowercase URLs via an HTTP status 301 ("Permanent") redirect.
  • Canonical domain name: uses an HTTP status 301 ("Permanent") redirect to ensure that clients always use the specified domain name.
  • Append or remove the trailing slash symbol: will either always add or always remove the trailing slash in an URL path using an HTTP status 301 ("Permanent") redirect.

Figure B: Creating a rule lets you pick a built-in rule to start from

The built-in rules are great, because while they start you with tailored wizard where appropriate, they generate standard rules that you can then tweak or modify as needed.

The user-friendly URL rule is pretty popular for those who do not have a system that does it automatically. You start by entering in an example of the "ugly" URL that the site actually requires. In my example, I put in: "http://www.demosite.titaniumcrowbar.com/cms.aspx?cat=docs&id=13". I was then offered four suggested examples of user-friendly URLs, each of which followed a slightly different pattern of translating path segments to the query string parameters. In the dropdown, you choose which example you like best, and it will show you the URL matching and substitution patterns that the rule will use. Once you choose one, you are, of course, able to edit and tweak it as needed.

Figure C: Creating a user-friendly URL rule
Another of the built-in rules that I use quite a bit is the reverse proxy rule. Again, the system walks you through a competent default configuration of what could be a very complex task (Figure D). It has some nice built-in options that you can change, such as whether HTTPS responses should be always proxied to standard HTTP (to reduce server load), and whether or not you want to use an outbound rule to mask the internal server name. I often use this so that I can have one central server set up with virtual Web hosts on the same IP address handle the inbound requests that should go to different internal servers.

Figure D: Creating a reverse proxy

The final rule I want to discuss are the rewrite maps. These allow you create a list of URLs and translate them to substituted URLs. By itself, a rewrite map is useless, it needs to be used as part of a larger rule instead of or in conjunction with the substitution patterns. Where these are particularly handy in my experience is when you are redesigning or reorganizing a site that uses non-predictable URLs (such as many static HTML site). By combining a redirect using HTTP status 301 ("Permanent") with a rewrite map, you can hand-tailor your translations in situations where rules do not work well.

Once you have the basic rule set up (or used a blank rule), you can then edit it as needed. The rule editor (Figure E) really breaks things down nicely. You start with a rule name and the URL pattern to match (or not match). From there, you can add a variety of conditions, like looking for a particular string in a parameter of the URL, a server environment variable, and more. You can tell it to match all, or match any of the conditions. If the conditions are not met, then the rule will not perform the rewrite. You can also perform substitutions on server variables, which is great for enforcing certain behaviors. The server variables encompass a very large list of things to work with, including the rewrite maps that you have created. Next, you define what the rule should actually do: perform a "rewrite" (which has the server treat the request as if the rewritten URL was what the client requested) or a "redirect" which will actually send a redirect HTTP status code (you get to pick which one) to the client for them to query the new URL. Then you define the pattern for the rewriting itself. Finally, you have a few options:
  • Appending the query string
  • Logging the request
  • Not running any more rules once this one is finished

Figure E: The rule editor

With these basic ingredients, you can create just about any URL rewriting recipe that you need. I have used URL rewrite for both simple and complex tasks and I have not been disappointed.

About

Justin James is the Lead Architect for Conigent.

2 comments
suhas.chatekar
suhas.chatekar

 Hello Justin,


In section "Add reverse proxy rules", is there a way I can specify to change the domain names of the cookies generated by the internal website so that they appear to be coming from public facing website to the user?

I am investigating options to offer seamless user experience between two of my client's website (which sit on different domains). Reverse proxy can help if I could rewrite the domain of the cookies and allow sharing of the cookies that way. 


Thanks

Suhas

NitaS
NitaS

Hello, Please advice how to upgrade the existing url rewrite module of v1.0 to 2.0? Does it require to reboot server (Windows 2008). Thanks in advance. NitaS