How to setup WSO2 with Let’s Encrypt certificate

Updated on November 26, 2021

Setting up an SSL certificate for WSO2 API Manager is not straightforward, as it requires creating Keystore and adding an SSL certificate to the Keystore. In this article, we will see how to set up WSO2 with Let’s Encrypt certificate.

I assume that you already have the Let’s Encrypt certificate issued and ready to add it to the WSO2 Keystores. If not, go ahead and get one for your domain. In my case, I had the NGINX server front-ending the WSO2 services, hence I had obtained Let’s Encrypt certificate using the certbot program for NGINX webserver.

$ sudo certbot --nginx -d -d

Once the certificate is issued, you will find .pem files under ‘/etc/letsencrypt/live/<domain_name>/‘ folder. Now copy the cert.pem and privkey.pem files to your home directory and follow the below steps.

How to setup WSO2 with Let’s Encrypt certificate?

Step 1: Create PKCS12/PFX file using the cert.pem and privkey.pem files.

We will use the OpenSSL command to export certificates to PKCS12/PFX format and secure it with a strong password when prompted.

$ openssl pkcs12 -export -in cert.pem -inkey privkey.pem -name "letsencrypt" -out letsencrypt.pfx

-name option takes alias as value. The alias can be any name and is required for using it in the WSO2 configuration files later on.

Step 2: Creating Java Keystore

Once you have the PFX file ready, create the Java Keystore using the below command.

$ keytool -importkeystore -srckeystore letsencrypt.pfx -srcstoretype pkcs12 -destkeystore letsencrypt.jks -deststoretype JKS

For the above command to work, you will need to have JDK installed (of course, you already have WSO2 Setup ready). The command keytool would be located inside bin directory of the JDK.

The above command will prompt for the password of both the source Keystore and the destination Keystore.

Step 3: Export the public key from the Java Keystore file.

WSO2 comes with the public trust store (client-truststore.jksand this file needs to be updated with the public key of the JKS file created in step 2.

So let’s go ahead and export the public key from the letsencrypt.jks file. To do that, execute the below command.

$ keytool -export -alias "letsencrypt" -keystore letsencrypt.jks -file letsencrypt.pem

Remember to use the same alias ‘letsencrypt‘ that you had set in step 1.

Step 4: Move letsencrypt.jks and letsencrypt.pem files to the following directory.

$ cp letsencrypt.jks letsencrypt.pem <WSO2_APIM>/repository/resources/security

WSO2_APIM should be replaced with the WSO2 installation directory.

Step 5: Add a public key to the client-truststore.jks

$ cd <WSO2_APIM>/repository/resources/security
$ keytool -import -alias letsencrypt -file letsencrypt.pem -keystore client-truststore.jks -storepass wso2carbon

-storepass takes the value as wso2carbon, which is the default password of the client trust store.

Step 6: Configure the Keystore with WSO2 API Manager.

Configure the WSO2 API Manager with the new Keystore created in step 2. To do that, the following files need to be edited.

Some versions of WSO2 require carbon.xml file to be edited, but the latest versions need only the deployment.toml file to be changed (as the WSO2 managed to simplify the configuration model).

$ vi <WSO2_APIM>/repository/conf/carbon.xml

Lookout for <KeyStore> tag and replace it with the below.

<!-- Keystore file location-->
<!-- Keystore type (JKS/PKCS12 etc.)-->
<!-- Keystore password-->
<Password><Keystore password></Password>
<!-- Private Key alias-->
<!-- Private Key password-->
<KeyPassword><Keystore password></KeyPassword>

Remember to use the same Keystore password and alias set while creating the JKS file in step 2

Change the deployment.toml file with the details of the new Keystore:

$vi <WSO2_APIM>/repository/conf/deployment.toml
file_name = "letsencrypt.jks"
type = "JKS"
password = "<Keystore password>"
alias = "letsencrypt"
key_password = "<Keystore password>"

I suppose modifying deployment.toml should suffice. However, if things do not work straight away, you may edit the below files (probably required for the older versions of WSO2 API Manager).

$ cd <WSO2_APIM>/repository/conf/
$ grep -rn "*.jks"

Edit all the listed files with the relevant Keystore entries.

Now go ahead and restart the WSO2 server.

$ <WSO_APIM>/bin/ --restart

Step 7: Log in to the Carbon interface and check if the new Keystore is added successfully. Click Keystores > List.

WSO2 with Let's Encrypt certificate

Step 8: If you don’t find the Keystore, you can add it manually by clicking Keystores > Add.

That’s it! You will now see the green padlock next to the WSO2 URL in the browser address bar.

Still, have problems? You may need to look at the following references.

Was this article helpful?

Related Articles

Leave a Comment