/iisproxy

Simple C# script to add reverse proxy functionality to IIS web server.

Primary LanguageC#BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

IIS Reverse Proxy

Build status

By Paul Johnston, http://pajhome.org.uk/

This is a simple C# script to add reverse proxy functionality to the IIS web server. It has been very useful for hosting TurboGears applications behind IIS, and could be used for other frameworks like Ruby on Rails and Django.

Using The Script

  1. Create the directory you want to be proxied, within the webroot. We'll call this the "proxy directory".

  2. Copy the "bin" subdirectory from the IIS proxy souce into the proxy directory.

  3. In IIS Manager, locate the proxy directory and select "Properties"

  4. In the "Directory" tab, under "Application Settings", select "Create"

  5. Click "Configuration"

  6. In the "Mappings" tab, under "Wildcard application maps", select "Insert"

  7. Enter "C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll"

  8. Uncheck "Verify that file exists"

  9. Click "Ok" three times to return to IIS Manager

  10. In the proxy directory, create a file web.config with the following content, replacing {URL} with the URL of the back-end site. Note that the URL must not have any path component, or a trailing slash.

    <configuration>
        <appSettings>
            <add key="proxyUrl" value="{URL}" />
        </appSettings>
        <system.web>
            <httpHandlers>
                <add verb="*" path="*" type="ReverseProxy.ReverseProxy, ReverseProxy" />
            </httpHandlers>
        </system.web>
    </configuration>
    

Directory Layout

The directory layout on the back-end site must exactly match that on the front-end site. For example, if the front-end site is configured so that http://front/mydir is proxied to http://back/ then a request for http://front/mydir/myfile is proxies to http://back/mydir/myfile The reason for this is to avoid the proxy doing any link rewriting. While some proxies attempt this, I've found it unreliable. Reconfiguring the back-end is a better option.

User Identity

By default, the script uses its default credentials for authentication to the back-end. If the directory is configured to use Windows authentication and impersonation, the script will authenticate to the back-end with the identity of the client user. Otherwise, it will be the user the script is running as.

There is an option to enable a different authentication model.

<add key="basicPwd" value="password" />

If this option is specified, the script with present basic authentication to the back-end. The user name will be the user the script is running as, and the password the value specified. This can be useful for fronting a legacy application with a single sign-on interface.

The also adds the current user name into the back-end request, as the Remote-User header. Relying on this for security can carry some risks - a header is potentially spoofable. The back-end application must be deployed so it can only be accessed from trusted sources, usually by making it only listen on the 127.0.0.1 interface.

Tracing Redirects

To aid debugging, the script has the ability to record redirect locations generated by the back end. These are recorded in the event log, in the application section and with the source "iisproxy". To enable this option, add the following to the appSettings:

<add key="traceRedirect" value="on" />

iisproxy may need to be given permission to access the error log. If you encounter problems, see http://support.microsoft.com/kb/329291

Why IIS?

Serving behind IIS is useful for IIS-specific features, and also if an existing server is already using IIS. I found the IIS implementation of integrated Windows authentication to be very reliable, while mod_auth_sspi for Apache has some problems, including issues with inter-forest trusts.

Aims of Script

The script aims to be simple and to get in the way as little as possible. It does not do any link rewriting. The proxy passes nearly everything in both directions, including POST data, headers (e.g. Content-Type), cookies, etc.

Credits

This script has taken inspiration from two existing scripts:

  1. Simple HTTP Reverse Proxy with ASP.NET and IIS, by Vincent Brossier (http://www.123aspx.com/redir.aspx?res=32037)

  2. IIS Reverse Proxy, by John Pierce, john@pierce.name (no longer online)