Microsoft IIS

We provide a Windows Powershell script to set up Microsoft IIS as a reverse proxy. We assumed the following when preparing this script:

Hard requirements:

  • You have at least Windows Powershell (v5.1) installed and available.

  • The Server Manager PowerShell interface is available.

Configurable requirements:

  • IIS is on the same host as the Axon Ivy Engine.

  • The Axon Ivy Engine is accessed via the Default Web Site of IIS.

  • There are no other applications served by this IIS. Otherwise, you need to adapt the IIS server level URL rewrite rules.

  • The script shall download the additional IIS modules required.

To use Microsoft IIS as a reverse proxy in front of your 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.

Hint

If you have not been asked about the Execution Policy Change but the script is still not running, you maybe need to unblock it via the Options menu (Properties -> General -> Security -> Unblock) or by running the following command in the PowerShell Unblock-File iis-proxy-setup.ps1

This script will guide you to set up IIS as a reverse proxy for the Axon Ivy Engine.

If your IIS server cannot access external links, you need to download the modules externally and upload them to your IIS server. Please check the download links for the modules in our script by searching for downloadModule. Once you have downloaded them, upload them onto the IIS server in a directory of your choice. Using the directory where you store our script is the most simple solution. Then, start the script and select No to the question titled IIS Module Source, and enter the path where you stored the modules in question IIS Modules Source Path.

The script is divided into several parts:

  • IIS Setup will install all required features including IIS itself, as well as the URL Rewrite and Application Request Routing (ARR) modules. Furthermore, it will enable the reverse proxy capabilities.

    ../../../../_images/iis-arr.png
    ../../../../_images/iis-enable-proxy.png

    And set preserveHostHeader to true. The most important configuration entries in IIS are the Authentication and URL Rewrite modules. The script will sense if IIS including all required features is already installed and will skip the IIS installation in that case.

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

  • URL Rewrite Rules configures the rules 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 applications that are available to your users. You can do that by changing the standard pattern .* of the rule to YOUR-APP.* e.g., demo-portal.*. e.g., system.*. If you have multiple apps being served by this IIS site, use a rule like (demo-portal|myApp1|myOtherApp)/.*. We suggest that you define a separate, internal-only website for access to the engine cockpit.

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

    There are features in Axon Ivy that require WebSocket communication. 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. We implement that adding HTTP_SEC_WEBSOCKET_EXTENSIONS to IIS Server Variables and setting HTTP_SEC_WEBSOCKET_EXTENSIONS on the ivy-route-all rewrite rule to empty.

  • Terminate SSL on IIS ensures that IIS serves the Axon Ivy Engine over HTTPS but the connection between IIS and Axon Ivy Engine is HTTP only. We highly recommend to setup your IIS this way. This will create a new IIS Server Variable called HTTP_X-Forwarded-Proto that 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. The Axon Ivy Engine needs this information to 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 that will be forwarded to the Axon Ivy Engine. You will also need to activate Single Sign-on on the Axon Ivy Engine in ivy.yaml. The script 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.

    Warning

    If you enable SSO, you need to make sure that your users can access the Axon Ivy Engine exclusively via IIS.

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

  • Serve with HTTPS is not covered by this script. You need to set this up manually. You need to install an SSL certificate. You can do this on the server level in section Server Certificate. Import your SSL certificate there. Alternatively, you can generate a self-signed certificate to try out HTTPS.

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

    Then, go to Default Website, open Handler Mappings and add https as a new binding. Choose the SSL certificate you supplied earlier. We strongly recommend to remove the http binding. This prevents your Axon Ivy Engine being accessible via HTTP through IIS.

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