Configure NGINX

Below you will find a description of how to configure NGINX as a reverse proxy for Intrexx.

If you want to create your own configurations for web front-ends (Nginx, IIS, Apache, HAProxy, TrafficServer or similar), please note the following:

HTTPS

  • Access only via HTTPS

  • Redirect from HTTP to HTTPS

Blocked URLs

  • Hidden files and directories starting with ... Exception : /.well-known/

  • /WEB-INF/ (recursive)

  • /web.config

  • /bin/ (recursive)

1. Adjust the configuration file

If upgrading in the NGINX configuration file, replace the line

location ~ (css|download|images|include|is|script|temp|thirdparty|userfiles) {

with the following line

location ~ ^(/css|/fonts|/images|/include|/script|/thirdparty|/userfiles|/download|/is) {

Usually, this affects NGINX configuration files that were created with Intrexx 20.09, Intrexx 20.03 OU3, 19.09, 19.03 OU13 or older.

Intrexx version 12.0.1

The adjustments for Intrexx 12.0.1 are related to the changed access options for the "userfiles" directory ("<portal directory> \external\htmlroot\userfiles"), to which image files can be uploaded by portal users and downloaded again from there if configured accordingly.

Further information on this can be found in the section Portal properties - Security - Upload/Download.

Up to Intrexx 12.0.0, the image files were made available via the front-end web server (reverse proxy). As of Intrexx 12.0.1, this is done via the web server integrated in Intrexx (Tomcat). For this reason, the "userfiles" directory must be removed from the configuration file.

Further information on the front-end web server (reverse proxy) and embedded Tomcat can be found in section Using the front-end web server (reverse proxy).

If upgrading in the NGINX configuration file, replace the line

location ~ (css|download|images|include|is|script|temp|thirdparty|userfiles) {

with the following line

location ~ ^(/css|/fonts|/images|/include|/script|/thirdparty) {

Usually, this affects NGINX configuration files that were created with Intrexx 20.09, Intrexx 20.03 OU3, 19.09, 19.03 OU13 or older.

NGINX is configured via configuration files. After downloading the Intrexx setup files, you will find three template files for configuring NGINX. You can use this as a basis for configuring your NGINX.

The template files can be found under the following path: <INTREXX-ROOT>/samples/web-tls-configuration/nginx/

The names of the template files are portal-intranet.conf, portal-internet.conf and portal-remote.conf

Please note: The "portal-internet.conf" file contains more entries than the "portal-intranet.conf" file as it also contains a section for configuring the OCSP stapling.

You can view both files via the following two expandable links and already get an idea of what they look like.

Open the file with an editor of your choice to make the adjustments you need.

TODOs

The file contains instructions for the configuration. Each one of these is labeled with "TODO".
The most important TODOs are:

  • The specification of the web connector and port

  • The specification of the server name (fully qualified domain name) and port

  • Specifications relating to SSL

  • The path to the certificate file (*.cer or *.pem) and the private key

It is also important that the path to the portal's "external/htmlroot" directory is specified correctly.

  1. To do this select "Portal properties" from the "Portal" menu and go to "Web configuration > Front-end web server".

    Name

    Description

    NGINX virtual host

    "NGINX virtual host" refers to the embedded Tomcat. NGINX connects to the Intrexx portal service via the virtual host. Typically, "localhost" should be entered here. (One exception to this is when NGINX is installed on a different server to Intrexx. In this case, the Intrexx server should be specified here.)

    NGINX configuration file

    You can generate the NGINX configuration file with Intrexx.

    Enter the path to the directory that the NGINX configuration file should be generated in.
    Example: /myfolder/portal.example.com.conf
    Afterwards, copy and link the NGINX configuration file to the desired folder within /etc/nginx.
    Example: /etc/nginx/sites-available/portal.example.com.conf

    Embedded Tomcat Port

    The port that you used in the previous version of Intrexx will be shown here. You can leave this port as it is.

    Note: Port 1337 is predefined here for a new installation.

    Base URL of the portal

    The base URL needs to be entered here.
    The first part refers to the protocol. Bear in mind that https is specified here. The second part is made up of the hostname that you defined in the NGINX configuration file. Please make sure that this ends with a slash (/). It is essential that this is correct so that your portal can be accessed in the browser.

  2. Click on "OK".
    Intrexx will now generate the configuration file. The data entered in the edit fields will be written in the configuration file. The generated file is stored in the specified directory.

2. Save the configuration file in the "sites-available" directory.

Move the configuration file to the "sites-available" directory.

Please note: Depending on the Linux distribution and the selected installation package, the "sites-available" directory may not be available in some cases.

Usually, the "sites-available/site-enabled" directories are provided when you install NGINX from repositories of Debian-based distributions. If you get NGINX from the NGINX repository, then the directories won't exist. In this case, only conf.d/ is present. The same applies to other Linux distributions such as CentOS. In this case as well, you only have conf.d/.

If this is the case, please find out how the configuration file needs to be implemented for your Linux distribution.

3. Create a symbolic link to the configuration file

Create a symbolic link from sites-enabled to the sites-available file. Use the full paths when doing this.

Please note: When using symbolic links, you should make sure that these are created directly in the desired directory.

Example: "ln -s /etc/nginx/sites-available/host.example.org.conf"

4. Restart NGINX

Restart NGINX.

NGINX and Intrexx on different servers (NGINX on remote machine)

  1. If NGINX is running on a different server to Intrexx, you need to comment out the following blocks in the configuration file:

    Root directive (the root path of the Intrexx web application)

    • Settings for favicon and robots (server favicon and robots.txt)

    • Settings for static files (static files that should be served by NGINX)

    It is necessary to comment out these blocks so that static files are not delivered by NGINX as it has no access to the remote htmlroot of the portal.

  2. You must set the "NonLoopback" parameter to "true" in the "web.xml" file (<Portalverteichnis>\external\htmlroot\WEB-INF\web.xml).

    <init-param>
        <description>
            Allow receiving security-sensitive headers on non-loopback network interfaces.
            Values: true or false (default).
         </description>
        <param-name>connector.security.header.receiveOnNonLoopbackInterface</param-name>
        <param-value>true</param-value>
    </init-param>
    

See also the example configuration file portal-remote.conf.

Configure WebSockets

So that you can use WebSockets in conjunction with NGINX, you need to specify which URLs should be forwarded to the back end via the WebSocket protocol in the NGINX configuration file. This looks like this for the default configuration:

...

# Delegate WebSocket requests to the Intrexx Portal Service.

#

location /ws/ {

proxy_pass https://backend;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "Upgrade";

}

# Delegate requests to the Intrexx Portal Service.

#

location / {

proxy_pass https://backend;

...

 

Note When upgrading from an earlier Intrexx version, the existing configuration file must be adapted accordingly so that WebSockets can be used.

More information about WebSockets is available here.