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, 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 headers 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.

 

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.

1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.