Microsoft IIS

To use Microsoft IIS as reverse proxy in front of Axon Ivy Engine download and execute the powershell script iis-proxy-setup.ps1. Right click on the file and click Run with PowerShell. You need to run this script as Administrator.

The first time, when you execute this script, you may be asked for a Execution Policy Change so that this script can be executed. You need to answer this question with [A] Yes to All.

This script will guide you to set up IIS as reverse proxy for the Axon Ivy Engine. It is divided into several parts:

  • IIS Setup will install all required features including IIS itself, URL Rewrite and Application Request Routing (ARR) modules. Furthermore, it will enable the reverse proxy capabilities and set preserveHostHeader to true. The most important configuration entries in IIS are the Authentication and URL Rewrite modules.

    ../../../../_images/iis-overview.png

  • Rewrite Rule configures the rule for URL rewriting. It will add a new rule ivy-route-all to the Default Website. This will route all traffic to the Axon Ivy Engine which runs on the same host at http://localhost:8080. You may adjust this rule according to your needs when your Axon Ivy Engine runs on a different host, and/or on a different port. We recommend to limit the access to specific applications by only routing the application which is used by your users. You can do that by changing the pattern of the rule to YOUR-APP.* e.g., demo-portal.*.

    ../../../../_images/iis-url-rewrite.png

    There are features of Axon Ivy which requires WebSocket. Therefore we automatically install the WebSocket feature. IIS-ARR is not able to negotiate WebSocket compression, therefore we need to always set the HTTP Header SEC_WEBSOCKET_EXTENSIONS to empty. By adding HTTP_SEC_WEBSOCKET_EXTENSIONS to IIS Server Variable and setting HTTP_SEC_WEBSOCKET_EXTENSIONS on the ivy-route-all rewrite rule to empty.

  • Terminate SSL on IIS is that IIS serves the Axon Ivy Engine over HTTPS but the connection between IIS and Axon Ivy Engine is HTTP. We highly recommend to setup your IIS this way. This will create a new IIS Server Variable called HTTP_X-Forwarded-Proto and will be set to https on the ivy-route-all rewrite rule. This will send the HTTP Header X-Forwarded-Proto from IIS to the Axon Ivy Engine which is needed, that the Axon Ivy Engine can generate correct URLs.

    ../../../../_images/iis-terminate-ssl-server-variable.png
    ../../../../_images/iis-terminate-ssl-port.png

  • Setup SSO will configure Single Sign-on. This will enable Windows Authentication and will add a HTTP request header X-Forwarded-User with the current user to the request which will be forwarded to the Axon Ivy Engine. You will also need to activate Single Sign-on on the Axon Ivy Engine. Furthermore this will also enable Basic Authentication which is required for REST clients like the Axon Ivy Mobile App to call the protected REST Services provided by the Axon Ivy Engine. If you don’t need this you can manually disable it.

    Attention: If you enable SSO, you need to ensure exclusive access to the Axon Ivy Engine only over the IIS.

    ../../../../_images/iis-authentication.png

  • Serve with HTTPS is not covered by this script. This needs to be done manually. First of all you need to install a SSL certificate. This can be done on server level in section Server Certificate. Import your SSL certificate there or you can generate a self-signed certificate to try out HTTPS.

    ../../../../_images/iis-https-certificate.png

    After this step go to Default Website, open Handler Mappings and add https as a new binding. There you can choose now your SSL certificate. I highly recommend to remove the http binding. So that your Axon Ivy Engine only can be served over HTTPS via IIS.

    ../../../../_images/iis-https-binding.png