· Aug 12, 2020 2m read

Running the Management Portal (Private Web Server) Over TLS/SSL/HTTPS

Updated Jan 19th, 2023.


Hi all,


I want to share a quick little method you can use to enable ssl with a self signed certificate on your local development instance of IRIS/HealthShare. This enables you to test https-specific features such as OAuth without a huge lift.



1. Install OpenSSL

Windows     : Download from or other built OpenSSL Binary. 

Debian Linux: $ sudo apt-get -y install openssl

RHEL        : $ sudo yum install openssl


2. Create a self-signed certificate pair. In your terminal (powershell, bash, zsh, etc)

$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout apache-selfsigned.key -out apache-selfsigned.crt

Note -- This above command will create a certificate that lasts for a year.

3. Edit your private web-server to use the new self-signed certificate pair.

In you instance installation directory, edit your pws config <install-dir>/httpd/conf/httpd-local.conf. Add the following section before the "Include .. " directives.

# Port to listen for secure traffic On. The default is 443
# Update Jan 19th, 2023: No longer required to manually load the ssl_module
# LoadModule ssl_module "modules/"
Listen 10443

# Listen Virtual Host Block to define the keys we should use for that port
# If you define a different port in the Listen directive, change that here as well
<VirtualHost *:10443>

    # We need a servername, if you have a server name for your certificate, make sure to match that here.
    ServerName mysecureinstance

    # Turn on SSL for this Virtual Host
    SSLEngine on

    #key files, replace these paths with the path you generated the keys from in step 2.
    SSLCertificateFile "/path/to/apache-selfsigned.crt"

    SSLCertificateKeyFile "/path/to/apache-selfsigned.key"


Here is an example of my config file:



In action:



Note: using the private web server for anything other than the server management may encounter performance errors and isn't explicitly supported for a production configuration. A better option would be to configure the apache / httpd or IIS web server using the default web gateway. You can find instructions to configure a dedicated web server in our Web Gateway Guide, or contact someone at InterSystems.


Discussion (6)5
Log in or sign up to continue

I am not sure! This will secure any traffic hosted by the instance itself on the port added to the config (10443 in the example). It also does not change the way links are generated. If the portal webpage uses relative links, then it could secure those requests, but they ultimately don't connect through the instance so really security is out of our hands there.

This method simply opens an additional port on the included Apache server secured by the self-signed certificate. The non-secure ports will still work so this isn't a viable production strategy.

This is sort of the minimum for just enabling SSL/TLS on apache.  Please see apache documentation for further configuration options, including but not limited to selecting ciphersuites and configuring client verification:

Also, please recall that private web server is provided for convenience and that for production purposes you should install a CSP/Web Gateway into a full web server.  Per this documentation, quote:

When installing InterSystems IRIS, this private version of Apache is installed to ensure that:

  1. The Management Portal runs out of the box.
  2. An out-of-the-box testing capability is provided for development environments.

The PWS is not supported for any other purpose.

For deployments of http-based applications, including REST, CSP, Zen, and SOAP over http or https, you should not use the private web server for any application other than the Management Portal; instead, you must install and deploy one of the supported web servers. For information, see the section “Supported Web Servers” in the online InterSystems Supported Platforms document for this release.

end quote.

Just one little addition to this InterSystems Data Platform Best Practice, which saved me a lot of time: 

if you may have tried this on a Windows machine with a password protected private key file (for example: created with the built-in Public Key Infrastructure of InterSystems products), you probably ran into this error message in the Apache error.log:
SSLPassPhraseDialog builtin is not supported on Win32

That's because- as the message suggests- the SSLPassPhraseDialog directive is not supported on Windows version of Apache 2.4 and it can't prompt you for your private key password on startup.

The solution is:
a) to make sure, that the SSLPassPhraseDialog directive is not explicitly turned on in your httpd.conf file (or additional include files) and
b) remove the pass phrase from your private key file with the following openssl command:
openssl rsa -in privatekey-withpass.key -out  privatekey-nopass.key

BTW: you don't necessarily need to install OpenSSL on your own. InterSystems products (at least at the moment) come with an openssl executable in their bin directories. Of course: if you want to make sure, that you use the latest and most secure version of the tool, it's better to install it separately.