Custom Domain: Configure Your Reverse Proxy for an Uberflip Hub

Follow

Learn how to configure your reverse proxy to point requests for a specific subdirectory to Uberflip's origin server.


 

Before You Begin

  • This article is intended for readers with a technical background. It assumes a general familiarity with web servers and related concepts and terminology.
  • In most organizations, the person who can perform the steps described in this article will be a web administrator (or similar).
  • This guide assumes that you have reverse proxy capability available and set up on your website. This can be implemented in various forms; specific requirements are laid out below.

 

What This Guide is About

You have likely been provided this guide by your organization's Uberflip administrator. Uberflip is a SaaS provider that helps Marketing and Sales departments to create curated content experiences for prospects and customers. These content experiences are managed and delivered through a web-based interface called a Hub.

For user experience and SEO reasons, we recommend unifying your Uberflip Hub with your website, which means delivering it on a URL that is part of your website's root domain. However, because Uberflip is SaaS, Hubs are hosted on servers managed by Uberflip. One way to solve this problem is to use a reverse proxy to integrate your Hub and your website.

This article explains how to set up a reverse proxy so that it sends requests for a designated subdirectory (and anything under it) to a specific origin server. The ultimate purpose of doing this is to allow visitors to your website to request a certain subdirectory (e.g. www.mycompany.com/resources) and be served content from an Uberflip Hub that is hosted outside your website's hosting infrastructure.

 

Requirements

We don't require any specific type of reverse proxy, so you can choose the most appropriate option for your situation based on your preference or what you already have in place. The possible options include:

  • A Content Delivery Network (CDN), e.g. Amazon CloudFront, Akamai, Cloudflare (Enterprise), Limelight, etc.
  • A dedicated load balancer or reverse proxy server, e.g. HAProxy or NGINX.
  • A reverse proxy/gateway module on your web server, e.g. mod_proxy on Apache HTTP Server or Application Request Routing on Microsoft IIS.

More information about these options (along with our recommendations) can be found in this article.

No matter which option you go with, your specific reverse proxy must support the following functionality to be used with Uberflip:

  • Proxy requests for a subdirectory and anything below it (e.g. http://www.mycompany.com/hub/*) to a specific origin server.
  • Proxy GET, POST, HEAD and OPTIONS requests (at minimum these types required; others do not have to be excluded as they will be ignored).
  • Disable caching of the origin server (for CDNs).
  • Pass requests to the origin server intact, i.e. with the full request URL, and all original headers/parameters included.

Specific reverse proxy services that are known not to work are listed in the Frequently Asked Questions section at the end of this article.

 

Configure the Reverse Proxy

As the exact steps needed to configure your reverse proxy will vary depending on the type of reverse proxy you are using, we're not able to provide detailed, step-by-step instructions on how to do this. Instead, we will describe the general setup objectives you need to achieve, as well as the reasoning behind them.

The reverse proxy technology you are using will have its own documentation that outlines the exact steps you need to follow to get the desired result. Use the objectives below to guide you as you configure the settings for your particular reverse proxy.

 

Objective 1: Proxy Requests for a Subdirectory to a Specific Origin Server

What you need to do:

  • Create a rule in your reverse proxy. The rule must:
    • Apply to any request that involves a specific subdirectory on your root domain (including any further subdirectories nested under the designated subdirectory)
    • Pass all requests that meet this criterion to a specific origin server
  • The subdirectory that will form the basis of the rule will be provided by your organization's Uberflip admin (e.g. http://www.mycompany.com/hub/)
  • Specify the following origin server:
    • https://read.uberflip.com/

Why you need to do it:

  • The underlying goal is to make your Uberflip Hub accessible under a subdirectory on your website's root domain
  • Uberflip Hubs are actually hosted on Uberflip's servers, accessible via the URL https://read.uberflip.com/
  • To serve a Hub when a visitor requests the specified subdirectory, you need to identify those requests and automatically send them to https://read.uberflip.com/

 

Objective 2: Ensure the Required Request Methods are Passed

What you need to do:

  • Your rule must be able to pass all requests that use the following methods:
    • GET
    • POST
    • HEAD
    • OPTION
  • You do not need to set up a rule that passes only requests using these methods. Requests using any other method will simply be ignored by the Uberflip origin server.

Why you need to do it:

  • To ensure full Hub functionality, at minimum Uberflip needs to receive any and all requests that use the 4 methods ("verbs") listed above
  • Therefore, your reverse proxy must be capable of passing these types of requests without omitting/filtering any
  • Requests using any other method can also be passed safely, as they will simply be ignored by the Uberflip server

 

Objective 3: Ensure Requests are Passed Intact

What you need to do:

  • Your reverse proxy and/or your rule must be set up in such a way that requests passed to the Uberflip origin server are passed through as-is
  • This means that the origin server must receive the original request exactly as it was sent by the client — the reverse proxy may not make any changes to it
  • Some reverse proxies add header fields that were not part of the original request. This is fine, provided the change is only additive (i.e. no part of the original request is modified or removed as a result)

Why you need to do it:

  • Metrics around the way that visitors interact with your Uberflip Hub are very important to your Marketing department
  • To report accurate data, Uberflip requires all of the information passed through by the client, as it allows us to identify users and their behaviour
  • Passing the requests intact also allows us to ensure the correct Hub (and content within the Hub) is served to the client

 

Objective 4: Enable TLS ("SSL") Between Your Reverse Proxy and the Origin Server

What you need to do:

  • Requests passed from the reverse proxy server to the origin server must use a secure connection (HTTPS over TLS)
    • This is still commonly referred to as "SSL", but in the interest of clarity, you should specifically use the current standard TLS protocol rather than the deprecated SSL protocol
  • This specifically refers to the connection between the proxy server and the origin server only, i.e. it is a requirement even if your website does not use HTTPS
  • The connection will be terminated at the origin server and is therefore covered by Uberflip's certificate, so you do not need to provide a certificate

Why you need to do it:

  • The Uberflip origin server (https://read.uberflip.com/) is configured to require HTTPS, so the connection to the reverse proxy should be set to use it

 

Objective 5: Disable Caching of the Origin Server (If Needed)

What you need to do:

  • Your reverse proxy may support caching of origin servers (i.e. if you are using a CDN)
  • If so, you must specifically disable this feature for the Uberflip origin server

Why you need to do it:

  • As with the "requests must be passed intact" requirement, this is to ensure accurate Hub metrics
  • If caching is enabled, the proxy server will serve requests from its own cache of the origin server
  • When a request is served from cache, the request is never passed to the origin server, so Uberflip does not receive the request headers requires to produce metrics

 

Confirm Basic Functionality

When you have configured your reverse proxy to meet the objectives outlined above, you can test whether it is working by visiting the subdirectory URL in any browser. If you set everything up successfully, your Uberflip Hub (or, in certain cases, a testing Hub) should load.

Once this test passes, you can notify your organization's Uberflip admin so that they can complete the remaining setup and testing steps.

 

Common Problems

Below are some of the configuration problems we see most often with reverse proxies. These issues will generally either make the Hub inaccessible, or will break important functionality, so it's important to try and avoid them while setting up your reverse proxy.

 

Removing HTTP headers and changing the request method

Some proxy servers can be set up to change components of HTTP messages, including the method and the values in the HTTP request and response header fields.

However, various functions of Uberflip Hubs rely on our origin server receiving this information exactly as it was sent by the client's browser (and vice-versa): for example, the User-Agent and Cookie header fields, among others, are used to collect visitor metrics.

If your proxy server changes the HTTP messages in this way, this can either break particular functionality, cause security risks to the client's browser, or cause the Hub to stop working altogether. For example:

  • If the proxy rewrites POST requests to GET requests, functionality like CTA submission and progressive profiling will break
  • If the proxy modifies or removes header fields like Accept-Encoding, the server may return an encoding that the client's browser can't display
  • If the proxy changes the Host header field, the Hub can't be displayed at all (see below)

As a result, you should make sure that your proxy server is configured to not modify either the request or response messages in any way (though it may add its own headers if needed).

 

Changing the value of the Host header field

In addition to generally ensuring that your reverse proxy is not changing any HTTP headers, it's particularly important that the Host header on HTTP requests is not modified in any way. When a request for a Hub reaches our origin server at read.uberflip.com, the server relies on the hostname listed in the original request to figure out which Hub the request is intended for. If this hostname has been changed by the reverse proxy, our server has no way of knowing which Hub to serve in response to the request, since the information it needs to do that is missing.

Some reverse proxies (such as Apache's mod_proxy) will change the hostname on the request header by default, and replace it with the hostname of the origin server. For example, it would change

Host: www.mycompany.com/hub/

to

Host: read.uberflip.com/

With proxies that do this, you would generally need to specifically override this behavior by changing a setting (in mod_proxy's case, this setting is called ProxyPreserveHost) to ensure that the original host is kept on the proxied request.

 

Removing part of the request path

Keep in mind that the way your proxy works might cause part of the request path to be removed. For instance, consider this mod_proxy ProxyPass directive:

ProxyPass "/hub/" "https://read.uberflip.com"

This directive, as written, would redirect any request with /hub/ in its path to https://read.uberflip.com. However, this would not work, because a request like:

GET /hub/blog/ HTTP1.1
Host: www.mycompany.com

would be proxied to https://read.uberflip.com as:

GET /blog/ HTTP1.1
Host: www.mycompany.com

As you can see, the /hub/ part of the path has been removed from the proxied request, so you end up with GET /blog/ instead of GET /hub/blog/. Without the full path, Uberflip would be unable to identify the Hub that the request is intended for.

The reason for this is that a proxy like ProxyPass requires you to specify a full URL, not just the origin server domain. ProxyPass works by appending the requested path to the URL you provide, but does so after removing the part of the path specified in the directive (e.g. /hub/).

To avoid this issue, you would need to ensure that you set up your proxy in such a way that no part of the original request path is removed when the request is proxied to read.uberflip.com. In the case of a ProxyPass directive specifically, you would need to include the part of the path to be matched in the URL as well, like this:

  • Incorrect: ProxyPass "/hub/" "https://read.uberflip.com"
  • Correct: ProxyPass "/hub/" "https://read.uberflip.com/hub/"

 

Enabling caching on the proxy server

Some proxy servers, particularly those that are part of CDNs, offer the ability to cache server responses. With this functionality enabled, the proxy server can serve resources it has saved from its own cache, rather than requesting them from the origin server.

Using a proxy server's cache can have performance benefits for many web properties, but with an Uberflip Hub, doing so will break important functionality. Specifically, client requests must hit the origin server for features like CTAs and visitor metrics to work: if these requests are served from cache, instead, this will result in data loss as you will be unable to collect CTA submissions and metrics.

If your proxy server does have cache capabilities, you should therefore ensure that it is turned off specifically for any request that is proxied to Uberflip's origin server (though you can still enable it for any other request if desired).

 

Frequently Asked Questions

Q: The URL for our Hub is currently [mycompany].uberflip.com, not read.uberflip.com. Why do I set the origin server as read.uberflip.com?

Q: I have multiple Hubs that I want to set up on subdirectories. Do I need to specify a different origin server for each one?

A: The answer to both of these questions is that, for logistical reasons, we actually serve all Hubs from a single domain: read.uberflip.com.

Every Hub is linked in the Uberflip interface (Account Settings > Services > Domains) to a particular domain under which it can be accessed — but in fact, each of these Hub domains are just aliases for read.uberflip.com. As a result, visiting any given Hub domain always routes the request to read.uberflip.com. We then simply look up which Hub that domain is linked to in Uberflip's database and serve up the appropriate Hub.

For this reason, when you set up a reverse proxy to point requests for a Hub's domain at an origin server, you always specify the origin server as read.uberflip.com: this is the actual underlying server from which all Hubs are served.

 

Q: My website uses HTTPS (SSL/TLS). If I set up a custom domain for my Hub on a subdirectory of my website, do I need to send Uberflip a certificate?

A: No, you don't have to send us a certificate in this case. While you do have to send us a certificate if you use a subdomain as your custom domain and want to use HTTPS on it, this is not necessary if your custom domain is a subdirectory. When a client requests the subdirectory for your Hub, the TLS connection is terminated at your domain, because the subdirectory is under that domain. This means that it is covered by your domain's certificate.

The request is then passed on by your reverse proxy server to the Uberflip origin server (read.uberflip.com). This connection also uses HTTPS, and as it terminates on Uberflip's domain, it is covered by Uberflip's certificate.

 

Q: Are there any specific reverse proxies that do not work with custom domains?

A: Yes. At present, we have confirmed that the following will not work:

  • AWS ALB (Application Load Balancer), ELB (Elastic Load Balancer) and Classic Load Balancer. As an alternative, you can use CloudFront, which is confirmed to work and is also part of AWS.

We will be adding to this list as we identify other reverse proxy services that are not compatible with Uberflip custom domains.

2 out of 2 found this helpful

Comments

0 comments

Please sign in to leave a comment.