How To: Use IIS URL Rewrite to Redirect, Route and Adjust Realm Traffic

Version Affected: All

 

Overview

The IIS URL Rewrite module can redirect or route a realm's traffic based on almost anything available to IIS when a client connects — the requested URL, the client's IP address, the browser's user agent string, the host header, or any other server variable. This article explains the general procedure for creating a rewrite rule once, then gives worked examples of that procedure for several common SecureAuth use cases.

1. Follow General Procedure to learn the steps every rewrite rule shares.
2. Then use whichever example below matches what you're trying to do, and substitute its specific Match/Condition/Action values into the general procedure.
   

In this article

• General Procedure: Create a Blank Inbound Rewrite Rule
• Example 1: Redirect Based on Client IP Address
• Example 2: Redirect Specific Browsers to a PFX Enrollment Realm
• Example 3: Redirect macOS Users to a Different Realm
• Example 4: Redirect One Realm to Another
• Example 5: Split Internal and External Traffic to Different Realms
• Example 6: Writing Rules Directly in web.config
• Example 7: Auto-Populate the Username Field When the SP Uses a Different Parameter Name

General Procedure: Create a Blank Inbound Rewrite Rule

Every example below starts from this same procedure. The Match URL, Conditions, and Action values are what change between examples.

1. Open IIS Manager, expand Sites, and select the realm you want the rule to apply to.
2. Double-click URL Rewrite in the middle pane.
3. In the Actions pane on the right, click Add Rule(s)..., select Blank Rule, and click OK.
4. Give the rule a descriptive name.
5. Under Match URL, set Requested URL and Using as needed for your goal (see the examples below for specific values).
6. Expand Conditions, set the Logical grouping, and click Add to add each condition your goal requires.
7. Under Action, set the Action Type and the redirect destination.
8. Click Apply in the Actions pane, then test the rule.

Example 1: Redirect Based on Client IP Address

Redirects a client to a different URL based on their IP address (or IP range) — for example, sending a specific set of IPs to a maintenance page or an alternate realm.

• Match URL: Requested URL Matches the Pattern, Pattern *
• Conditions: Input {REMOTE_ADDR}, Matches the Pattern, Pattern set to the IP address or range to match (IP ranges are supported)
• Action: Type Redirect, Redirect URL set to the destination (for example, www.secureauth.com)

Example 2: Redirect Specific Browsers to a PFX Enrollment Realm

Forces users on specific browsers (for example, Firefox and Chrome, which don't support the same auto-enrollment as Internet Explorer/Edge) to a dedicated PFX Enrollment realm instead of the default auto-enrollment realm. Install the URL Rewrite module (IIS 7 and later) on every IdP the users may reach before starting. Create one rule per browser you want to redirect.

• Match URL: Requested URL Matches the Pattern, Pattern *
• Conditions (Logical grouping: Match All):
  • Input {HTTP_USER_AGENT}, Matches the Pattern, Pattern *Firefox* (use the target browser's string here)
  • Input {HTTP_USER_AGENT}, Does Not Match the Pattern, Pattern *Edg* — needed because Edge's user agent string is inclusive enough to otherwise match most other browser rules too
• Action: Type Redirect, Redirect URL set to the PFX Enrollment realm's fully qualified domain name (FQDN), with Append query string checked — leaving it unchecked causes visitors to see 500 server errors

Repeat with a new rule for each additional browser you want to redirect (a list of browser user agent strings, including mobile browsers, is available at useragentstring.com).

Example 3: Redirect macOS Users to a Different Realm

Redirects Mac users to a different realm — useful for Office 365 or other realms configured for Integrated Windows Authentication (IWA), which macOS clients cannot use the same way Windows clients do.

• Match URL: Requested URL Matches the Pattern, Using Regular Expressions, Pattern ^$, Ignore case checked
• Conditions (Logical grouping: Match Any):
  • Input {HTTP_USER_AGENT}, Matches the Pattern, Pattern Macintosh
  • Input {HTTP_USER_AGENT}, Matches the Pattern, Pattern Intel Mac OS X
• Action: Type Redirect, Redirect URL set to the destination realm

Example 4: Redirect One Realm to Another

A generic redirect from an old realm to a new one — useful when deprecating a realm in favor of an updated one.

• Match URL: Requested URL Matches the Pattern, Using Regular Expressions, Pattern (.*)
• Conditions (Logical grouping: Match All): Input {HTTP_HOST}, Matches the Pattern, Pattern .*
• Action: Type Redirect, Redirect URL set to the new realm or URL, Append query string unchecked, Redirect Type Permanent (301)

A Permanent (301) redirect is cached by the browser. If the condition behind this rule might change later — for example, the rule itself is edited or removed on the server — a browser that already cached the 301 response keeps sending requests to the old destination until its cache is cleared, even though the rule no longer matches. Use Temporary (307) instead of Permanent (301) for any redirect that might need to stop applying or change its destination later.

Example 5: Split Internal and External Traffic to Different Realms

Sends internal clients to one realm/server and external clients to another, based on client IP address — useful as a substitute when there isn't a load balancer available to do this instead.

• Match URL: Requested URL Matches the Pattern, Using Wildcards, Pattern *
• Conditions (Logical grouping: Match Any): Input {REMOTE_ADDR}, Matches the Pattern, Pattern 10.* or 192.* or 172.* (the private IP ranges used by internal clients)
• Action: Type Redirect, Redirect URL set to the internal realm — for example https://SecureAuthFQDN/SecureAuthRealm#/ if it's on a different server, or /SecureAuthRealm# if it's on the same server

Test the rule from both an internal IP and an external IP to confirm each is redirected correctly.

Example 6: Writing Rules Directly in web.config

Every rule created through the GUI above is stored as XML and can also be written or edited directly, which is useful for copying a rule between sites or for more complex rules than the GUI wizard covers cleanly. Rules can be set at three levels:

• Global (all sites): C:\Windows\system32\inetsrv\Config\applicationHost.config
• Site: D:\Inetpub\wwwroot\web.config
• Application (a specific realm): %application_path%\web.config

A simple rule that redirects one URL pattern to a fixed destination:

<rule name="Redirect to NEW qa-test" patternSyntax="Wildcard" stopProcessing="true">
   <match url="test.domain.*" />
   <action type="Redirect" url="https://qa-test.domain.com" />
</rule>

A more complex rule that uses a condition to rewrite the URL itself, rather than redirecting to a fixed destination:

<rule name="Remove Username from URL" stopProcessing="true">
   <match url="(.*)" />
   <action type="Redirect" url="{R:0}?{C:1}{C:3}" appendQueryString="false" logRewrittenUrl="true" redirectType="Temporary" />
   <conditions logicalGrouping="MatchAny">
      <add input="{QUERY_STRING}" pattern="(.*)(&username=[aA-zZ0-9._%+-]+%40[aA-zZ0-9.-]+\.[aA-zZ]{2,})(.*)" />
   </conditions>
</rule>

Remove Username from URL strips a username= parameter some Service Providers append to the query string, for realms where that parameter shouldn't auto-populate the username field on the login page (for example, to opt a realm out of the auto-populate behavior added in 22.12 Hotfix 3).

In the first example, the destination URL is fixed. In the second, it's built from {R:N} values (captured from the <match> pattern) and {C:N} values (captured from a <conditions> pattern). RegEx patterns can be tested directly in the IIS Manager console while creating a rule, using the Test pattern... button.

Example 7: Auto-Populate the Username Field When the SP Uses a Different Parameter Name

Some SAML Service Providers make the user type their username before redirecting to the IdP, and then the IdP makes the user type the username again — because the Service Provider doesn't send it in the query string under the keyword username, so the IdP's own auto-fill has nothing to match. This rule detects whichever parameter the Service Provider actually sent (for example, login_hint) and adds it to the query string as username before redirecting to the IdP.

• Match URL: Requested URL Matches the Pattern, Pattern *
• Conditions (Logical grouping: Match All):
  • Input {QUERY_STRING}, Does Not Match the Pattern, Pattern (username=).*
  • Input {QUERY_STRING}, Matches the Pattern, Pattern (login_hint=)(\w*).* — substitute whatever parameter name the Service Provider actually sends. This condition must be listed second, after the username check above.
• Action: Type Redirect, Redirect URL set to {R:0}?{C:0}&username={C:2}, Append query string unchecked, Redirect Type Temporary

Sign in to the Service Provider afterward to confirm the username now populates on the IdP's login page. If it still doesn't, confirm the Service Provider is actually sending the parameter named in the second condition — if it uses a different name than login_hint, update that condition's pattern to match.

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.