Adding WSO2 public certificate to Java Certificate Store

When using WSO2 Identity Server to provide OpenID Connect based SSO, you may encounter the following error, PKIX path building failed: unable to find valid certification path to requested target

This is commonly observed when trying to generate an access token from the WSO2 Identity Server. This error occurs due to the fact that the public key of the WSO2 Identity Server doesnt exist in the Java certificate store. You can follow the steps given below to avoid this error.

1. Generate a public key from the WSO2 carbon keystore – To do this you would need to access the following folder. <IS HOME>\repository\resources\security. Once inside the folder, run the below command to export the public certificate.

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2PubCert.cer

you will be prompted to enter the password, the default password is ‘wso2carbon’. If this command is executed correctly you will see a newly created PubCert.cer certificate file in this folder.

2. Import the certificate to the Java certificate store -To import the certificate navigate to the following folder. <JavaHome>/jre/lib/security. Open a console from here and run the following command to get the number of certificates that are currently in the certificate store.

keytool -list -keystore cacerts

Default Password : ‘changeit’

This will list down all the certificates in the store. If you scroll up you would see the number of certificates in the store.

Lets import the WSO2 public certificate to this certificate store. You can do this by running the following command. For Windows users please make sure that your command prompt is running as administrator.

keytool -import -keystore cacerts -file <Certificate Path>\wso2PubCert.cer

Default Password : ‘changeit’

You will get the confirmation that the certificate is successfully imported, you can validate this by listing the certificates using the list certificates command given above.

You should now be able to access the OAuth 2.0 endpoint of the WSO2 Identity Server and generate an access token.

Accessing an OAuth 2.0 secured API in WSO2 API Manager with a SAML 2 Bearer token

One of the key feature provided by the WSO2 API Manager is its ability to secure the exposed API’s using OAuth 2.0 tokens. WSO2 API Manager supports all 4 grant types of OAuth 2.0 specification. OAuth 2.0 is a specification that is widely adapted especially in the mobile application space. However we still find the need for API’s to be accessed by web applications that still use standard username-password based credentials. Many of these web applications use SAML 2 based authentication and would prefer to use the same SAML assertion to access OAuth 2.0 protected API’s. This type of a scenario is supported by WSO2 API Manager which supports a SAML 2 Bearer grant type that can allow an application to exchange the SAML 2 bearer token with an OAuth 2.0 access token. This token exchange is transparent to the end-user hence it will not impact their user experience. This token exchange process can be depicted in the diagram below.diag

Step 1 – Application receives a SAML assertion from the SAML IdP after authenticating the user.

Step 2 – When the Application needs to invoke an API, it sends the SAML assertion to the token endpoint of the API Manager. SAML assertion is Base 64 encoded and sent as a SAML Bearer grant. Application will also need to send the consumer key and consumer secret which has to be obtained when subscribing to this API.

Step 3– API Manager will validate the request and exchange the SAML token with an OAuth 2.0 access token and a refresh token.

Step 4 – Application Access the API with the OAuth 2.0 access token (generated in the above step). This OAuth 2.0 token should be included as the Authorization header when invoking API’s via the API Manager.

The objective of this blog is to introduce the concept of token exchange, you would find detailed instructions on how to set this up in the following API Manager document.

WSO2 API Manager for message mediation

Even though the API Manager’s primary focus is to manage and expose API’s to different API consumers, it a common scenario to have the API Manager to perform some level of message mediation for both message requests and responses. The gateway component of the WSO2 API Manager is essentially a lightweight ESB that can perform almost all mediation activities that can be done by a regular ESB.

Newer releases of WSO2 API Manager provides the ability to attach mediation sequence to the request, response or the fault sequence of an API. The sequence gets executed when a request is made or a response is received to a request. Let’s look at how to add a message mediation to an API.

  1. Firstly you need to create message mediation sequence. Lets create the following sequence that would add a header to an out-going message. Save this sequence as setHeader.xml`
<sequence xmlns=""  name="SetHeader">
<header name="TempHeader" value="Test Header Value" action=set/>
  1. Log-in to the management console of the API Manager. You can access the management console via the following URL https://{IP}:9443/carbon You will find multiple options in the left hand navigation bar, select the ‘Browse’ icon in the Resources tab as shown below to access the internal registry.


  1. Once inside the registry, navigate into ‘/_system/governance/apimgt/customsequences/in/’ folder in the registry and add the newly created setHeader.xml. Similarly if you have any sequence that needs to be added to the out sequence or the fault sequence you can do so by going into each of these folders under ‘customsequences’ folder. You can upload a sequence by selecting ‘Add Resource’ button and upload this file as shown below.


  1. Once this is done, you can go to the publisher of the API Manager, and create a new API. Enter the required information in ‘Design’ and ‘Implement’ tabs and move to the ‘Manage’ tab. In the ‘Manage’ tab tick on the ‘message mediation policies’ and select the ‘SetHeader’ from the inflow dropdown as shown below. Once this is done Save & Publish the API to the API Store.


  1. You can now invoke the API from the API Store. You will see that the new header called ‘TempHeader’ is added to the message request before the backend API is invoked.

Throttling of API’s using WSO2 API Manager

When exposing API’s for consumption it is of paramount importance that the API access is controlled so that service consumers are not able to misuse these exposed API’s. WSO2 API Manager provides the capability to throttle API’s that are exposed via the API Manager. API Manager allows throttling at multiple levels.

1. Application Level throttling
2. API Level throttling
3. Resource level throttling

To understand the above levels of throttling we need to first understand the concept of API’s and applications in the API Manager.

An application inside the WSO2 API Manager is a logical group to which API’s are subscribed into. For example if you take a Weather Application, this will have 2 API calls. First one would make a call to a Location API to get GPS coordinates of the current location, after which a second API call would be made to a Weather API to get weather information of the current coordinates.So in this case the Application within the API Manager would be the ‘Weather Application’ and both the Location API and the Weather API would be subscribed under this application. This can be illustrated in the diagram below

Lets related the above diagram to different throttling tiers that are available with the API Manager, this can be illustrated as below.


1. Application Level Throttling

Each application can have a throttling policy defined that would limit the aggregated number of API calls that can be made to API’s subscribed under that application. In this case we can throttle the number of API calls made from the weather application irrespective of whether they are calling the Location or the Weather API. A throttling tier can be associated to an application from API Store. This can be done by navigating to ‘My application’ tab as shown below.


2. API Level Throttling
Each API can be associated with a throttling tier. When an API is subscribed the subscriber would have a choice to choose which throttling plan to subscribe. This is shown in the screenshot below


The choice of throttling plans that needs to be associated to an API can be selected at the point of API creation. Given below is a screenshot which shows how to add a throttling plan to an API.


3. Resource Level Throttling
WSO2 API Manager also allows you to define throttling tiers for each resource within an API. This allows you to have more control on how each resource is throttled in a given API. In the above example the Weather API would have two resources ‘getWeather’ and ‘getFullWeather’ which can have two different throttling tiers. A throttling tier can be associated to a resource at the point of API creation. This is shown in the screenshot below.


If you wondering on how to set these tiers that you see on the screen, you can refer to the following API Manager documentation [1]


WSO2 Registry Explained!

What is a Registry?

Registry in essence is a storage space in which data and configuration relating to a product can be persisted and referred from. The Registry uses a database for data persistence and it can be mounted to any type of Relational DB. Registry is a Carbon Kernel component hence all WSO2 products have a registry space built into the product.

Registry Spaces

Each registry can be divided into 3 spaces.

  1. Local Registry space

Local Registry space is specific to each WSO2 product and is not shared with other products in the deployment. Local registry stores artifacts that are local to that particular server.

  1. Config Registry space

Config Registry is shared between similar products in the cluster. For example all ESB nodes in the cluster would share a single Config Registry space. All product specific artifacts are stored inside this Registry.

  1. Governance Registry space

The governance registry space is a common space that is shared by all WSO2 products in the deployment. This registry space will store all artifacts that are common to all WSO2 products in the deployment. Governance Registry space should not be confused with the WSO2 Governance Registry.

Registry spaces are conceptual and all 3 spaces can mount to a single location. In the vanilla distribution of a WSO2 product, all these 3 spaces are pointed to the local H2 Database.

What is Registry mounting?

Registry mounting refers to a concept of linking the registry to a database. By Default the registry is mounted to the local H2 Database. It is possible to mount different Registry spaces of the same registry to different databases. For example the Local Registry space can be mounted to the H2 database whilst other spaces can be mounted to a remote database. In a production system it is recommend to mount the Config and Governance spaces of the Registry to a remote database.

Governance Registry Space != Governance Registry

Even though they sound similar, the Governance Registry space is not the same as WSO2 Governance Registry Product. Governance Registry simply refers to a registry space that is common to all WSO2 Products. Whereas the WSO2 Governance Registry product is a registry and a repository to store any type of data or metadata. It provides a rich set of features including SOA governance, lifecycle management, and a strong framework for governing anything.

What is remote Registry mounting

In a production deployment it is recommended to mount the Config and Governance space of the Registry to a remote database. This allows these registry spaces to be shared by the other products in the cluster or in the deployment. For example if you mount the Config space in a remote location all similar products in the cluster can use this remote location, where as if you mount the Governance space in a remote location all the WSO2 products in the deployment can use this remote Governance space.

How WSO2 Governance Registry comes into the picture

WSO2 governance registry can be used to manage the registry spaces of WSO2 products. This provides the capability to incorporate registry features to the registry spaces so that the registry can be managed better from a central point.

Implementing a Data Diode with WSO2 ESB

Data Diode is the data pattern that ensures unidirectional data flow between networks and is useful for enterprises who want to connect networks with different security levels. This patterns will be used to ensure that data is only allowed to flow from the low side (low security network) to high side (high security network). This type of a dataflow, in most cases is controlled at the network level, but if a need arise to control this at a data layer this EIP pattern can be used. Let’s look at the image below


As you can see in this diagram, two WSO2 ESB’s reside on two sides of the network. The ESB in the unsecure network is connected to different applications in the unsecured network. It also connects to the ESB in the secure network and the communication is encrypted (if needed integrity and non-repudiation can also be ensured) using WS-Security.

The ESB in the secure network has all its outbound transports (except JMS transport) removed, hence the ESB can only receive messages from the unsecured network whilst it can only send out messages to a pre-designated message queue.

Consumers of this data can listen to the queue and pull messages from the queue once they are queued.

Setting up the ESB to work in this pattern would require the execution of following steps

  1. Remove/Disable all out-going transports except the JMS and local transport. This can be done by disabling/removing all transportSenders from the following configuration file.

The transportSender section of the configuration file should only have the two transports below.

<transportSender name="local" class="org.wso2.carbon.core.transports.local.CarbonLocalTransportSender"/>
<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/>
  1. Configure a message queue, you can configure a JMS or AMQP based message queue. More instruction on how to configure the queue can be found in the following link

  1. Create a Proxy service as given below.

  1. Finally Secure the proxy service, you can follow the instructions below to secure a proxy service using the WSO2 ESB.

You can now try to invoke the DiodeProxy from the unsecure network, you will notice that no response would be received back from this proxy. Even if a new proxy service is created in the secured ESB, the communication would still be blocked by the ESB as all but the JMS is blocked in the secured ESB.

Creating your own profile in the API Manager

API Manager is shipped with the capability that allows the product to be started in a specific profile(for example a Gateway profile or a Key Manager profile). When the API Manager is started in a specific profile only the features specific to that profile and the common features as started with the server. For example if you start the API Manager with the Key Manager profile, only the features required for the key manager server and the set of features common to all profiles are started.

The feature bundling capability is provided using the underline OSGi architecture of the WSO2 API Manager. The API Manager is currently shipped with some server profiles which are documented in the following URL[1]. This blog looks at how we can create our own profile within the API Manager.

Features relating to a given API Manager profile can be found in the following location

\repository\components\\configuration\org.eclipse.equinox.simpleconfigurator\ file contains the features that needs to be started with the given profile.

Lets create a new profile called ‘api-km-pub’. This profile will allow the API Manager to work as a Key Manager and a Publisher. For this profile I will merge the two files in ‘api-key-manager’ and ‘api-km-pub’. The merged bundle file should be placed in the following directory structure below


You can now start the API Manager server with the newly created profile by executing the following command

/bin/ -Dprofile=api-km-pub