Mutual TLS (mTLS)

Introduction

InterSystems IRIS supports mutual TLS (mTLS) for authentication between an instance and the InterSystems Web Gateway. Mutual TLS, also known as two-way TLS or client-authenticated TLS, is a security protocol that enhances the authentication process in a network communication. It establishes a secure connection between a client and a server (for InterSystems IRIS, this is the Web Gateway and an InterSystems IRIS instance respectively) by validating the identities of both parties using digital certificates. Mutual TLS follows a standard TLS handshake process but with an additional step for client authentication. After the client initiates a connection and the server responds with its certificate, the server requests the client’s certificate for mutual authentication. The client then sends its certificate to the server, and both parties exchange a finished message to confirm the completion of the handshake. Both certificates (server and client) must be signed by a trusted Certificate Authority (CA).

Prerequisites

There are several prerequisites to enabling mutual TLS for InterSystems IRIS. Before getting started, ensure you have:

• A Web Gateway that can communicate with InterSystems IRIS. See Set Up a Web Gateway for more details on how to set up the Web Gateway.

• A trusted CA certificate.

• The certificate and private key for the InterSystems IRIS superserver. See Managing Superservers for more details on the superserver.

Once you have gathered the required certificates and installed the web server, you must configure a SSL/TLS definition for the superserver. Refer to Configuring TLS for more details on how to do this. Ensure Client certificate verification is set to Request or Require. After this, configure a superserver to use this TLS definition. Note the port for this superserver.

By now, you should have a Web Gateway set up and a superserver configured to use TLS with client certificate verification.

Set Up

Once you have a web server installed and a superserver configured to use TLS with client certificate verification, follow the steps below to set up mTLS authentication for the Web Gateway.

1. Turn on mTLS authentication in %Service_WebGateway. See Services for details on this service.

2. Using your preferred method, generate a new certificate for the Web Gateway where the CN (common name) field is the name of an existing InterSystems IRIS user. Have the trusted CA sign this certificate.

3. Configure the Web Gateway to use this certificate.

   1. Authenticate to the Web Gateway management page. See Accessing the Web Gateway Management Pages for details.

   2. Under Configuration, go to Server Access and edit or create a server configuration profile.

   3. Ensure the Superserver TCP Port field matches the port of the superserver you previously configured to use TLS.

   4. Under Connection Security, set the Connection Security Level to SSL/TLS.

   5. Clear any existing values for User Name and Password. These values take priority over mutual TLS.

   6. Enter the path to the Web Gateway certificate that you generated in step 2 in the SSL/TLS Certificate File field.

   7. Enter the path to the Web Gateway private key that you generated in step 2 in the SSL/TLS Private Key File field.

   8. Enter the path to the CA certificate that signed the superserver certificate in the SSL/TLS CA Certificate File field so that the Web Gateway can verify the superserver’s certificate.

   9. If applicable, enter the Web Gateway private key password in the SSL/TLS Private Key Password field.

   10. Save the configuration.

By now, you should have enabled mTLS authentication in %Service_WebGateway and configured the Web Gateway to use TLS with the CA-signed certificate where the CN field is an existing InterSystems IRIS user.

Testing

Once you have completed set up, you can test whether mutual TLS authentication succeeds using the Web Gateway. Follow the below steps to test the authentication:

1. Close all Web Gateway connections.

   1. From the Web Gateway portal, go to Management > System Status.

   2. Close all server connections and click the refresh button.

2. Test the server connection.

   1. From the Web Gateway portal, go to Management > Test Server Connection.

   2. Select the server profile name that you configured for mutual TLS during setup.

   3. Click Connect.

If the server connection failed, you can check the audit database for LoginFailure events from %Service_WebGateway. Ensure the CN field of the Web Gateway certificate matches the username of an existing InterSystems IRIS user. If no such event exists in the audit database, ensure that the system is auditing for LoginFailure events. See Auditing for more details.

If you enabled auditing for LoginFailure events and do not see this event, go to the Event Log in the Web Gateway management page and review the log messages for further troubleshooting. If you have SELinux in enforcing mode, please refer to the SELinux Considerations.

SELinux Considerations

If SELinux is set to enforcing mode, then mutual TLS authentication fails to connect to the superserver unless you configure the SELinux contexts for the certificates correctly. You must ensure the contexts and OS permissions are correctly set for the CA, the superserver, and the Web Gateway certificates and associated private keys.

Superserver Certificate Context

Ensure the superserver certificate and trusted CA certificate are readable by the irisusr group and are configured with the appropriate context. If generated in <IRIS-install-dir>/mgr/, then they should already have the correct context as files inherit the context of their original parent directory. If they were not, then move them to <IRIS-install-dir>/mgr/ and run the following commands in the Linux command-line interface:

# restorecon -vF <IRIS-install-dir>/mgr/<superserver_certificate.cer>
# restorecon -vF <IRIS-install-dir>/mgr/<superserver_private.key>
# restorecon -vF <IRIS-install-dir>/mgr/<trusted_CA_certificate.cer>

The restorecon command restores the context of the file to that of the parent directory. Ensure that the superserver TLS configuration has the correct path for these files.

Web Gateway Certificate Context

Additionally, you must ensure that the Web Gateway private key, certificate, and superserver CA certificate are readable by the web server user or group and configured with the appropriate context. To set the appropriate context, first place the Web Gateway private key, certificate, and superserver CA certificate in the /etc/ssl/certs/ directory. Then, run the following commands in the Linux command-line interface.

# restorecon -vF /etc/ssl/certs/<WebGateway_certificate.cer>
# restorecon -vF /etc/ssl/certs/<WebGateway_private.key>
# restorecon -vF /etc/ssl/certs/<superserver_CA_certificate.cer>

The restorecon command restores the context of the file to that of the parent directory. Ensure that the Web Gateway server access profile has the correct path for these files.