This article explains how to configure Ideagen Internal Audit (Aura) to work with a reverse proxy. Setting up a reverse proxy is optional and is not part of a standard implementation — most organisations connect directly to the application server without one. However, some organisations choose to route traffic through a reverse proxy for network or security reasons, and this article covers what is needed to make that work.

The article covers two scenarios: maintaining the default WCF configuration when adding the proxy, and an alternative where the main application service is switched from message security to transport security. It also includes a reference guide to common error messages that may be encountered during configuration.

Background

In an out-the-box Ideagen Internal Audit (Aura) setup, connections between the components look like this:

• The desktop client connects to the main application service via encrypted message security, over http
• The browser connects to the WebUI service via https
• The WebUI service connects to the Web application service, also via https
• The Web application service connects to the main application service, via encrypted message security, over http

Adding a reverse proxy makes the system look like this:

• app.domain.com is a Ideagen Internal Audit (Aura) application server, running the main and Web services 
• proxy.domain.com is the reverse proxy 
• The desktop client connects to proxy.domain.com/Service 
• proxy.domain.com forwards the request to app.domain.com/Service 
• The browser connects to proxy.domain.com/WebUI 
• proxy.domain.com forwards the request to app.domain.com/WebUI 
• the WebUI connects to proxy.domain.com/WebService 
• proxy.domain.com forwards the request to the app.domain.com/WebService 
• The Web application service connects to the main application service directly

A note on SSL Offloading

It is common to use SSL offloading in this type of setup, whereby a client connects to the proxy via https, and the proxy then connects to the back-end Web server in clear http.

However, this is not possible with Ideagen Internal Audit (Aura).  The WCF bindings required by the application components preclude this mixing of https and http connection. 

SSL prerequisites where a reverse proxy is used

• Both the proxy server and the application server must be set up for https
• The proxy’s certificate must be trusted by the client PC’s
• The application server’s certificate must be trusted by the proxy, or the proxy must be configured to ignore any errors

The client PC’s do not need to trust the application server’s certificate.  Simply put:

• PC trusts proxy
• Proxy trusts app server, or ignores errors

Scenario 1:  adding the reverse proxy, maintaining the default WCF configuration

Unfortunately you cannot just swap out the server names specified in the client connection URL’s, because doing so causes content security policy and certificate trust violations.  So, in order to set this up you must take the steps described below.

Note: the assumption is that your starting point is a configured and working Ideagen Internal Audit (Aura) system where the client currently connects directly to the back-end app server.

Do an end-to-end test of https

The first thing to do is test that a client PC is able to access a page from IIS on the application server without errors or warnings.  If it cannot do this then this issue must be fixed before proceeding further. 

The service description pages are a good option for this test:

• If:
  • Your application is installed on server app.domain.com 
  • Your application is at app.domain.com/PentanaPRD
  • Your proxy is proxy.domain.com 
• Then you should be able to open the following two URLs in a browser with no errors or warnings:
  • https://proxy.domain.com/PentanaPRD/WebService/TngWebService.svc
  • http://proxy.domain.com/PentanaPRD/Service/TngService.svc

As well seeing a successful load of the pages, you should inspect the IIS logs on app.domain.com and verify that the request you made ended up at the correct port (443), in order to verify that SSL offloading is not being used:

Change the desktop client configuration

The method for making this change depends on how you deploy the application:

• If it is via ClickOnce, then the easiest way is via App Manager – open the correct instance, go to the Config tab, select the Client tab and make the changes. Clicking Save will cause the updated config file to be deployed 
• If it is via XCOPY, MSI or some other method then you will need to edit the file vision.exe.config in a text editor and then redeploy using your normal method 

The changes are as follows:

• Every time 

  app.domain.com appears, change it to proxy.domain.com. The locations are:
  • <Pentana.Tng.UI.Smart> - HelpURL
  • <system.serviceModel><client><endpoint> - for both TngService.svc and TngFileService.svc

Change the WebUI configuration

At the application server, open WebUI\Web.config (either in a text editor or in App Manager:  open the correct instance, go to the Config tab, select the Web UI tab).

The changes are as follows:

• Every time 

  app.domain.com appears, change it to proxy.domain.com. The locations are:
  • <Pentana.Tng.Agent.Web> - HelpURL (if present)
  • <Pentana.Tng.Agent.Web> - serviceUrl
  • <Pentana.Tng.Agent.Web> - imageStore
  • <system.serviceModel><client><endpoint>

If FBA is used, change the password reset email configuration

If all users are authenticated via Windows authentication then this can be ignored, but for consistency and certainly if FBA is used then the password reset email links should be updated:

• Open Service\Web.config (either in a text editor or in App Manager: open the correct instance, go to the Config tab, select the Service tab) 
• Find <Pentana.Tng.UI.Web.FBA> - urlLink 
• Update the URL with proxy.domain.com 
• Make the same change for:
  • FBA\Web.config
  • WebUI\Web.config

Scenario 2:  adding the reverse proxy, changing the main service to run under https

If you are wanting to change the setup so that the desktop client connects to the proxy (and then on to the main service) via https then the start point is different - it is necessary to change all of the application configuration files so that the main service is available under https before you begin.  This process is described in the KB article Ideagen Internal Audit (Aura): Converting the main service to https (and why not to).

So the steps are:

• Convert the application configuration to https, per the KB article.
• Then make the additional updates to configuration as described in the steps for Scenario 1

Potential error messages

There are so many moving parts to this that there are many possible misconfiguration problems.  Here are some of them.

WebUI:  “Something has gone wrong”

The WebUI error “Something has gone wrong 0 – The service call was not successful or has timed out” is a generic error that can occur for a number of reasons.  Normal troubleshooting is to press F12 and inspect the Console, and to examine the file WebService\TngWebService.log.  More descriptive error messages will be shown.

WebUI:  "Refused to connect to 'https://app.domain.com/[…]' because it violates the following Content Security Policy directive"

The following error, combined with an empty TngWebService.log file, indicates that the browser user is trying to access the system using the proxy address in their browser, but that WebUI\Web.config has not been configured with the proxy server address correctly and is still configured to access app.domain.com:

While it is tempting to try and fix this by editing the CSP in WebUI\Web.config, for example:

. . . this may then lead to an ERR_CERT_AUTHORITY_INVALID error, depending on whether the client PC trusts the SSL certificate for app.domain.com.

Hence, the fix is to open up the file WebUI\Web.config, and ensure that each reference to app.domain.com is changed to proxy.domain.com.

502 error

When trying to open https://proxy.domain.com/PentanaPRD/WebUI in the browser, a 502 error such as “Web server received an invalid response while acting as a gateway or proxy server.” likely means that the proxy does not trust the SSL certificate used by app.domain.com.  The proxy should either:

• Trust app.domain.com’s certificate, or 
• Ignore certificate errors

Desktop application:  “The provided URI scheme ‘https’ is invalid; expected ‘http’” or “An error occurred when verifying security for the message”

These errors indicate that

• the proxy may be attempting SSL offload
• the client is set up to connect to an https endpoint, but the service is listening on http

Check that the proxy is not set for SSL offloading, and check the configuration in the client file vision.exe.config is correct, based on the values in the server file Service\Web.config.

Note thought that “An error occurred when verifying security for the message” can also be caused by clock skew.

Desktop application:  “The remote server returned an error: (404) Not Found.”

This normally indicates that the client is expecting to connect via https, but the service is expecting an http connection.

Check that the files in use are from the same set (i.e. are all from the install set or are the modified https set).

Password reset emails contain the wrong server name

If users receive password reset emails that contain a URL for app.domain.com rather than proxy.domain.com, check that each of the following files has the correct value for urlLink set at <Pentana.Tng.UI.Web.FBA>:

• FBA\Web.config
• Service\Web.config
• WebUI\Web.config