Posted Dec 19 by Pete Oliver.
Updated Dec 19.

This article introduces the OpenText AppWorks Gateway Proxy.

Last activity Dec 19 by Pete Oliver.
1625 views. 0 comments.

Introduction to the OpenText AppWorks Gateway 16.1 Proxy

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

Prerequisites

  • AppWorks Gateway 16 or above. You can download it from here.

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
your 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.

OpenText AppWorks Proxy Configuration Page

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.

OpenText AppWorks Proxy - OTDS

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:

OTDS logon page without content substitution

And here is the very same OTDS login page when viewed on an iPhone 6 through the AppWorks
Gateway Proxy as configured above:

OTDS logon page with content substitution

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:

(?i)@font-face\s*\{\s*font-family\s*:\s*("|')Lato("|')\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.

About OpenText

OpenText is the leader in Enterprise Information Management, helping customers to create
a Digital-First World by simplifying, transforming, and accelerating their information
needs. Over 100,000 customers already use OpenText solutions, either on premises or in
our cloud. For more information about OpenText (NASDAQ: OTEX; TSX: OTC), please
visit: www.opentext.com.

About the Author

Pete Oliver is a long standing employee of OpenText, occupying the position of
Senior Software Architect. Pete has worked on various OpenText products
and platforms, including ECM Collaboration, OpenText Directory Services (OTDS),
AppWorks Developer, and more recently AppWorks Mobile.


Table of Contents