Understanding portal URL handling for custom reverse proxy

When you change the bindings on an IIS website, the site is cleared and all user sessions are stopped. With URL rewrite, you can add host names without changing bindings, so you can add new portals without affecting users. For businesses that need to have their portals available 24/7, URL rewrite is a good option.

If you use the standard reverse proxy support provided with IPF, you do not need to maintain URL rewrite settings. If you use your own reverse proxy, you must configure URL rewrite settings so they can work with IPF.

This appendix explains URL rewriting, how IPF handles the routing of incoming URL requests to the correct IIS site, and how IPF determines which portal is being associated with the incoming URL.

Terms

This section describes terms you must understand for working with URL rewrite and reverse proxy.

  • URL: The URL is what the end user sees in the browser address bar. It is always a portal ID followed by a resource locator.
  • Portal ID: Every portal is uniquely identified by the portal ID. Within the portal ID, there are two parts:
    • Website: This is the portion of the portal ID that is used by the browser to locate the website.
    • Portal Site: Optional. If you choose to create multiple portals on one website, this is used by IPF to determine which portal within the website to use. For example, in http://www.acme.com/custportal, custportal is the portal site.

    install_url_portal_id

  • Resource Locator: This is the remainder of the URL, after the Portal ID. This portion of the URL identifies the particular resource being accessed, for example the page or image, within a portal.

    install_resource_locator

  • IPF Instance Name: An IPF instance is an installation of the IPF architecture into IIS as a single web app. This provides a way to specify the IPF architecture instance/version to use in the URL. This allows portals using the same website to use different architecture versions.
  • Instance Binding: This is the portion of the URL that is used by IIS to determine the IPF instance to route the browser request to. If no URL rewriting is in effect, the instance binding and the website are the same.

    No URL rewrite: install_instance_binding

  • Rewrite ID: A rewrite ID is generated by the URL rewrite application (reverse proxy) using a combination of the portal ID and the rewrite rules.
  • Rewrite Binding: This is the portion of the URL that is used by IIS to determine the IPF instance to route the browser request to when URL rewriting is in effect.
  • Rewrite Portal Site: This is the portion of the rewrite ID used by IPF to determine the portal to use within the IPF instance. It is made up of two parts: the original website information followed by the original portal site.

    URL Rewrite:install_rewrite_portal_site

About URL rewrite

The IPF architecture provides functionality to work in an environment where portals take advantage of a URL rewrite tool, for example reverse proxy, which maps incoming URLs with a portal ID to a URL with a rewrite ID. URLs prefixed with a rewrite ID typically are not visible from outside the hosting company's firewall.

install_about_url_rewrite

This is how the mapping works:

  1. The above rewritten ID is referred to as the rewrite ID. This is the ID seen by the IPF architecture when processing requests.
  2. The InternalProtocol, InternalHost Name, and InternalPort comprise the rewrite binding for the specific IPF instance, or a specific site in IIS.
  3. The rewrite binding appears as a binding on the IIS website. This rewrite instance binding is also stored with the IPFinstance metadata in the IPF Control Database. It is a special binding, provided exclusively for rewrite scenarios.
  4. The website does not show up in the IIS instance bindings.
  5. There are multiple options as to how the URL rewrite tool is configured to do the above mapping. The options are described later in this section.

No URL rewrite

When there is no URL rewrite, the URL received looks like this:

install_no_url_rewrite

This is how it works:

  1. The bindings for the IPF instance site are referred to as the instance binding, which is the same as the website. The instance binding does not contain enough information to identify the portal. It identifies only which IIS site will service the request.
  2. The host header, port, and portal site identify the portal, and are referred to as the portal ID.

Identifying the portal by the received URL

Given the rewrite ID, the IPF architecture can find the associated portal definition in the IPF Control Database.

If the first part of the received URL matches the rewrite ID of any IPFinstance, then a URL rewrite scenario is assumed. The website and optional portal site are parsed from the request to build the portal ID. Otherwise a non-URL rewrite scenario is assumed, and the protocol, host header, port, and portal site from the received request are used to build the portal ID.

With the portal ID determined, IPF finds the portal in the IPF Control Database and makes sure the IPF instance/IPF version tied to that portal matches the IPF instance that is currently running. This is a check to make sure the reverse proxy rules have been set up correctly. If the portal is not found or the IPFinstance/ IPFversion does not match, the IPF architecture redirects to the "404... page not found" message, passing along an IPFFilterI containing the error message to display on the page.

URL rewrite rule details

The goal of the URL rewrite rule is to provide options to create portals without requiring farm configuration. This means no load balancer changes, no URL rewrite rule changes, and no modified IIS bindings. To accomplish this, defaults must be defined in the URL rewrite rule and in the IIS site bindings.

  1. All IPF instances are configured with a rewrite binding, which includes the rewrite host header, rewrite port, and rewrite protocol. This rewrite binding is set as a binding on the IIS site for each IPF instance.
  2. The farm defines a default rewrite binding, or default IPF instance. A low priority rule is required in the reverse proxy, which maps all unmapped requests to the default IPF instance using the rewrite binding attached to the farm.

Also, the portal site can have one or two parts. This is how each option works:

  • If there is only one part, the portal site simply identifies a specific portal within the same host name and port combination, within an instance binding. There cannot be multiple folders to identify a portal. That is, the Portal Site can be testcustportal or testvendportal but not test/custportal or test/vendportal.
  • If there are two parts, the first part is an IPF instance name, which identifies the IPF instance, and the second part identifies the portal. For example, IPF41/testcustportal or IPF42/testvendportal.

Based on these options, higher priority rules are required in the reverse proxy, which maps all of the IPF instance names that appear in a portal site to the rewrite binding, using the rewrite binding of the IPF instance.

install_rewrite_rule_detail

This mapping would occur even if the host name or the farm was pointed to a different IPF version. This is because the IPF41 in the Portal Site has special meaning and was configured in a high priority rule in the reverse proxy, to map to a specific rewrite binding.

To create a portal tied to a specific IPF instance, without the special rewrite binding with the IPF instance available, farm configuration is required. For this to work, another higher priority rule specific to the portal ID is required in the reverse proxy, which maps the portal ID to the specific instance binding in the desired IPFinstance.

Note: When you use custom reverse proxy and you need to access the portals from the same machine that is running IPF, you must stop the IPFReverseProxy application pool and site in IIS.
Note: Whenever a portal is changed to use a new or different IPF instance with a different port number, either by using Force IPF Instance or by changing the default IPF instance for the farm, custom reverse proxy rewrite rules must be updated to use the new port number. The existing rule will not work until the port number is changed. See Adding the new IPF instance to portals for more information.

Reverse proxy rules summary

This section summarizes reverse proxy rules.

  1. If portal ID is mapped to a specific IPF instance, then map any request directly to the rewrite binding for that IPF instance.

    For example, a portal is created and tied to the IPF instance name IPF42.

    install_reverse_proxy_summary

    No more rules are processed.

  2. Else map to default IPFinstance.

    For example, a portal is created and the host name entry is not tied to an IPF instance, but the farm is tied to IPF instance name IPF45.

    install_reverse_proxy_summary2

    No more rules are processed.

  3. Pass URL through unchanged.