WSO2 products can be downloaded from the WSO2 website, installed in a matter of seconds after which you can try out the software. No fees, no contracts and …. no lawyers.
What you’ll find when you start up any WSO2 product is that the browser will balk on the certificate that is used to encrypt the connection. This is a so called self-signed certificate and is deemed to be less secure then one from a Certificate authority.
How do Certificates work?
Without going into too much detail, certificates work using a trust mechanism. Certificates are issued by a so called Certificate Authority like the companies Comodo or Symantec. A certificate issued by them should be trusted since the trust relationship with CA’s is beyond discussion. The certificate issued guarantees that the site is indeed who it claims to be.
Certificates in this sense are used to encrypt the secure https traffic to and from your WSO2 products. To set up HTTPS you will need a valid certificate to enable the WSO2 product to encrypt the connection.
For this tutorial I've used a wildcard certificate signed by a (trusted) Certificate authority. This certificate will be used instead of the self-signed WSO2 certificates in the keystore . These are great for testing purposes but in a production environment you will of course want to change this keystore with a different one. And you also get rid of these pesky messages about security inherent with self signed certificates.
Mind you that certificates cost money since a service (in this case trust) is offered. There are some organizations that offer free 90 days certificates if you want to try it out and not directly shell out money for a full certificate. Keep in mind that you will need to offer proof of ownership or control over the website that you want the certificate for. For more information we direct you to the internet.
We assume that you have a working WSO2 product, e.g. an WSO2 ESB. Before we start we will need to collect a few things.
- A valid certificate, usually acquired from your company’s system administrator
- The Certificate private key, usually acquired from your company’s system administrator
- The intermediary and root certificates provided by the trust company who signed the valid certificate.These can be downloaded from the company’s website (In this case I've used a comodo certificate https://support.comodo.com/index.php?/Default/Knowledgebase/List/Index/108/sha-2)
To find out which ones you need you will have to open the valid certificate and open the below window.
This is the tab you need to see the certificate chain, you can see that the clients wildcard certificate is the one currently selected.
Above the current certificate there are two other certificates listed, these are the intermediary certificates within the certificate chain.
When selected they will show the names of the intermediary certificates you’ll need:
- Comodo RSA Organization Validation Secure Server ca certificate
- Comodo RSA Certification Authority certificateIn case of the root certificate this one is not listed and is most likely already embedded in the system you're using, if you're not sure it shouldn’t break anything to add this one too.
- Add Trust External ca root certificate
Here you can see the signed wildcard certificate (*.domain.nl) and the two intermediary certificates in the chain. When you open the intermediaries you can find the exact name of the certificate you will need to find.
So the intermediaries we need are the COMODO RSA Certification authority cert and the Comodo Rsa Organization Validation Secure Server ca.
Creating and configuring a new keystore
Creating a new keystore with a trusted key takes the following steps:
- Creating a PKCS12/PFX file
- Creating the Keystore
- Export a public key from the JKS file
- Adding the keystore and public key to the product
- Adding the public key to the Public truststore
- Configuring the product to use the new keystore
- Adding the intermediary certificates to the keystore.
- Done!
We will describe these steps in more detail below.
Before we can create a keystore we will have to create a .pfx file with the collected certificates and key.
Step 1 - Creating a PKCS12/PFX File
First you must export certificates to the PKCS12/PFX format. Use strong passwords whenever required.
We used an openssl prompt for this part of the process, you can open it in command line by typing "openssl".
To generate a correct PFX file you will need to use the following command, if correctly executed it will ask for a password twice, don't forget whatever you decide to use as a password as you will need it later!
| openssl pkcs12 -export -in (customer valid certificate file).crt -inkey (customer valid certficate file private key).key -name "alias for your pfx" -certfile (additional certificate intermediary1) -out (pfx keystore name).pfx |
This will result in a valid pfx file.
Step 2 - Creating the keystore
Now we will Convert the PKCS12/PFX file to a Java keystore using the following command:
Now we will Convert the PKCS12/PFX file to a Java keystore using the following command:
| keytool -importkeystore -srckeystore (pkcs12/pfx file name).pfx -srcstoretype pkcs12 -destkeystore (Keystore file name).jks -deststoretype JKS |
For this command you will need a valid JDK installation, keytool comes with the JDK. It can be found in the /bin directory of the JDK.
If your command line cannot find keytool when you try to use it your PATH environment variable might not be set. Edit the PATH environment variable on your computer and add the location of the jdk bin folder to it. Once this is configured you should be able to use keytool from any directory on the computer. Once the command is executed you will have a valid Keystore!
Step 3 - Export a public key from your JKS file
Aside from the keystore there is a "Public truststore" inside the WSO2 product, we will need to add the public key of our keystore to this truststore.
Since we don't have a public key yet we will have to export this one from the Keystore.
| keytool -export -alias "certificate alias" -keystore (mykeystore.jks) -file (public key name).pem |
Make sure the alias is the same as the one you used for your pfx file.
Step 4 - Adding the keystore and public key to the product
Before we can configure the keystore and public key for WSO2 product we have to place the files inside the /repository/resources/security folder.
Once the files are in position we can configure the product to use our newly created files.
Step 4.1 - Adding the public key to the Public truststore
The public truststore in the /repository/resources/security/ folder is called "client-truststore.jks", we will add the public key to this truststore with the below command.
| keytool -import -alias (certificate alias) -file (public key name).pem -keystore client-truststore.jks -storepass wso2carbon |
Note: the default password for the client-truststore.jks is "wso2carbon".
Step 4.2 - Configuring the product to use the new keystore
Inside each WSO2 product there are many different files that refer to the default keystore, if you want to replace it with the new one you will have to change the entry in all of the relevant places.
The most important file to configure is the primary keystore entry in the /repository/conf/carbon.xml file, if you don't want to edit this entry you can also manually add an extra keystore entry.
The entry will look like this:
wso2carbon.jks
#####
Change it to something like this:
#####################################################################
Change it to something like this:
|
Note that the password is stored in plaintext. If you want to store a more secure placeholder with an encrypted value, use SecureVault. For more information on this subject I will refer you to my colleague’s blog: https://www.yenlo.com/blog/wso2torial-encrypt-passwords-using-secure-vault
The easiest way to find all the other entries of the default keystore is to use the "grep -nr ".jks" in the /repository/conf/ folder, this will list all the relevant entries and their files.
You will get something like below. Now you can open each of the files you find and change the relevant keystore entries.
| /axis2/axis2.xml:260: ./axis2/axis2.xml:431: ./carbon.xml:316: ./carbon.xml:332: ./identity.xml:180: ./security/secret-conf.properties:21:#keystore.identity.location=repository/resources/security/wso2carbon.jks |
Once you've replaced these entries, restart the server.
Step 5 - Adding the intermediary certificates to the keystore.
Now that we've correctly configured the keystore we can look it up in the carbon console.
Under the Main tab there is a button called "Keystores" here you would originally see the "wso2carbon.jks" now you should see your own keystore.
If this is not the case, make sure you correctly configured the keystore entry in the carbon.xml.
It should look like this with your keystore name listed.
Now we just need to add the intermediary and (optionally) the root certificate to the keystore.
Click the Import cert button and do this for the intermediary certificates. It will end up looking something like this:
Step 6 - Done!
Restart the server and go to the carbon console, in your browser next to your URL it will show whether the connection is valid HTTPS.
If it still shows the website as unsafe in your browser you can get extra details about the problem by clicking on the notification in your browser.
If you can't find enough information through there you can also try one of many SSL checker web tools like https://www.ssllabs.com/ssltest/.
Note: Don't forget that if you go straight to the IP address in your browser and not through a DNS address it will also say that the HTTPS is not correct. This is because in our case the certificate used was for *.domain.nl so the browser only rates the website as secure if you go through a variation of *.domain.nl.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
Tutorial Credit: https://www.yenlo.com/blog/setting-up-wso2-with-a-valid-certificate
No comments:
Post a Comment