

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.

Note

CA-signed certificates are recommended for this keystore because it is used for communicating with external parties.
You can copy the new file to the <MI_HOME>/repository/resources/security/ folder.

Note

You can use a custom location only if you are using an updated version of the Micro Integrator. Read the below instructions for details.
Open the deployment.toml file and add the relevant configurations as described below.
- If you are using an updated Micro Integrator, use the following configuration and change the values.
  
  Info
  
  WSO2 released a product update on 17/09/2020, which requires that you provide the full path to your keystore file in your configuration as shown below. If you do not already have this update, you can get the latest updates now.
```
[keystore.primary]
file_name="repository/resources/security/wso2carbon.jks"
type="JKS"
password="wso2carbon"
alias="wso2carbon"
key_password="wso2carbon"
```
- If you are using a Micro Integrator without updates, use the following configuration and change the values.
  
  Info
  
  Be sure to replace [keystore.primary] with [keystore.tls] and specify the keystore name instead of the file path. Also, be sure to store the keystore file in the default <MI_HOME>/repository/resources/security/ folder. Custom keystore locations cannot be used without the product update.
```
[keystore.tls]
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.

Note

CA-signed certificates are recommended for this keystore because it is used for communicating with external parties.
You can copy the new file to the <MI_HOME>/repository/resources/security/ folder.

Note

You can use a custom location only if you are using an updated version of the Micro Integrator. Read the below instructions for details.
Open the deployment.toml file and add the relevant configurations as described below.
- If you are using an updated Micro Integrator, use the following configuration and change the values.
  
  Info
  
  WSO2 released a product update on 17/09/2020, which requires that you provide the full path to your keystore file in your configuration as shown below. If you do not already have this update, you can get the latest updates now.
```
[keystore.internal]
file_name="repository/resources/security/wso2carbon.jks"
type="JKS"
password="wso2carbon"
alias="wso2carbon"
key_password="wso2carbon"
```
- If you are using a Micro Integrator without updates, use the following configuration and change the values.
  
  Info
  
  Be sure to specify the keystore name instead of the file path. Also, be sure to store the keystore file in the default <MI_HOME>/repository/resources/security/ folder. Custom keystore locations cannot be used without the product update.
```
[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 truststore that is shipped with the product, follow the steps given below.

Create a new keystore.

Note

CA-signed certificates are recommended for this keystore because it is used for communicating with external parties.
You can copy the new file to the <MI_HOME>/repository/resources/security/ folder.

Note

You can use a custom location only if you are using an updated version of the Micro Integrator. Read the below instructions for details.
Open the deployment.toml file and add the relevant configurations as described below.
- If you are using an updated Micro Integrator, use the following configuration and change the values.
  
  Info
  
  WSO2 released a product update on 17/09/2020, which requires that you provide the full path to your truststore file in your configuration as shown below. If you do not already have this update, you can get the latest updates now.
```
[truststore]
file_name="repository/resources/security/client-truststore.jks"
type="JKS"
password="wso2carbon"
alias="symmetric.key.value"
algorithm="AES"
```
- If you are using a Micro Integrator without updates, use the following configuration and change the values.
  
  Info
  
  Be sure to specify the truststore name instead of the file path. Also, be sure to store the truststore file in the default <MI_HOME>/repository/resources/security/ folder. Custom locations cannot be used without the product update.
```
[truststore]
file_name="client-truststore.jks"
type="JKS"
password="wso2carbon"
alias="symmetric.key.value"
algorithm="AES"
```
Import the required certificates to the truststore.

Top