Modifying HTTP Response Headers

by Ruslan Yakushev

This section of the documentation applies to the URL Rewrite Module Version 2.0 for IIS 7.

This walkthrough guides you through how to use URL Rewrite Module v 2.0 to set HTTP response headers.

Prerequisites

This walkthrough requires the following prerequisites:

1. IIS 7 or above with ASP.NET role service enabled;
2. URL Rewrite Module 2.0 Release Candidate installed;
3. Completed walkthrough on Reverse Proxy with URL Rewrite v2 and Application Request Routing.

Introduction

URL Rewrite Module 2.0 provides support for rules-based rewriting of the response HTTP headers. A very common usage scenario for setting the response headers is to modify the redirection response generated by an application behind a load balancer or a reverse proxy. For example, when an application behind a reverse proxy returns a redirect response, the HTTP Location header in the response may not represent the internet-facing address, but rather an internal application address. URL Rewrite Module 2.0 can be used on the reverse proxy server to modify the Location header in the response. The scenario is represented on the following diagram:

1. An HTTP client makes a request to a web page http://www.contoso.com/webmail/oldpage.aspx.
2. The reverse proxy server uses URL Rewrite 2.0 and Application Request Routing to forward the request to an internal content server based on the name of the folder in the requested URL path. For example, http://webmail/oldpage.aspx;
3. The web application that is running on the content server issues a redirect response (HTTP/1.1 301) pointing an HTTP client to http://webmail/newpage.aspx;
4. The reverse proxy server uses URL Rewrite 2.0 to replace the internal-based redirection location in the response with the internet-based redirection location: http://www.contoso.com/webmail/newpage.aspx.

Setting up a walkthrough scenario

To set up the walkthrough scenario, complete the walkthrough about Reverse Proxy with URL Rewrite v2 and Application Request Routing. At the end of that walkthrough, you should have a reverse proxy web site that routes requests to two content applications: webmail and payroll.

For this walkthrough, you'll need to add a redirection logic to the webmail application. In real-life scenario, that would probably be a redirection initiated by the web application code but, for simplicity, in this walkthrough you'll use a redirect rule in the URL Rewrite Module.

1. Create a file named web.config in the following folder:

   %SystemDrive%\inetpub\webmail
   

2. Open the file in a text editor, paste the following XML code inside and then save the file:

   <?xml version="1.0" encoding="UTF-8"?>
   <configuration>
   <system.webServer>
     <rewrite>
       <rules>
        <rule name="Redirect" stopProcessing="true">
        <match url="^index\.aspx$" />
        <action type="Redirect" url="default.aspx" />
       </rule>
      </rules>
     </rewrite>
   </system.webServer>
   </configuration>
   

   This is a rule that will redirect all requests for index.aspx to default.aspx.

Now open a web browser and make a request http://localhost/webmail/index.aspx. Notice that the browser got redirected to http://localhost:8081/default.aspx, which is basically an internal URL used by the webmail web application. Now you'll configure the URL Rewrite rules to modify the HTTP Location header in the HTTP redirection responses so that the browser is redirected to a proper URL: http://localhost/webmail/default.aspx.

Modifying the inbound rule to preserve the host header

In order to be able to modify the HTTP Location header, it's necessary to preserve the original value of the HTTP host header. The outbound rewrite rule uses the preserved value when modifying the response. To preserve the original value, store it in a temporary server variable ORIGINAL_HOST.

1. In the main URL Rewrite feature view page, select View Server Variables in the Actions pane on the right hand side:
   
2. In the Allowed Server Variables page, select Add and then enter the name of the server variable that will be used to temporarily store the value of the HTTP Host header. For example, ORIGINAL_HOST:
   
3. Select OK to save the changes and then return to the main URL Rewrite feature view page. After that, select the "Reverse Proxy to webmail" inbound rule and select Edit.
4. In the Edit Inbound Rule page, expand the "Server Variables" group box; then select Add and enter "ORIGINAL_URL" for the server variable name and "{HTTP_HOST}" for the "Value":
   

Creating an outbound rule to modify the HTTP response header

Now you'll create an outbound rewrite rule that rewrites the HTTP Location header in redirection responses to add back the application folder to the URL path and to replace the host name.

1. In the main URL Rewrite feature view page, select "Add Rules" and then select "Blank Rule" under the "Outbound Rules" category.
2. In the "Edit Outbound Rule" page, name the rule as "Rewrite Location Header".
3. In the "Pre-condition" drop-down list, choose "<Create New Pre-Condition>".
4. In the "Add Pre-Condition" dialog, name the pre-condition as "IsRedirection"
5. Select "Add" and then enter {RESPONSE_STATUS} as a condition input and "3\d\d" as the pattern. This pre-condition is used to check if the response has a redirection status code, such as 301, 302, 307, and so on. The pre-condition dialog should look similar to the following:
   
6. Select OK to return to the Edit Outbound Rule page.
7. In the Match group box, use the Matching scope drop-down list to select Server Variable.
8. Enter RESPONSE_Location for the "Variable name" and "^http://[^/]+/(.*)" for the "Pattern". This configures the rule to operate on the response HTTP header "Location" and match its value against a regex pattern that stores the URL path into a back-reference.
9. Expand the "Conditions" group box, select "Add" and enter {ORIGINAL_HOST} as a condition input and ".+" as a condition pattern. This condition checks if the temporary server variable ORIGINAL_HOST exists and has a non-empty value.
10. Select Add one more time and add another condition. Set the condition input to {URL} and the pattern to "^/(webmail|payroll)/.*". This regular expression is used to match the URL paths that start with either /webmail or /payroll. Also, the parenthesis within the pattern captures the part of the matched URL string, so that it can be reused when constructing the replacement URL.
11. Finally, in the "Action" group box choose the "Rewrite" action and enter "http://{ORIGINAL_URL}/{C:1}/{R:1}" as a value. This action replaces the value of the HTTP Location header with a string constructed by using the host name from the server variable, the condition back-reference that contains the URL path folder prefix and the rule back-reference that contains the current URL path in the Location header.

The complete page should look like the following:

Testing the rule

To test that the rules work correctly, open a web browser and make a request to http://localhost/webmail/index.aspx. The browser should get redirected to http://localhost/webmail/default.aspx:

Summary

In this walkthrough:

• You've learned how to use several new features in URL Rewrite 2.0 to implement a fully functional reverse proxy scenario.
• You've configured the inbound rule to forward the requests to a back-end content server and to set a temporary server variable.
• You've then defined an outbound rule that modifies the HTTP Location header in the redirection response generated by the web application from the back-end content server.