· 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 (7)6
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.

i am using a different method which is quite similar to this, also added the http to https redirect.

in httpd.conf file add one line to include ssl.conf file

Include conf/ssl.conf

create a new ssl.conf

Listen 52443 https
SSLPassPhraseDialog exec:/usr/libexec/httpd-ssl-pass-dialog
SSLCryptoDevice builtin
<VirtualHost *:52773>
    ServerName localhost
    Redirect "/" ""
<VirtualHost _default_:52443>
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
LogLevel warn
SSLEngine on
SSLProtocol all -TLSv1 -TLSv1.1 -TLSv1.2 -SSLv3
SSLHonorCipherOrder on
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
SSLCertificateChainFile /etc/pki/tls/certs/server-chain.crt
<FilesMatch "\.(log|ini|pid|exe|so)$">
        Require all denied
        SSLOptions +StdEnvVars
         nokeepalive ssl-unclean-shutdown \
         downgrade-1.0 force-response-1.0
CustomLog logs/ssl_request_log \
          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

restart database, you will still seeing the http process listening on the original port.

but when you copy the original url (http) to browser, it will redirect to https.