Skip to main content

OutSystems configurations in reverse proxy scenarios

OutSystems

OutSystems configurations in reverse proxy scenarios

These configurations are implemented in several layers through different technologies. These solutions have been internally tested.

Some of these configurations require direct manipulation of OutSystems system database tables. Do not manipulate these tables in any other form not described in this document or indicated by OutSystems official support. Unexpected changes in these tables may result in service disruption.

A - Request Header Manipulation

Applies only to Web Applications

This occurs at a reverse proxy level. It translates the Internet exposed address into the internal application address.

To the Internet, your application is known and reachable by the address myapp.com. However, it’s served as server.local/myapp by the application server.

There are several different ways to accomplish this task depending on your reverse proxy. Below is an example configuration using a reverse proxy with Apache HTTP Web Server serving an application. For other technologies, please check the appropriate documentation.

< VirtualHost *:80 >
ProxyRequests off
ProxyPreserveHost off 
ServerName myapp.com 
ProxyPass / http://server.local/
ProxyPassReverse / http://server.local/
< / VirtualHost > 

B - Referenced Content Exposure

OutSystems applications can reference content outside the application context URL path. An example of this are the resources in RichWidgets. These also need to be exposed by the reverse proxy the same way the main application is.

The image below shows the ‘myapp’ application, and the ‘Richwidgets’ and ‘EPA_Taskbox’ references also exposed.

Depending on the level of URL manipulation, these references may also need the following:

  • Rewrite resource URLs inside the code (not supported for mobile apps);
  • Request Header Manipulation.

C - End-to-end SSL and SSL Offloading

When serving secure applications through a reverse proxy, OutSystems supports the following setups:

  1. End-to-End SSL
    Encrypting the communication end-to-end. This can be done by installing an SSL certificate in every OutSystems application server, and also in the reverse proxy. It can be the same certificate if it is multi-server or wildcard.
     
  2. SSL Offload
    Install an SSL certificate in the reverse proxy. This keeps the traffic unencrypted between the reverse proxy and the internal application servers. It also removes the need to manage certificates in each application server. This technique is called SSL offloading.

In SSL Offload scenarios, two configurations need to be applied.

  1. Add a custom HTTP header at the reverse proxy level; the header instructs OutSystems to build the URLs with the HTTPS protocol.
    To do so, configure a rule in the reverse proxy that adds the parameter X-Forwarded-Proto with the above defined value of https. This way OutSystems knows to which traffic needs HTTPS URLs.

    If Apache is being used as a reverse proxy, add the following line to the proxy configuration file:

    RequestHeader set X-Forwarded-Proto https

    Note: If you are using other software as a reverse proxy, make sure to check what is the proper header name and value, since they might be different. If the header name and/or value is different, adapt the instructions in the following step to use the correct header. 
     
  2. In the OutSystems database, create the OutSystems.HubEdition.HTTPtoHTTPSproxyHeader parameter:

    insert into OSSYS_PARAMETER (Name,Val) values ('OutSystems.HubEdition.HTTPtoHTTPSproxyHeader','X-Forwarded-Proto: https')

    Description: Allows you to set a special header that, when present, allows the server to process the request as if it was secure.

    Parameter: OutSystems.HubEdition.HTTPtoHTTPSproxyHeader

    Values: X-Forwarded-Proto: https (or another value, depending on the reverse proxy being used).

    You can use "<header>" (OutSystems will check for the presence of the header with name <header>) or "<header>: <value>" (OutSystems will check for the presence of the header with a specific value) as a valid parameter value.

    Default: (none)
     
  3. OutSystems services and application server have to be restarted for this setting to apply.

D - Rewrite URLs in resources

Applies only to Web Applications

Application resources, like HTML, JavaScript and CSS, include absolute and relative URLs.

Typical reverse proxies only manipulate HTTP headers. They don’t parse web resource code, therefore this code isn’t manipulated. The HTML received by the client will contain absolute URLs based on what the platform generates, not considering reverse proxy transformations.

In OutSystems applications, a resource URL like CSS or JavaScript is generated from the request host header plus the application context.

In the example below, the URL for the application is to be changed by adding an extra path “apps” after the request host header. This scenario is used when there is a requirement to serve several applications under a common path.

This change will invalidate all absolute URLs in the resources (HTML, CSS and JavaScript).

To implement this requirement, we need to rewrite all URLs in the resources. This must be done in a request post-processing step before it is sent to the client, preferably at the reverse proxy level.

You can access here the configuration required on an Apache Web Server to implement this scenario.

This configuration covers both application runtime, development, and console administration (Service Center and Lifetime).

E - Disable content compression

Applies only to Web Applications

Application resources such as CSS, JavaScript, HTML and others are served compressed by the application servers. This feature reduces the payload and thus, the time to load the application.

In a reverse proxy scenario where the content requires a rewrite operation, the code cannot be compressed at the application server level.

To disable compression, follow these instructions:

Platform Level

Disable the platform's own AJAX compression by creating the OutSystems.HubEdition.CompressHttpAjaxResponse parameter in the OutSystems database, if it doesn't exist:

insert into OSSYS_PARAMETER (Name,Val) values ('OutSystems.HubEdition.CompressHttpAjaxResponse','False')

Description: If set to False, the AJAX responses will not be compressed by OutSystems (if IIS is configured to compress, AJAX responses will be compressed).

Parameter: OutSystems.HubEdition.CompressHttpAjaxResponse

Values: True / False 

Default: True

Application Server Level

Microsoft IIS

  1. Create the IIS.SetHttpCompression parameter in the OutSystems database, if it doesn't exist:

    insert into OSSYS_PARAMETER (Name,Val) values ('IIS.SetHttpCompression','False')

    Description: When set to False, instructs the Configuration Tool not to enable IIS compression settings.

    Parameter: IIS.SetHttpCompression

    Values: True / False

    Default: True

  2. In IIS Management Console, disable the static and dynamic content compression

JBoss AS 7.1.1

  1. In the OutSystems servers, edit the file /opt/jboss-as-7.1.1.Final/bin/standalone-outsystems.properties;
     
  2. Set org.apache.coyote.http11.Http11Protocol.COMPRESSION to off;
     
  3. Restart JBoss.

Wildfly 8.2

  1. In the OutSystems servers, edit the file /opt/wildfly-8.2.0.Final/standalone/configuration/standalone-outsystems.xml;
     
  2. Comment the following line, to look like this:

    <!--filter-ref name="gzipFilter" predicate="exists['%{o,Content-Type}'] and regex[pattern='(?:text/javascript|text/css|text/html|text/xml|text/json|application/json|application/javascript)(;.*)?', value=%{o,Content-Type}, full-match=true]"/-->
     
  3. Restart Wildfly.

F - Adjust keep-alive connection timeout

Applies only to Mobile Apps

Some reverse proxy implementations, namely Apache and Apache-based ones, have the keep-alive feature (also known as HTTP persistent connection feature) enabled by default and define a default connection timeout value of 5 seconds, which can cause issues on OutSystems mobile apps.

If you are using the persistent connection functionality in your reverse proxy, make sure that either the reverse proxy is not setting any keep-alive connection timeout, or the connection timeout value is set to at least 30 seconds

For example, to configure this setting in Apache-based software, use the KeepAliveTimeout directive in your server or virtual host configuration file:

KeepAliveTimeout 30

Note that this change might have a performance impact in Apache, especially under heavy load. Check the Apache documentation on the KeepAliveTimeout directive for more information.