Configuring Keystores¶

After you have created a new keystore and updated the client-truststore.jks file, you must update a few configuration files in order to make the keystores work. Note that keystores are used for multiple functions in WSO2 Identity Server, which includes authenticating communication over SSL/TLS, encrypting pass words and other confidential information in configuration files etc. Therefore, you must update the specific configuration files with the updated keystore information. For example, you may have separate keystores for the purpose of encrypting passwords in configuration files, and for authenticating communication over SSL/TLS.

The wso2carbon.jks keystore file, which is shipped with WSO2 Identity Server, is used as the default keystore for all functions. However, in a production environment, it is recommended to create new keystores with new keys and certificates.

Configuring the primary keystore¶

• Encrypting/decrypting passwords and other confidential information, which are maintained in various configuration files as well as internal data stores. Note that you also have the option of separating the keystore for encrypting information in internal data stores.
• Signing messages when WSO2 Identity Server communicates with external parties (such SAML, OIDC id_token signing).

Configuring a separate keystore for encrypting data in internal data stores¶

Currently, the primary keystore configured in deployment.toml 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. However, it is sometimes a common requirement to have separate keystores for communicating messages with external parties (such 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.

This feature allows you to create a separate keystore for encrypting data in internal data stores. Follow the instructions given below.

1. Configure the new keystore by adding the following configuration block inside the keystore.internal tag of the deployment.toml file in the <IS_HOME>/repository/conf directory.

   Note

   The values of the properties such as passwords must be changed based on the keystore.

   [keystore.internal]
   file_name = "internal.jks"
   type = "JKS"
   password = "wso2carbon"
   alias = "wso2carbon"
   key_password = "wso2carbon"

Configuring a secondary keystore for SSL connections¶

The default keystore configurations should be updated with the keystore used for certifying SSL connections to WSO2 Identity Server. Given below is the default configuration used internally, which points to the default keystore in your product.

If you need to configure a different keystore for SSL, you may change the values accordingly.

[transport.https.sslHostConfig.certificate.properties]
certificateKeystoreFile = "${carbon.home}/repository/resources/security/$ref{keystore.tls.file_name}",
certificateKeystorePassword = "$ref{keystore.tls.password}"",
certificateKeystoreType = "$ref{keystore.tls.type}",
certificateKeyAlias = "$ref{keystore.tls.alias}",
certificateKeyPassword = "$ref{keystore.tls.key_password}"

The internally used following trust-store configurations can be changed to define a custom trus-store for SSL validations.

[transport.https.sslHostConfig.properties]
truststoreFile="${carbon.home}/repository/resources/security/$ref{truststore.file_name}"
truststorePassword = "$ref{truststore.password}"
truststoreType = "$ref{truststore.type}"