Reverse Proxy

The purpose of a reverse proxy (or frontend web server) is to provide a single point of entry for one or more services from outside the network. The reverse proxy receives all requests from the clients and forwards them to the Axon Ivy Engine which handles them. This allows integrating the processes and applications that you are running on an Axon Ivy Engine into a company or web portal. The use of a reverse proxy provides higher security. You have to keep the reverse proxy up-to-date at any time with the latest security updates because this is also the entry point for attackers. In addition, we recommend that you block access to critical resources such as the Engine Cockpit.

We strongly recommend running a productive Axon Ivy Engine behind a reverse proxy. You should terminate the SSL traffic (HTTPS) on the reverse proxy and let the reverse proxy communicate with the Axon Ivy Engine via plain HTTP.

We have described how to integrate the Axon Ivy Engine with the following reverse proxy servers:

• NGINX
• Apache HTTP Server
• Microsoft IIS

Read carefully how to improve security by restricting the access to an Axon Ivy Engine when using a reverse proxy. Some reverse proxy servers provide Single Sign-on (SSO) functionality. The reverse proxy then is responsible to authenticate users.

The Engine Cockpit provides the web server view for debugging purposes while integrating a reverse proxy.

Base URL

Besides the setup of the reverse proxy itself, you always need to configure the base URL in ivy.yaml. The Axon Ivy Engine will use this configuration to create absolute links that are accessible to clients (e.g., for links in mails).

# sample ivy.yaml that configures the base URL for clients.
# https://acme.com will be the absolute URL prefix for links generated by Axon Ivy Engine.
BaseUrl: https://acme.com

HTTP Headers

To successfully integrate a reverse proxy with the Axon Ivy Engine you need to pass the host which the client itself initally has requested, so that the Axon Ivy Engine can generate correct URLs based on the request. All documented examples preserve this Host header, but if you integrate the Axon Ivy Engine with any other reverse proxy you need to pass the Host header to the Axon Ivy Engine. As an alternative you can provide X-Forwarded-Host for identifying the original host requested by the client.

Check out also the following headers in the example which need to be set correctly:

• X-Forwarded-For for identifying the originating IP address of a client connecting to the reverse proxy server. It should not affect functionality, but you may be glad to have the correct IP address of your client in the logs.

• X-Forwarded-Proto for identifying the protocol (HTTP or HTTPS) that a client used to connect to your reverse proxy server. This is important otherwise the generated links or redirects are wrong. Mostly only needed to terminate SSL on the reverse proxy server.

• X-Forwarded-Port for identifying the port that a client used to connect your reverse proxy server. This is only in charge if X-Forwarded-Proto is set and only needed if you don’t serve your site via non-standard ports (80 and 443).

You can change the name of the X-Forwarded headers in the ivy.yaml , see section ReverseProxy.