Skip to Main Content

Deciphering datasources in WSO2

Creating datasources from the console of WSO2 Carbon is a simple task and if we work with the WSO2 family of products you may find it a trivial task.

In this article, we want to show you some of the magic that happens behind the scenes.

When the process of creating a new datasource is completed, it is automatically encrypted. To encrypt this information use the certificates indicated in the file carbon.xml.

Now, what happens if the certificates change?

Well, all the datasources that we have created, will remain unreadable, because the new certificate can not decode the content, thus losing the information contained in the configuration files of the datasources.

In this article we will talk about the possible solutions that there are to losing the datasources that have been created, as well as how to configure them.

1. What are datasources?

The datasources are the data sources of the database connections. That is, certain credentials are defined as driver, user, password, and connection chain, in order to store them for later use.

2. How to create a datasource?

In order to create a datasource we must log in to the WSO2 console (/carbon). In the menu on the left, click Configure > Datasources and then add Datasource

By default, when we start a Enterprise Integrator, we will have 3 predefined datasources (IN_MEMORY_SAMPLE_DS, ECHO_SAMPLE_DS and WSO2_CARBON_DB), and we can visualize it, clicking on View.

When we create a datasource, as we can see in the following image, we must define a series of required fields:

  • Datasource Type: is the type, by default Database Relations is used.
  • Name: is the unique name we will give to the connection string.
  • Datasource Provider: is the provider of the data source.
  • Database Engine: is the database engine that will be used.
  • Driver: internal driver that will be used for the connection to the database.
  • URL: connection to the database.
  • User Name: user of the connection chain.
  • Password: user’s password.

After defining these parameters, we will be able to try a connection test, and if everything goes well, we will save and have already created our first datasource.

 3. Problems with certificate changes

One of the main problems that we can find with the datasources, is at the time of generating a new certificate when the datasources have already been created. When we create a datasource from the WSO2 console, it becomes encrypted with the current wso2carbon.jks certificate. When changing the certificate, we will find that the datasource we have created is not there, in addition to the log, and will show ERROR.

[XXXX-XX-XX XX:XX:XX,XXX] [EI-Core] ERROR - DataSourceRepository Error in updating data source 
[remove:false] at path '/repository/components/org.wso2.carbon.ndatasource/WSO2_Datasource': 
Error in updating data source 'WSO2_Datasource' from registry [remove:false]: Error in secure 
load of data source meta info: An error occurred while decrypting data.

org.wso2.carbon.ndatasource.common.DataSourceException: Error in updating data source 
'WSO2_Datasource' from registry [remove:false]: Error in secure load of data source meta 
info: An error occurred while decrypting data.

As we can see, it gives us an error when loading the data from the datasource we have created, and when we access the WSO2 console, the datasource will not appear.

4. How to solve the problem with datasources: Solutions

In this section we will talk about the possible solutions that we can use to solve the problem with the datasources and the advantages and disadvantages of each one of them:

  • Definition in master-datasources.xml
  • Generation of exclusive certificates.
  • Recreation of the datasources.

4.1. Definition in master-datasources.xml

The first solution that we are going to see, is the creation of the datasource, defining it in the configuration file of master-datasources.xml, located in {carbon.home}/conf/datasource/. In this configuration file we will already find a datasource WSO2_CARBON_DB created.

To create a datasource, we will have to create a new field, in which we will define the datasource that we have created previously from the WSO2 Console, with the same fields.

            <description>New datasource</description>
            <definition type="RDBMS">
                    <validationQuery>SELECT 1</validationQuery>

Once defined, we start up the product, and when we access the datasource, we will see that the datasource has been created:

datasource created

As we can see, the datasource has been created for us, and even if we change the certificate there will be no problems when it comes to losing the datasource.

Now let’s analyze the advantages and disadvantages of this configuration.

  • Advantages:
    • It is not necessary to recreate the datasource every time you change your certificate.
  • Disadvantages:
    • Readable database password, security problems.
    • We can not edit the datasources and for them we must do it from the configuration file and we must restart the product

This is the first solution that we will see, an alternative for the password is not clear, is to implement it with Secure Vault, so that the password becomes encrypted.

4.2. Generation of exclusive certificates.

The second alternative is the creation of a new exclusive certificate for the internal encryption of WSO2. By creating a certificate that will have exclusive internal use, we will be able to give it a longer durability, so that we will not be changing the certificate.

The configuration that we must do is the following:

  1. Generation of a certificate, we can store it in new certificate within wso2carbon.jks or create a new store for this new certificate.
  2. Edit the file carbon.xml, in {carbon.home}/conf/, go to the InternalKeyStore section, and edit the configuration, specifying our new certificate:
  • Location: location of the new key storage.
  • Password: password of the key storage.
  • KeyAlias: is the name we have given to the new certificate.
  • KeysPasswrod: is the password of the new alias created.
    <!-- Keystore file location-->
    <!-- Keystore type (JKS/PKCS12 etc.)-->
    <!-- Keystore password-->
    <!-- Private Key alias-->
    <!-- Private Key password-->

Once this configuration is applied, we can regenerate the wso2carbon certificate, which is located in wso2carbon.jks, since we will not use it for internal encryption.

This configuration we have done, leads to all internal encryption of WSO2, is done by this new certificate, it is not necessary to save the certificate in a new keystore, we can also store it in the wso2carbon.jks itself

Now let’s analyze the advantages and disadvantages of this configuration.

  • Advantages:
    • The datasource is now encrypted with a certificate that will expire according to the years we have indicated on the new certificate.
    • Datasources are now encrypted.
  • Disadvantages:
    • The certificate will have to be changed when it expires, but unlike the first case, the time of expiation is indicated by us.

4.3. Recreation of the datasources

The third and last alternative is the recreation of the datasources that have been lost when the certificate was changed.

Now let’s analyze the advantages and disadvantages of this configuration.

  • Advantages:
    • The datasources are encrypted.
  • Disadvantages:
    • Every time you change your certificate, it will mean recreating the datasources again.

5. Conclusion

In conclusion, we can appreciate that the configuration of datasources is a delicate subject, and each configuration option available has its advantages and disadvantages.

When deciding which is the best, we could choose the second option, since it allows us to change the certificate annually without the need to recreate the datasources.

On the other hand, another option would be to choose the first option, define the datasources in a configuration file, and then use the Secure Vault, to encrypt it.

In short, the datasources are a subject that requires care, because of the internal encryption that we use, in addition to the expiry of the certificate we are using for WSO2, so before starting the service, we must decide which of these options to choose, in order to prevent problems when the certificate expires and we need to recreate a new one.