

Configuring Keystores for the Micro Integrator¶

Follow the instructions given below to configure keystores for the Micro Integrator.

The default keystore configuration¶

WSO2 Micro Integrator is shipped with a default keystore (wso2carbon.jks) and default trust store client-truststore.jks, which are stored in the MI_HOME/repository/resources/security/ directory.

The default keystore is used for the following requirements:

Encrypting/decrypting passwords and other confidential information, which are maintained in various configuration files as well as internal data stores.

Note

It is recommended to separate the keystore for encrypting information in internal data stores.
Signing messages when the WSO2 product communicates with external parties (such as SAML, OIDC id_token signing).

The default trust store contains the certificates of reputed CAs that can validate the identity of third party systems that communicate with the Micro Integrator. This trust store also contains the self-signed certificate of the default wso2carbon.jks keystore.

Changing the default primary keystore¶

If you want to change the default primary keystore that is shipped with the product, follow the steps given below.

Create a new keystore and copy it to the MI_HOME/repository/security/ directory.

Note

CA-signed certificates are recommended for this keystore because it is used for communicating with external parties.
Open the deployment.toml file, add the following config section, and update the parameter values for the newly-created keystore.
```
[keystore.primary]
file_name="wso2carbon.jks"
type="JKS"
password="wso2carbon"
alias="wso2carbon"
key_password="wso2carbon"
```
Find more details about keystore parameters.
Import the required CA-signed certificates to the key store.

Separating the internal keystore¶

By default, the primary keystore is used for internal data encryption (encrypting data in internal data stores and configuration files) as well as for signing messages that are communicated with external parties.

Info

Why separate the internal keystore?

It is sometimes a common requirement to have separate keystores for communicating messages with external parties (such as SAML, OIDC id_token signing) and for encrypting information in internal data stores. This is because, for the first scenario of signing messages, the keystore certificates need to be frequently renewed. However, for encrypting information in internal data stores, the keystore certificates should not be changed frequently because the data that is already encrypted will become unusable every time the certificate changes.

Follow the steps given below to separate the keystore that is used for encrypting data in internal data stores.

Create a new keystore and copy it to the MI_HOME/repository/security/ directory.

Note

You do not require CA-signed certificates for this keystore because it will not be used for communicating with external parties.
Open the deployment.toml file, and update the parameter values for the newly-created internal keystore.
```
[keystore.internal]
file_name="wso2carbon.jks"
type="JKS"
password="wso2carbon"
alias="wso2carbon"
key_password="wso2carbon"
```
Find more details about internal keystore parameters.

Optional: Changing the default truststore¶

If you want to change the default trust store that is shipped with the product, follow the steps given below.

Create a new keystore and copy it to the MI_HOME/repository/security/ directory.

Note

You do not require CA-signed certificates for this keystore.
Open the deployment.toml file, add the following config section and update the values for the newly-created trust store.
```
[truststore]
file_name="wso2carbon.jks"
type="JKS"
password="wso2carbon"
alias="symmetric.key.value"
algorithm=""
```
Import the required certificates to the trust store.

Top