Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

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 to the CSP engine (%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)

In 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

In username/password, the Connection Security Level is set to Password and values are supplied for the Username and Password.

This is the simplest form of authentication that can be applied between the Web Gateway and InterSystems IRIS.

Remember that 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.

In all cases, the default username and password used for the Web Gateway is as follows. The installation process creates the CSPSystem user for this purpose. This user (CSPSystem or any other) should have no expiration date; that is, its Expiration Date property should have a value of 0. 

Username: CSPSystem
Password: SYS

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.

Note:

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 CSPx.so|dll library> <context> <clear text password>

Where:

  • context = 0: Password to the Gateway Management forms

  • context = 2: Password to Cache/IRIS servers

The encoded password is written to the standard output.

Examples (Windows):

CSPpwd C:\cachesys\csp\bin\CSPx.dll 0 MyGatewayManagementPassword
CSPpwd C:\cachesys\csp\bin\CSPx.dll 2 MyIRISServerPassword

Examples (UNIX®):

CSPpwd /opt/cspgateway/bin/CSPx.so 0 MyGatewayManagementPassword
CSPpwd /opt/cspgateway/bin/CSPx.so 2 MyIRISServerPassword

Passwords Encrypted on Other Computers

Because the web server hosting the Web Gateway operates within a protected environment where there is no available user profile on which to base the encryption, it must use the machine store rather than the user store. Consequently, it is not possible to decrypt a Web Gateway password that was encrypted on another computer. This creates a situation for clustered environments in which the configuration file is on a shared drive and is shared among multiple participating computers. Only the computer that actually performs the password encryption can decrypt it. It is not possible to move a configuration file containing encrypted passwords to another computer; the password must be reentered and reencrypted on the new machine.

Here are some possible approaches 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 file before starting the Web Gateway and adding the passwords:

           [SYSTEM]
       DPAPI=Disabled

Kerberos-based Authentication and Data Protection

In 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: irisconnect.so

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: 5.3.0.175.0.

(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®: libssl.so and libcrypto.so, 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/
Important:

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.

Windows

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 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.

CGI Environment Variables Passed by the Web GatewayNext section
Previous sectionManaging and Monitoring the Web Gateway
FeedbackOpens in a new tab