Skip to main content

Protecting Web Gateway Connections to InterSystems IRIS

This page describes options for protecting connections from the Web Gateway to InterSystems IRIS®. For more details on CSP authentication, see the Authentication Guide. Web Gateway connections to InterSystems IRIS can be protected according to the following levels of security:

  1. Minimal connection security (not recommended)

  2. Simple username- and password-based authentication

  3. Kerberos-based authentication and data protection

  4. SSL/TLS-based authentication and data protection

Remember that security applied here is solely for the purpose of authenticating the Web Gateway host to the InterSystems IRIS server. It protects against the unauthorized creation of connections between the Web Gateway and an InterSystems IRIS application server (%cspServer). It does not, however, identify an individual user of a web application. A user of a web application can only be positively identified by whatever user login facility is provided by the application itself. For example, a Systems Manager logging on to the Management Portal can only be identified by the username and password supplied to the Management Portal login form.

The stateless nature of the Web should also be borne in mind. There is no fixed relationship between a Web Gateway connection to InterSystems IRIS and an individual user of a web application. Many users share the same connection.

Authenticating the Web Gateway to InterSystems IRIS at connection time is important. If an attacker can impersonate a Web Gateway, it can redirect traffic through a system under his control (by technical means and/or social engineering) and read and/or modify data at will. This is distinct from authenticating individual users to a web application. The Web Gateway's InterSystems IRIS username and password, Windows network credentials, or UNIX® Kerberos key table should never be used by ordinary users.

Configuring Connection Security for the Web Gateway

To configure the connection security for the Web Gateway, in all cases you use the Web Gateway management pages. The relevant options are in the Configuration > Server Access > Connection Security section, which provides the following settings:

  • Connection Security Level — Choice of:

    • Password

    • Kerberos

    • Kerberos with packet integrity

    • Kerberos with encryption

    • SSL/TLS

  • Username

  • Password

  • Product

  • Service Principal Name

  • Key Table

Minimal Connection Security (Not Recommended)

To use minimal connection security, the Connection Security Level is set to Password and the Username and Password fields are left empty.

In this mode, there is a minimal level of security applied to the connection between the Web Gateway and InterSystems IRIS.

In this mode of operation, ensure that the Web Gateway service (%Service_WebGateway) together with the username under which it operates (for example, CSPSystem) is not expecting any form of authentication.

Simple Username/Password Authentication

Username/password authentication is the simplest form of authentication that can be applied between the Web Gateway and InterSystems IRIS. The installation process for an instance creates the CSPSystem user to authenticate Web Gateway access for the instance. This user (CSPSystem or any other) should have no expiration date; that is, its Expiration Date property should have a value of 0.

In all cases, the default username and password used for the Web Gateway is as follows:

Username: CSPSystem
Password: SYS

To configure simple username and password authentication for an instance using the Web Gateway management pages, modify the server access profile by setting the Connection Security Level to Password and then supplying values for the Username and Password.

For any InterSystems IRIS application server, you can change the credentials for the user account which grants access to the Web Gateway as you wish. However, you must also update the corresponding server access profile in the Web Gateway with these new credentials. Otherwise, the Web Gateway is unable to establish new connections to that application server. Keep in mind that passwords cannot begin with { and end with }, because the Web Gateway attempts to interpret strings between these braces as a password retrieval command.

Remember: passwords are a weak form of authentication since they must be sent over the network as plain text for authentication in InterSystems IRIS. Network sniffing is easy to do and can be used to reveal these passwords. Passwords used in this configuration option must be held in the Web Gateway configuration file in accordance with the following guidelines.

For UNIX®, Linux, and macOS, passwords in the CSP.ini file are stored as base64 hashes. For Windows, passwords are encrypted in the Web Gateway configuration file using functionality provided by Microsoft’s Data Protection API (DPAPI). The Web Gateway Management Default Parameters page handles the encryption of passwords.


This password encryption is used for Windows because ordinary Windows user accounts are occasionally granted membership in the Administrators Group, although this is not recommended practice for production systems. Encrypting the password offers a higher level of protection for all Windows installations.

Passwords Introduced from Outside

Occasionally, you need to introduce a password outside the context of the Web Gateway Management pages, for example, if the Web Gateway configuration is set up by custom configuration scripts. In this case, the password should be filed as plain text and the Web Gateway encrypts it when it is started for the first time. If you use this method, the password to the Gateway Management forms cannot start with '1' or 'PBKDF2|', and the password to IRIS cannot start with ']]]'. If you need passwords that start with these characters, use the CSPpwd utility at the OS command prompt instead. This utility encodes passwords held in the Web Gateway configuration file. The general form is:

CSPpwd <path to the|dll library> <context> <clear text password>


  • context = 0: Password to the Web Gateway management pages

  • context = 2: Password to Cache/IRIS servers

The encoded password is written to the standard output.

Examples (Windows):

CSPpwd C:\Inetpub\CSPGateway\CSPx.dll 0 MyGatewayManagementPassword
CSPpwd C:\Inetpub\CSPGateway\CSPx.dll 2 MyIRISServerPassword

Examples (UNIX®):

CSPpwd /opt/webgateway/bin/ 0 MyGatewayManagementPassword
CSPpwd /opt/webgateway/bin/ 2 MyIRISServerPassword

Passwords Encrypted on Other Computers

On Windows, the web server uses the machine store rather than a user store. Consequently, DPAPI password encryption is machine-specific; it is not possible to decrypt a Web Gateway password that was encrypted on another computer. This means it is impossible for machines in a clustered environment to share information within a CSP.ini file.

Here are some possible solutions to this problem:

  • Use a machine outside of the cluster as the web server.

  • Each time you fail over, reset the same password in the Web Gateway.

  • Configure each computer participating in the cluster so that it has its own copy of the Web Gateway configuration file on a disk that does not belong to the cluster. InterSystems IRIS maintains the file in the directory hosting the Web Gateway DLLs. Save and encrypt the password on each individual computer before introducing the node to the cluster.

    For example, where Disk C from each machine does not belong to the cluster and InterSystems IRIS is installed on Disk S, you may have the following:

    CLUNODE-1: A copy of CSP.ini with password XXX encrypted by CLUNODE-1

    CLUNODE-2: A copy of CSP.ini with password XXX encrypted by CLUNODE-2

  • Disable password encryption by manually adding the following directive to the configuration file before starting the Web Gateway and adding the passwords:


Retrieve Passwords Programmatically (UNIX®/Linux/macOS)

On UNIX®/Linux/macOS systems, you can instruct the Web Gateway to execute an operating system command which retrieves the password from a secure storage solution (such as a vault application or a mounted secret file) instead of providing the password itself as plain text. To do so, provide the command within braces ({}) in the Password field of an instance’s server access profile using the Web Gateway management pages. Alternatively, you can set the corresponding CSP.ini parameter (Password) directlyPassword parameter within the section of the CSP.ini file that corresponds to the instance. For example, a CSP.ini file may contain the following line:

Password={sh /tmp/}

The string is stored as a base64 hash value within the CSP.ini file, just like a plain text password would be.

The Web Gateway executes the command you provide when you save the server access profile using the Web Gateway management pages or when the RELOAD=1 flag is found in the CSP.ini file’s [SYSTEM] section. The output of the command is then stored as the password for the instance within memory. The command that you provide must be sufficient to retrieve the password without further action: the command line interface for your secure storage solution must be fully configured on your system and any credentials needed must be available in environment variables or configuration files.


You can also use this method to retrieve an SSL/TLS Private Key Password programmatically within a server access profile or within the CSP.ini file.

Kerberos-based Authentication and Data Protection

To use Kerberos-based Authentication and Data Protection, three levels of authentication (and data protection) are provided through the Connection Security Level parameter.

  1. Kerberos. This option provides initial authentication only for the connection.

  2. Kerberos with Packet Integrity. This option provides initial authentication and guarantees data packet integrity.

  3. Kerberos with Encryption. This is the highest level of security and provides initial authentication, guaranteed data packet integrity, and, finally, encryption for all transmitted messages.

Kerberos Library

To use any of the Kerberos-based modes, the Web Gateway must be able to load the InterSystems Kerberos client library:

  • Windows DLL: irisconnect.dll

  • UNIX® Shared Object:

Install the appropriate library in a location specified in the PATH environment variable for the operating system or at one of the following locations relative to the Web Gateway installation.

  • . (that is, local to the Web Gateway)

  • ./bin

  • ../bin

  • ../../bin

The Web Gateway attempts to load the library at the time it is first required. If successful, the following status message is written to the Web Gateway Event Log:

Web Gateway Initialization The IRISCONNECT library is loaded - Version: 

(This library is used for the optional Kerberos-based security between the Web Gateway and InterSystems IRIS.)

If the Web Gateway is unable to locate or link to the IRISCONNECT library, a suitable statement of failure and error message is written to the Web Gateway Event Log.

For Kerberized communications between the Web Gateway and InterSystems IRIS, the Web Gateway is the Kerberos client.

The procedure for configuring the Web Gateway to use Kerberos is in the Windows section.

Overriding the Library Path If You Use SSL/TLS

By default, the Web Gateway expects dependent security libraries (shared objects) to be installed in its home directory (that is, the directory with the Web Gateway binaries).

If you use SSL/TLS connectivity between the Web Gateway and InterSystems IRIS, these libraries include the IRISCONNECT library and SSL/TLS libraries (on UNIX®: and, on Windows: libcrypto-1_1-x64.dll and libssl-1_1-x64.dll).

When the Web Gateway and IRISCONNECT libraries, loaded in the web server's process space, load a copy of the SSL/TLS libraries, there is a conflict between different versions of the same libraries that were previously loaded by the hosting web server. To ensure that only one copy of the SSL/TLS libraries are loaded in the web server process space, the Web Gateway must instruct the IRISCONNECT library to source the SSL/TLS libraries from the same location as those used by the hosting web server.

The Web Gateway Management Default Parameters page provides the parameter SSL/TLS Library Path to allow you to use an alternative set of OpenSSL libraries. For example:

SSL/TLS Library Path = /usr/bin/  

It is possible to create an Apache installation that does not permit OpenSSL usage, and it is possible to configure Apache to disable OpenSSL. In this situation, the Web Gateway loads the libraries it was shipped with unless SSL/TLS Library Path is set to a different location.

If a library version mismatch occurs between Apache and the Web Gateway, TLS connections between the Web Gateway and an InterSystems IRIS instance can fail. A TLS error can occur when a connection is attempted, or the Web Gateway might crash with SIGSEGV when calling an OpenSSL function.


Kerberos key tables are not implemented for Windows. Therefore, authentication uses network credentials that are either obtained when the hosting service starts in a named account or from the Trusted Computing Base (TCB) when the hosting service runs in the System Logon Session (that is, as LOCAL SYSTEM).

Windows domain accounts use a permanent key derived from a password to acquire a Kerberos Ticket Granting Ticket (TGT) and service ticket for the local machine. The local machine must also have a permanent Kerberos key, shared with the Key Distribution Centre (KDC) component of the domain controller. That key can be used to acquire a TGT and service ticket to authenticate to another Kerberos principal such as InterSystems IRIS.

For practical purposes the Web Gateway, operating within the context of a Windows-based web server is operating through either the Network Service logon session or the System logon session. The account used must have Log on as a batch job rights assigned.

The built-in Network Service logon session has access to the machine's credentials and is designed for services that need network credentials to authenticate to other machines. However, the Network Service logon session is not always present. The System logon session can also be used for the purpose of authenticating the Web Gateway to InterSystems IRIS.

For IIS installations, and ISAPI extensions in particular, using the Network Service login session is the preferred means through which both databases (local and remote) and remote computers should be accessed.

Windows Web Gateway Configuration for Kerberos

  • Set the Service Principal Name to that of the target InterSystems IRIS server that the Web Gateway is connecting to.

  • Leave the Username, Password, and Key Table fields empty.

  • The client principal name (or client username) is that of the Web Gateway host. This is the Kerberos name representing the Web Gateway hosts' network service session: <computer_name>$

  • Assign this principal the necessary privileges in the InterSystems IRIS server to allow the Web Gateway’s service to operate.

UNIX® Web Gateway Configuration for Kerberos

These operating systems support Kerberos Key Tables.

UNIX® Web Gateway Configuration for Kerberos

The Web Gateway configuration is conceptually more straightforward for these systems.

  • Set the Service Principal Name to that of the target InterSystems IRIS server that the Web Gateway is connecting to.

  • Enter the name of the key table file (including the full path) in the Key Table field.

  • Set the Username field to the name of the appropriate key in the key table file.

  • Leave the Password field empty.

  • The client principal name (or client username) is that of the Web Gateway host. This is the name used to identify the key in the Kerberos Key Table. Assign this principal the necessary privileges in the InterSystems IRIS server to allow the service of the Web Gateway to operate.

SSL/TLS-Based Authentication and Data Protection

You can also use the SSL/TLS protocol to secure communications between the Web Gateway and InterSystems IRIS.

In this mode, the SSL/TLS transport, as configured for this host, secures connections to InterSystems IRIS. The SSL/TLS Configuration Name field should be set to the appropriate value for the target server. The Service Principal Name and Key Table fields are not relevant and should be left empty.

For more information on creating SSL/TLS client configurations for InterSystems IRIS systems, see Configuring the Web Gateway to Connect to InterSystems IRIS Using TLS.

FeedbackOpens in a new tab