How to use .htaccess files on Windows Server IIS

Learn how to use .htaccess in Windows Server IIS. In this post I’ll provide you with some useful .htaccess URL rewrite examples. URL rewrite examples that you can use on Window Server IIS for your website.

URL Rewriting in IIS

Before IIS 7 and the URL Rewrite module, you had to rely on third party extensions to IIS for URL rewriting with .htaccess files. One example of such an extension is the widely used ISAPI_Rewite 3 by Helicon Tech. Helicon ISAPI_Rewrite is superseded by Helicon Ape nowadays.

Here is some information for you to use .htaccess in IIS.

Using such an extension made search engine friendly URL’s with WordPress Permalinks or Joomla SEF possible, and some other neat stuff like protecting your website from 0-day exploits or to hiding the .php extension with URL Rewrite Module & Helicon Ape. Emulating Apache MultiViews on IIS, both web.config and .htaccess examples in that post! 🙂

Since IIS 7 and the IIS URL Rewrite module, you can add rewrite rules to your website’s web.config file. You convert your Apache .htaccess to web.config manually or automatically.

However you can always install and use Helicon Ape on an IIS web server to process .htaccess files. This makes your website more cross-platform.

About Helicon Ape

Helicon Ape is an Apache emulator for Microsoft IIS. It literally implements Apache configuration model (like .htaccess and httpd.conf files) and all most demanded Apache modules in a single IIS add-on, not only making IIS compatible with Apache, but also extending it’s functionality by a number of highly essential features. You can check all currently available modules in the compatibility chart (the list is growing with new builds).

Helicon Ape is implemented as managed IIS 7 (7.5) module, but can be installed as .NET module on IIS 6 as well. It works transparently for both server and client and can even be installed on a shared hosting account without administrative access.

Includes following modules: mod_rewrite, mod_proxy, mod_auth, mod_gzip, mod_headers, mod_cache, mod_expires, mod_replace and others. Helicon Ape overview

ISAPI_Rewrite 3 comes as an ISAPI Filter and Helicon Ape as a managed IIS 7 module which can be installed as a .NET module. Unfortunately the ISAPI_Rewrite 3 and Helicon Ape syntax are not always compatible with each other, and therefore you should only use Helicon Ape nowadays.

IIS URL Rewrite

IIS URL Rewrite 2.0 enables Web administrators to create powerful rules to implement URLs that are easier for users to remember and easier for search engines to find. By using rule templates, rewrite maps, .NET providers, and other functionality integrated into IIS Manager, Web administrators can easily set up rules to define URL rewriting behavior based on HTTP headers, HTTP response or request headers, IIS server variables, and even complex programmatic rules.

In addition, Web administrators can perform redirects, send custom responses, or stop HTTP requests based on the logic expressed in the rewrite rules. URL Rewrite – The Official Microsoft IIS Site

A visual representation

This flowchart highlights how the Helicon Ape managed module intercepts the request early in the IIS pipeline to process .htaccess rules.

graph TD
    %% Node Definitions
    Request([Client Request]) --> IIS[IIS Request Pipeline]
    
    subgraph HeliconApe [Helicon Ape Managed Module]
        IIS --> Intercept[Intercept Request]
        Intercept --> ReadHT[Read .htaccess Files]
        ReadHT --> Rewrite{Process mod_rewrite}
        Rewrite -- "Rule Match" --> Update[Update Internal URL]
        Rewrite -- "No Match" --> Continue[Keep Original URL]
    end

    Update --> Handler[Final IIS Handler / ASP.NET / Static]
    Continue --> Handler
    Handler --> Response([HTTP Response])

    %% Styling for better visualization in WordPress
    style HeliconApe fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5
    style Rewrite fill:#fff9c4,stroke:#fbc02d
    style Request fill:#e1f5fe,stroke:#01579b
    style Response fill:#e1f5fe,stroke:#01579b

Key steps illustrated in this flow:

1. Request Arrival: The HTTP request hits the Windows Server.
2. Module Interception: Because Helicon Ape is a managed .NET module, it enters the pipeline early, allowing it to act similarly to Apache’s native engine.
3. Discovery: The module traverses the directory tree to find all relevant .htaccess files.
4. Transformation: Rules are applied (mod_rewrite, mod_auth, etc.). If a rewrite occurs, the internal path is updated without the client seeing a redirect.
5. Final Execution: The processed request is handed off to the final handler (like the StaticFileModule or AspNetCoreModule) to serve the content.

.htaccess examples for IIS

All .htaccess examples are for Helicon Ape. The .htaccess examples I describe are:

• WordPress Permalinks
• linked domains to one master website
• linked domains to a sub folder on the master web site
• manage subdomains
• redirect HTTP to HTTPS
• domain without www to www (canonical hostnames, from example.com to www.example.com)
• block all visitors, except from some IP addresses
• RewriteProxy to another web server
• 7 Tips: .htaccess as Web Application Firewall (WAF) to secure your website

WordPress Permalinks .htaccess

Helicon Ape recognizes existing directory and existing file as test strings for %{REQUEST_FILENAME}. By negating we turn this around which makes the rules only processed if a request_filename is not an existing file or directory. All those requests are then rewritten to WordPress index.php file for internal handling.

# Enable the RewriteEngine.
RewriteEngine On

# When the HTTP request doesn't match and existing file 
# or directory, Rewrite the request and send it to the 
# index.php file
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [L]

And some would still say search engine friendly URL’s are not possible on IIS with .htaccess `files… sigh

Rewrite linked domains to one master web site – how to map multiple domains 1

Most hosting providers offer the ability to map multiple domains to one master domain and / or webspace.

Let’s say you have example.com, example.net, and example.org hosts your website. You’d like to have all requests for www.example.com, example.com, www.example.net, example.net to be rewritten to www.example.org, how would you accomplish that?

Of course you can list all domain names in your .htaccess file, but that doesn’t scale easily. Therefore, you can map all incoming HTTP request, except for www.example.org, to your main website on www.example.org.

Wondering how to get these redirects in place with WordPress? Check out my guide “SSL in WordPress: how to move WordPress to HTTPS? The definitive guide” detailing the ideal redirect schema for WordPress.

You can choose to rewrite the requests, but for Google Search Engine Optimization (SEO), and duplicate content, it’s better to permanently redirect them with a 301 redirect. And here is how!

Add to your .htaccess:

# Enable the RewriteEngine.
RewriteEngine On

# Rewrite the HTTP request for every mapped domain to the 
# master domain. Replace "example.com" with your master 
# domain name.
RewriteCond %{HTTP:Host} ^(?!www\.example\.com)$ [NC]
RewriteCond %{REQUEST_URI} (.+)
RewriteRule .? http://www\.example\.com%1 [L,R=301]

This one also takes care of the REQUEST_URI, meaning that a request for www.example.net/foobar.php will be redirected to www.example.org/foobar.php.

Linked domains to a subfolder on the master web site – how to map multiple domains 2

The same as above, we want to map multiple domain names to our master domain. But now map them to a subfolder, for example for different languages: example.nl, example.de, example.fr, example.co.uk.

All requests are automatically mapped to a sub-folder with the same name as the domain name. Be aware of that!

# Enable the RewriteEngine.
RewriteEngine On

# Rewrite a HTTP request for a mapped domain to a subfolder, 
# with the name of that domain.
#
# Replace example.nl with your domain name, on the first 
# and third line
RewriteCond %{HTTP:Host} ^(?:www.)?example\.nl$
RewriteCond %{REQUEST_URI} (.+)
RewriteRule .? example%1 [L]

We can probably make this more robust:

# Enable the RewriteEngine.
RewriteEngine On

# assuming the domain is always example, with several ccTLD's.
# We list all ccTLD's for convenience.
RewriteCond %{HTTP:Host} ^(?:www)?\.example\.(nl|be|de|co\.uk|fr)$
RewriteCond %{REQUEST_URI} (.+)
RewriteRule .? %2%3 [L]

This should map example.nl to example.org/nl

Manage and rewrite sub-domains on IIS with Helicon Ape

As with the above .htaccess to map a linked domain to a subfolder, we can do the same for subdomains. A subdomain substitutes www in the address bar, sales.example.com for example.

# Enable the RewriteEngine.
RewriteEngine On

# Rewrite any subdomain to a folder with the same name, 
# except for www. Nothing is rewritten if no subdomain 
# is used.
# Subdomains like "www.foo" are rewritten to "/foo",
# "foo.bar" to "/foo.bar".
RewriteCond %{HTTP:Host} ^((?!www.)(.+)|(?:www.)(.+)).(example\.com)$ [NC]
RewriteCond %{REQUEST_URI} (.+)
RewriteRule .? %2%3%5 [L]

How to rewrite your non-www domain to www (canonical hostnames, example.com to www.example.com)

In order to not to display double content – which is bad for your Google SEO – we need to rewrite non-www URL’s to www. Assuming we want to have our website available on www.example.com. Again we use a 301 permanent redirect.

And again, REQUEST_URI is included too.

# .htaccess IIS rewrite
# Enable the RewriteEngine
RewriteEngine On

# Rewrite any HTTP request for a domain name without 
# www to www.domain name.
RewriteCond %{HTTP_HOST} ^(?!www.)(.+)$ [NC]
RewriteCond %{REQUEST_URI} (.+)
RewriteRule .? http://www.%1%2 [L,R=301]

Block all visitors, except from some IP addresses

Sometimes you want or need to block access to all visitors, except from your own IP address. Fortunately Helicon Ape supports the REMOTE_ADDR server variable, which you can use to test the visitors IP address against.

Blocked visitors simply receive a Forbidden error message.

# Enable the RewriteEngine.
RewriteEngine On

# Deny access to everyone (all visitors), except the IP addresses 
# below. Change 11.222.33.444 and 555.66.7.888 with the 
# IP addresses.
#
# You can use this .htaccess file on IIS in separate folders 
# to protect/secure them.
RewriteCond %{REMOTE_ADDR} !(11.222.33.444|555.66.7.888)
RewriteRule .* / [F,L]

There are several use cases for blocking visitors with Helicon Ape. For example when you’re creating your own .htaccess HTTP blacklist with Helicon Ape, or if you need to temporarily disable your website for maintenace.

Is this post worth a small donation to you? Did it help you solve a problem? Or just want to say thanks?

If you found this post interesting, or it helped you solve a problem , why not buy me a coffee?

A small donation of only $5 helps out a lot in the development, research and hosting of this blog.

Thank you for your support.