HTTPS and the OutSystems Platform

HTTPS and the OutSystems Platform

This topic intends to be a collection of documents on how to configure the OutSystems Platform over IIS to use SSL. There are several parts to this:
  1. Get an SSL certificate
  2. Configure an SSL certificate in IIS
  3. Configure applications to use HTTPS

Get an SSL certificate

To get an SSL Certificate you can purchase one (from a certification authority), ask the company where you are developing if they have a Certification Authority that can provision one for the server (typically the case for non-productive environments) or you can even create a self-issued certificate using a tool by Microsoft called SelfSSL.

To create a certificate using SelfSSL, you need to download the IIS 6.0 Resource Kit Tools from the following URL:

After installing it, simply use the SelfSSL tool to create the certificate. For additional information, refer to this web site:

Configure an SSL certificate in IIS

After you have obtained the certificate, you need to install it in IIS. If you used SelfSSL, you can skip this step, since SelfSSL does this for you.
To install the certificate in IIS do the following:
  1. Open IIS Manager;
  2. Navigate to Web Sites, choose the web site where you want to install the certificate, right-click it and choose Properties;
  3. In the Directory Security tab, press Server Certificates... and follow the tutorial.

Configure applications to use HTTPS

After doing the above steps, you can already access applications using HTTPS. To force redirection of all accesses from HTTP to HTTPS, you need to enable that in the eSpace Flows properties (in Service Studio). For more information, please check the following help topic: .
Please feel free to add more information to this topic!

I think in few months we will implement https so this post is very usefull! I'm starting to investigate, and any questions I'll come back here. Thank you.

Hi Carolina

If you do find more useful information, feel free to post it here. I myself would like to add a minor aspect: by default, IIS6 will only bind the localhost IP address ( to the HTTPS traffic (port 443).

After installing the certificate, you might get an error "unable to connect" in your browser. If you do, see what IP addresses are mapped to SSL:
  • In IIS Manager, choose the appropriate web site under Machine \ Web Sites. Right-click it and choose Properties;
  • Choose the Web Site tab
  • Click the Advanced button in the Web Site Identification group;
  • In the next dialog, in the bottom list, check what is read. If you see, click edit and choose one of the other IP addresses (or simply use All Unassigned).
Just a quick note to let you all know about StartSLL where you can get the basic SSL certificates for free -

For stronger  validation you'd still want to go with another kind of certificate, but this is good to get started. 
Just checking - is this stil the valid procedure for 5.1 and 6.0 platform installations?
Hi Hans

All of these procedures apply to IIS - so they are independent of Agile Platform version.
The only thing to note is that the UI changes from IIS6 to IIS 7.x - particularly, the certificate options are at Server level in the tree, instead of at Site level.

Other than that, everything works just the same. I keep on doing this in version 6.0 successfully.

Hi everyone

I just remembered that I had never written an how-to for Java. The steps are similar conceptually, but since all is done in command-lines, I will write this with an example, with the idea of being a step-by-step nobrainer.
These instructions assume the paths for Agile Platform for Java 5.0, running on JBoss EAP - but should run as well in other versions, simply by adjusting them.

All instructions use keytool - this is a tool that comes with your Java installation. If keytool does not run in your system, specify the full path to your Java installation.
Also, make sure $JBOSS_HOME is defined in your shell - if not, make sure to define it, or replace $JBOSS_HOME with the actual location in the command lines below.

0. Make sure you use the proper keytool (read my answer to this post below)

Run the following commands:
source /etc/sysconfig/outsystems
alias keytool="$JAVA_HOME/bin/keytool"

1. Create a keystore to store your certificate

This is the file from where JBoss will read your certificate. I suggest you save it under $JBOSS_HOME/server/outsystems/conf. The following command line will create the file:

keytool -genkey -alias devserver_key -keypass easypassword123 -validity 3650 -storepass easypassword123 -keystore $JBOSS_HOME/server/outsystems/conf/jboss.keystore

This will create a keystore, with 10 year validity, password easypassword123, and store the file in $JBOSS_HOME/server/outsystems/conf/jboss.keystore.
After typing the command, you will be asked a series of questions about your organization - don't worry, those are kept in the file.

You can confirm successfull creation of the keystore with the following command:

keytool -list -keystore $JBOSS_HOME/server/outsystems/conf/jboss.keystore

2. Get an SSL certificate

For this you have 2 options: generate your own certificate, or request one from your organization's CA.

2.1. To issue your own certificate (self-signed certificate), use this command-line:

keytool -export -alias devserver_key -keypass easypassword123 -file /tmp/devserver_cert.crt -keystore $JBOSS_HOME/server/outsystems/conf/jboss.keystore

This creates file /tmp/devserver_cert.crt with your certificate, to be imported later on.

2.2. To create a certificate request to send to your organization's CA, use this command-line:

keytool -certreq -alias devserver_key -file /tmp/certreq.txt -keypass easypassword123 -keystore $JBOSS_HOME/server/outsystems/conf/jboss.keystore

This creates file /tmp/certreq.txt that you must send to your organization's CA to obtain a certificate.

3. Import the certificate

After you have the file (let's assume /tmp/devserver_cert.crt) importing is done with the following command:

keytool -import -alias devserver_cert -keypass easypassword123 -file /tmp/devserver_cert.crt -keystore $JBOSS_HOME/server/outsystems/conf/jboss.keystore
If you have issued a self-signed certificate, you will be asked if you want to import an entry that already exists. Just accept with yes.

4. Configure JBoss to use the certificate

This requires editing 2 files. Make sure to back them up before editing:
  • $JBOSS_HOME/server/outsystems/run.conf
  • $JBOSS_HOME/server/outsystems/deploy/jbossweb.sar/server.xml
In $JBOSS_HOME/server/outsystems/run.conf you need to add the following, near the end, but before the FI line:

   # Adding trusted store for jboss

In $JBOSS_HOME/server/outsystems/deploy/jbossweb.sar/server.xml, locate the SSL connector part. Uncomment it (remove the <!-- and --> surrounding it) and fix attributes keystoreFile and keystorePass. You should end up wiht something similar to:

      <Connector protocol="HTTP/1.1" SSLEnabled="true"
           port="8443" address="${jboss.bind.address}"
           scheme="https" secure="true" clientAuth="false"
           keystorePass="easypassword123" sslProtocol = "TLS" />


I was eating my own dog food and I ran into a strange issue: jboss would not start after I followed these instructions. Since I had produced them myself I knew that they were correct, but I could not find out what was the problem.

After some digging I determined I was using the wrong keytool. So, on step 2, the wrong keytool produced the following output:

Enter keystore password:

Keystore type: jks
Keystore provider: IBMJCE

Your keystore contains 1 entry

devserver_key, 27-May-2013, keyEntry,
Certificate fingerprint (SHA1): F5:A0:3D:63:CA:A8:56:3B:65:0F:B4:B0:EC:13:98:5F:C6:BF:8F:90
while the correct keytool produced the following output:

Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

devserver_key, 27-May-2013, PrivateKeyEntry,
Certificate fingerprint (MD5): 2D:5D:B7:0C:73:75:9B:BA:85:C5:2A:8D:04:25:91:E8

Notice the subtle difference: one has Keystore provider: SUN and the other IBM.

Make sure to use the keytool from Java, not the one from IBM...


JBoss has it's own quirks when it comes to certificates .... while following this amazing post, I've bumped into a problem setting up SSL on JBoss 5.0.1. After digging into posts and documentation, I've finally identified and fixed the problem with my setup, so I'm sharing it here in case you bump into this problem as well.

I did follow the steps above for setting up SSL on JBoss, with a sligth difference: I already had a PFX private key certificate for my server, so I've imported it in the JKS keystore.

When starting JBoss I've bumped into this error, and SSL port 8443 was not available:

ERROR [org.jboss.kernel.plugins.dependency.AbstractKernelController] (main) Error installing to Start: name=WebServer state=Create
LifecycleException:  Protocol handler initialization failed: Cannot recover key

Apparently, the root cause is a known Tomcat issue when loading the private key: the Keystore password MUST BE the same as the PrivateKey password [1]

To fix this, just change the keystore password, or the private key password, to be the same. In order to do that, you can use on of the commands:

To change the keystore password:

keytool -storepasswd -keystore my.keystore

To change the private key's password:

keytool -keypasswd  -alias <key_name> -keystore my.keystore
Fixing the password and restarting the JBoss solved the problems.



Query related to outsystems
One of the requirement is to set up https port on a non-default port i.e. would like to use port 8543 instead of 8443.  We are making chages on jboss-standalone-conf file. Please let us know if this going to create any issue or it will work seamlessly. 
As per the policy iptables will be disabled.

Well, there isn't any specific configuration that would prevent a different port to work in tandem with the default ports.

However, this means that the users will access the applications using url, so you must allow that port in the iptables firewall to accept connections to it, but there shouldn't require any port redirect rule.

But you should keep the default ports active as well (8080 and 8443).

I've added certificate in server. I've imported webservice in FASt. I've done the same procedure in development and test environmnents. The service is working in development environment but is not working in test environment. See below the error:
" PKIX path building failed: unable to find valid certification path to requested target"
_ My outsystems is
_ The Service is:
_ The imported certificate:
credilink, Mar 28, 2016, trustedCertEntry,
Certificate fingerprint (MD5): 40:CF:43:FC:7D:CC:1F:7E:1E:DD:CF:17:54:3D:32:64

See attached file please.