WSO2 8 minutes

How to patch the open source version of the WSO2 API Manager

Rob Blaauboer
Integration Consultant & WSO2 Trainer
How to patch the open source version of the WSO2 API Manager

How to patch the open source version of the WSO2 API ManagerWSO2 provides a full stack of open source products that allow you to do API management, message mediation and transformation using the WSO2 Enterprise Integrator, WSO2 Identity and Access Management with the WSO2 Identity Server and finally stream processing using the WSO2 Stream Processor.

What is special about WSO2 is that it’s open source. The complete source code can be downloaded from WSO2 GitHub page to be compiled, altered, inspected, and used by you. Like any software every now and then there will be a security bulletin that will warn you about vulnerabilities that have been discovered. In order to be safe this requires you to apply a patch that will close the vulnerability. In most cases these vulnerabilities are not the equivalent of leaving the back door open. A lot of these vulnerabilities are very specific where a situation let’s call it A within environment B and with settings C could allow someone that tries D to gain access. This is not to downplay the severity of a security bulletin. These are things that you need to take seriously.

Open source versus product support

WSO2 can be downloaded and used by anyone without ever incurring cost. However, in this case you do not have the support from WSO2 as far as product patches and security patches using the WSO2 Update Manager (WUM). With this tool and a paid product support account you can establish a baseline of WSO2 products and regularly check if there are any new updates and then creates a new updated version that you can try out and start deploying in your IT landscape. The open source version will be updated on the regular basis, between every three to six months. However, there are some security patches that you can download and apply.

The link to the security patches is a bit hidden, they can be found on WSO2’s website as an overview of all products or as an overview per year. So how does the process work? Actually, it’s quite a simple process, take a look at this flowchart:


There are some differences with WUM. WUM takes all updates and applies them automatically, you cannot choose just one update. Patches can be applied to an existing deployment (restart required).


Patching WSO2 API Manager

The WSO2 API Manager 2.6.0 has had some security updates in 2019. Let’s download one and apply it to the API Manager. 

We are running on a Windows Machine for this blog and installed an out of the box (open source) API Manager on the desktop. Looking at the high-level tree structure of the API Manager we see that the deployment contains a patches folder:

Directory of C:UsersrobDesktopAPIMwso2am-2.6.0repositorycomponents

10/02/2019  10:28 AM    <DIR>          .
10/02/2019  10:28 AM    <DIR>          ..
09/14/2018  08:32 PM    <DIR>          api-key-manager
09/14/2018  08:32 PM    <DIR>          api-publisher
09/14/2018  08:32 PM    <DIR>          api-store
09/14/2018  08:32 PM           247,452 artifacts.xml
09/06/2018  10:22 AM    <DIR>          default
09/06/2018  10:06 AM    <DIR>          dropins
09/06/2018  10:06 AM    <DIR>          extensions
09/14/2018  08:32 PM    <DIR>          features
09/14/2018  08:32 PM    <DIR>          gateway-worker
09/14/2018  08:32 PM    <DIR>          lib
09/14/2018  08:32 PM    <DIR>          p2
09/06/2018  10:06 AM    <DIR>          patches
09/14/2018  08:32 PM    <DIR>          plugins
09/06/2018  10:06 AM    <DIR>          servicepacks
10/02/2019  10:29 AM                 0 test.txt
09/14/2018  08:32 PM    <DIR>          tools
09/14/2018  08:32 PM    <DIR>          traffic-manager


The patch directory can be found under [APIM-HOME]/repository/components.

We download a patch from the WSO2 API Manager page and selected the most recent one.

The ZIP file contains a readme file. This file describes the steps and, in this case, there is a manual step:

Patch ID         : WSO2-CARBON-PATCH-4.4.0-3865
Applies To       : wso2am-2.6.0
Associated JIRA  : N/A

This update provides the ability to perform an intermediate certificate validation for certificate based requests.


NOTE: If you are a WSO2 customer with support subscription, do not apply this patch. Use WSO2 Update Manager (WUM) to receive the same fixes. This patch is applicable to above listed products, only for WSO2 public (free) users.

- Add the following config to the <APIM_home>/repository/conf/identity/identity.xml file inside the <Server > tag.
- To enable the intermediate certificate validation change enable="false" to enable="true" as follows <IntermediateCertValidation enable="true">.
- Add the intermediate certificate CN in the <CertCN> element. Multiple <CertCN> elements can be used for multiple certificates.
- Add exemptable context paths from this validation in the <Context> element. Multiple <Context> elements can be used for multiple contexts.
  <IntermediateCertValidation enable="false">
      <!--Add intermediate certificate CN. Multiple <CertCN> elements can be used for multiple certificates.-->
      <!--Add exemptable context paths. Multiple <Context> elements can be used for multiple contexts.-->
      <!-- <Context>oauth2</Context> -->

- The incoming certificate request CN should be the username of the user and the certificate issuer CN should be in a <CertCN> tag.
- If a context path is required to be exempted from the validation that context can be added with a <Context> tag.

(i)  Shutdown the server, if you have already started.

(ii) Copy the patch3865 to  <CARBON_SERVER>/repository/components/patches/

(iii) Restart the server with :
       Linux/Unix :  sh
       Windows    :  wso2server.bat

So, you can see that we cannot simply apply this update. Let’s open up the API:

[APIM_home]/repository/conf/identity/identity.xml file

I’ve added the configuration to the beginning of the file, since it only states it needs to be inside the <Server> tag:


I copied the patch3865 directory to the patches directory of the APIM Manager.

Now it is time to start the server. Since this is Windows, I am using the wso2server.bat.

Console output

The org.wso2.carbon.server.extensions.PatchInstaller process is starting.

TID: [2019-10-02 11:04:51,336]  INFO {org.wso2.carbon.server.extensions.PatchInstaller} -  Patch changes detected  {org.wso2.carbon.server.extensions.PatchInstaller}
TID: [2019-10-02 11:05:11,153]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Backed up plugins to patch0000 {org.wso2.carbon.server.util.PatchUtils.console}
TID: [2019-10-02 11:05:11,304]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Patch verification started {org.wso2.carbon.server.util.PatchUtils.console}
TID: [2019-10-02 11:05:11,393]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Patch verification successfully completed. {org.wso2.carbon.server.util.PatchUtils.console}

This creates a baseline directorypatch0000 that allows patch rollback.


The API Manager continues to load and when you see the Management URL displayed on the console:

TID: [-1234] [] [2019-10-02 11:12:34,320]  INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : {org.wso2.carbon.ui.internal.CarbonUIServiceComponent}

You can start working with it.

Removing the patch

If we remove the patch from the directory and restart the API Manager, the system detects the patch is removed and will reestablish the baseline it created. However, the manual change is still intact.

TID: [2019-10-02 11:27:25,452]  INFO {org.wso2.carbon.server.extensions.PatchInstaller} -  Patch changes detected  {org.wso2.carbon.server.extensions.PatchInstaller}

TID: [2019-10-02 11:27:43,962]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Patch verification started {org.wso2.carbon.server.util.PatchUtils.console}

TID: [2019-10-02 11:27:43,967]  INFO {org.wso2.carbon.server.util.PatchUtils.console} -  Patch verification successfully completed. {org.wso2.carbon.server.util.PatchUtils.console}


Keeping your open source versions of WSO2 up to date as far as security patches go requires attention. It is a vital element of keeping your products as safe as possible. Of course, this new version needs to be tested as well, typically on a test or acceptance environment before changing the production environment as well. If you have a product support account this procedure is not for you. You would typically use WSO2 Update Manager updates to create a new version of all patches security and product patches to push to your environment after configuration and testing of course.

Need help or more information?

If you don’t want to wait for public patches or releases, and want new patches instantly, then a product support account might be of interest for you. Yenlo can help you with various other versions of support as well. Read more about our support services or contact us for more information.