Introduction to the AppWorks Gateway 16.1 Proxy

Pete_Oliver

originally published December 2019 | 🕐️ 8 minute read

This article introduces the AppWorks Gateway Proxy and walks through some example configurations.

Prerequisites: AppWorks Gateway 16 or above. You can download it from My Support.

Introduction

The AppWorks Gateway Proxy is an integral component of the OpenText AppWorks Gateway. Its function is to provide a reverse HTTP proxy for web services and simple web applications.

There are numerous reasons why a reverse HTTP proxy may be required, or useful, some of which are given below

Single Point of Entry

An AppWorks solution may require the consumption of APIs from more than one service. These services may be hosted on your premises, or in the cloud, or a mixture of both. By using the AppWorks Gateway's proxy, you can ensure your client software needs to be configured with just one URL (that of the AppWorks Gateway) - all web service API calls will be made to a path rooted by that URL regardless of ultimate destination.

This makes development and configuration of your client software much simpler than it would be were it consuming web service APIs from multiple hosts.

Enforcement of Same-Origin Policy

A central concept of web security is the enforcement of same-origin or known-origin policies. What this means in practice is that in order to mitigate security attacks, JavaScript code and other web artifacts will not be accepted by the client software (usually a web browser) unless those artifacts originate from the same host originally connected to at the beginning of the session, or from one of a set of named (and trusted) hosts.

If your solution is comprised of more than one web resource, spread across different hosts, then same-origin policies can be easily met by routing all client/server web API calls via the same AppWorks Gateway Proxy.

Securing Web Service APIs

Typically, a web-based solution will be required to access only certain sub-sections of a product's web service API. For example consider OpenText Directory Services (OTDS) RESTful web services. Your client software may wish to authenticate its user with the OTDS /authentication endpoint, but once authenticated, you may not wish your user to be able to call the OTDS /user or /group resource endpoints as this will give them access to the contents of our corporate user directory.

In this scenario, with OTDS traffic routed through the AppWorks Gateway Proxy, you can prevent direct access to OTDS, and prevent access to certain parts of its web services API while allowing access to others.

Simple Web Service API Routing

You may have a need to expose the same API from more than one product installation as part of your solution. For example, you may have two identically-hosted document repositories, one that may be accessed by only some of your users, and another by all your users.

Those that fall into the first category will need to be able to access content hosted by either repository. You can use the AppWorks Gateway Proxy to configure separate virtual paths for each repository. In this way, you don't need to make your client software connect to two separate hosts to access both of the APIs.

Meta APIs

The term Meta API is used to describe an API that is comprised of parts from two or more otherwise separate APIs. The AppWorks Gateway Proxy can be used for the assembly of simple Meta APIs by combining rules that expose API parts from different services.

Content Rewriting

Consider when a web service API sits behind a reverse proxy; that API may be exposing internal URLs, IP addresses, etc. The AppWorks Gateway Proxy allows for such things to be re-written on content egress, substituting internal URLs and IP addresses for external ones.

Another situation where content rewriting may come in useful is in the rewriting of CSS, HTML or other web content. For example, the AppWorks Gateway 16.1 uses the Proxy to rewrite portions of the OTDS sign in page to make it more mobile friendly.

Main Proxy Page

The Proxy configuration page is displayed by selecting the Proxy option from AppWorks Gateway administration user interface.

Proxy Operation

From the main Proxy configuration page, you can perform operations such as, enable or disable the entire proxy (1), create new proxy rules (5), and import or export proxy rules (6).

How Proxy Rules are Evaluated

With the proxy enabled, when the AppWorks Gateway receives an HTTP request the proxy will attempt to satisfy that request first. The proxy will only act on the request if it finds an enabled Proxy Rule configured to match the URL of the incoming request. Proxy Rules are examined one-by-one, from the top down in the order displayed on the configuration page. Once a matching proxy rule has been found for the request, the rule is acted upon and further proxy rule processing is halted for that request.

Individual proxy rules may be enabled and disabled with use of the Enabled checkbox (2).

The order of rule evaluation may be adjusted with use of the individual up and down buttons (3).

Anatomy of a Proxy Rule

When you install and configure the AppWorks Gateway to use an external OTDS, a proxy rule is created for you. This rule allows your clients to securely connect to OTDS while authenticating without exposing the OTDS installation directly to the Internet or other external network. For purposes of illustration, we'll examine that rule now.

Regular Expressions

The AppWorks Proxy works by intercepting requests made to the AppWorks Gateway internal web server, and matching those requests against rules that are formulated in Java Regular Expressions. In essence, a match is declared in the Java Regular Expression Language, which, when matched will trigger some outcome, usually with some substitution, which also may contain elements of the regular expression language.

The Whitelist

The Whitelist section (1) of the proxy ruleset defines a coarse-grained match for incoming URLs. A proxy ruleset will be triggered only if the incoming URL contains characters that match one of the whitelist regular expressions.

Before the regular expression is applied to the incoming URL, the scheme, host, and port elements are removed. For example, the incoming URL:

http://my.appworks.opentext.com:8080/otdsws/login

becomes:

otdsws/login

In the above OTDS example, the whitelist is given by the regular expression:

(?i)^(otdsws|otds-v2|ot-authws)(/.*|$)

• (?i) is a modifier that means that case should be ignored when computing the match
• ^ inidicates the expression must match the start of the URL
• (otdsws|otds-v2|ot-authws) means the URL path must start with one of otdsws, otds-v2, ot-authws
• (/.*|$) means the match must either be followed by / and any number of other characters, or be followed by nothing. In other words otdsws is a match, as are otdsws/login and otdsws/, but otdswsx is not a match

The Blacklist

The Blacklist (2) is available from AppWorks Gateway version 16.1 and may be used for a number of purposes:

• To narrow an overly broad whitelist
• For security purposes to prevent URL path manipulation attacks
• To issue temporary redirect responses, for example while a service is undergoing maintenance

The Blacklist is evaluated only after a successful whitelist match.

An example of path manipulation prevention is seen in the OTDS example above. The blacklist entry (\.\./)|(//) will cause requests for any URL containing ../ or // to be met with an HTTP 400 (Bad Request) response. This prevents the target resource (OTDS) from attempting to de-reference relative paths (../), or otherwise fool the whitelist into accepting something it shouldn't (//).

The remainder of the blacklist entries above deal with securing the OTDS REST web services. By default, OTDS permits read-only access of the users and groups stored within it, and this access can be achieved through its web services. Since the AppWorks Gateway is acting as a proxy for OTDS, we can use the proxy blacklist like this to prevent outside clients from accessing those sensitive parts of that OTDS API.

URL Mappings

A URL mapping (3) defines how to transform a matched URL into a target URL. The matched portion of the URL is replaced with the target of the mapping.

The match portion of the rule may use regular expression catch groups which may then be fed into the target URL. An example of this is shown above, as:

(?i)^(otdsws|otds-v2|ot-authws)/?(.*|$) ==> http://<otds-host>:<port>/$1/$2

This contains two capture groups, (otdsws|otds-v2|ot-authws) and (.*|$).

The substitution of the captured groups in the target URL can be seen with the placeholders $1 and $2.

For example, given the incoming URL:

http://my.appworks.opentext.com:8080/otdsws/login?otdsauth=no_sso

otdsws is captured by group $1 and login?otdsauth=no_sso is captured by group $2.

This results in a rewritten URL of:

http://<otds-host>:<port>/otdsws/login?otdsauth=no_sso

Content Substitution with URL Mappings

The above OTDS example also shows some URL mapping rules that demonstrate content substitution, here for files named logon_custom.css, logon2.css and signin-ot.svg. This allows the OTDS login page, as viewed by a client connecting via the AppWorks Gateway Proxy, to be tailored for a better mobile experience.

Here is the OTDS login page without the content substitution, as viewed on an iPhone 6:

Order of processing of URL Mappings

The URL mapping rules are processed in the order they are displayed in the configuration page. This order may be altered with the up and down arrow buttons displayed alongside each rule.

The continue checkbox, controls whether URL Mapping rule processing should halt with the matched URL Mapping rule, or should continue to the next. This allows for quite complex URL substitutions to be defined as a series of simpler rules.

Outgoing Content Rewrite

An example of outgoing content rewriting (4) is seen in the OTDS example above with this rule:

("|')\s*;(\s|.)*?\} ==> /* Removed by AppWorks Gateway: $0 */

This causes references to the Lato font in OTDS CSS files to be commented out as the content flows back through the gateway. This is for historical reasons, as some versions of OTDS cause large font files to be delivered to the connecting client. This is not a problem for desktop devices connecting via a local LAN, but may cause issues for mobile devices with limited or slow data plans.