In the WRC, we frequently see customers contact us because their Web Gateway is unable to serve web pages. This article will explain a frequent reason why these errors can occur, and explain some tools which can be used to debug the problem. This explanation is focused on the Web Gateway serving InterSystems IRIS instances, but the same explanation should apply to the CSP Gateway serving Caché instances as well.

The Problem:

Attempting to load a Web Application (either a custom application or the System Management Portal) results in one of the following errors (depending on your browser):

In addition, the CSP.log file shows:

Why this happens:

To understand why this happens, we need to take a look at the architecture which the Web Gateway functions in:

When you try to load your application in a browser, the browser sends a request to your Web Server. The Web Server passes this request off to the Web Gateway. The Web Gateway then has to reach out to InterSystems IRIS to understand what to do with the request. But given that the Web Gateway lives outside of InterSystems IRIS (and might be on another machine entirely), we require that the Web Gateway process authenticate to IRIS. This is the same as we would require for any other new processes connecting to IRIS, such as remote ODBC connections or a simple local IRIS Terminal Sessions.

The reason we are seeing the above errors when loading the application are because this authentication from the Web Gateway to IRIS is failing. The Web Gateway configuration stores within its CSP.ini file a set of credentials for each InterSystems IRIS server it connects to. Normally, these credentials are for the “CSPSystem” user, which is an account created by default when IRIS is installed. These credentials are then used to try and authenticate using the settings configured for the %Service_WebGateway Service in IRIS.

 To understand more information about why this authentication is failing, you can use the Audit capabilities offered by InterSystems IRIS. Given that you likely cannot use the Management Portal at this time, you can use the ^SECURITY routine in an IRIS Terminal Session in order to configure Auditing and view the Audit Log.

First off, you will need to Enable Auditing, if it has not already been enabled:

Next, make sure that Auditing for the %System/%Login/LoginFailure Event is enabled:

Once you’ve done that, you can reproduce the “Server Availability Error” problem. This should result in a LoginFailure Audit Event being logged, and you can examine the details for this event to find out more:

The “Error message” section should provide more information about why we are seeing the LoginFailure. Common problems include “User CSPSystem is disabled” or “Service %Service_WebGateway is not enabled for Password authentication”, which suggest changes which should be made to the IRIS Security Settings.

The most common problem that we see in the WRC is that authentication is failing due to “Invalid password”. This means that the CSPSystem password stored in the Web Gateway does not match the CSPSystem password stored in IRIS.

How to fix the problem:

Now that the Audit Log entry gives you a clear indication of what the mismatch is between the Web Gateway and InterSystems IRIS, you have to fix that mismatch. The IRIS-side CSPSystem credentials can be modified through the ^SECURITY menu in a Terminal session.

There are a few ways to modify the CSPSystem credentials stored in the Web Gateway. The easiest way will be to access the Web Gateway Management Portal, which is documented here: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GCGI_oper_config  Once you’ve loaded the Web Gateway Management Page, you can edit the credentials used to authenticate to IRIS by clicking the Server Access link, and editing the Connection Security settings for the relevant Server.

If you are not able to access the Web Gateway Management Page, then you are left with editing the CSP.ini file. The CSP.ini file should have sections for each Server Definition configured in the Web Gateway. You should be able to edit the “Username” and “Password” sections in the relevant section to match what is stored in InterSystems IRIS. Note that the [SYSTEM] section controls access to the Web Gateway Management Portal, not an InterSystems IRIS instance named [SYSTEM].

For example, if you have a definition to server “Test” where the CSPSystem password is incorrect:

You can edit the CSP.ini file to have the correct plaintext password:

The next time you try to authenticate from the Web Gateway to InterSystems IRIS, the password will be encrypted: