This documentation is for WSO2 Identity Server 5.7.0 . View documentation for the latest release.

All docs This doc
||
Skip to end of metadata
Go to start of metadata

WSO2 Identity Server by default has one keystore. To mitigate security incidents it is advisable to maintain multiple keystores. For example, if one keystores gets compromised, you can continue with the other keystores that are intact. Mainly, you may maintain three keystores:

  • A keystore to store tokens, which is mentioned in the carbon.xml file.
  • An internal keystore to store internal critical data such as encrypted passwords. 
  • A keystore for Tomcat SSL connection, which is the secondary keystore of the WSO2 Identity Server.

Ideally, the internal keystore should be used for encrypting internal critical data. However, currently, the secondary userstore passwords are encrypted using the primary keystore, which is also used to sign and encrypt tokens. Thus, it is preferable to move the secondary userstore password encryption functionality from the primary keystore to the internal keystore.

After moving the secondary userstore password encryption functionality to the internal keystore, WSO2 Identity Server secondary userstore password encryption tool allows you to decrypt all the existing secondary userstore passwords using the primary keystore and re-encrypt them using the internal keystore.

Let's get started! 

To use this feature, apply the  4656 WUM update for WSO2 Identity Server 5.7.0 using the WSO2 Update Manager (WUM).

To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature in a future version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide.

  • If you are using an NFS-like file system, make sure to isolate the newly-downloaded pack from others.
  • The secondary userstore password encryption tool is a one-time tool. Do not use the WSO2 Identity Server pack that contains this tool in production.

Setting up

  1. Copy the following files and directories from your existing WSO2 Identity Server pack to the respective directories of the newly-downloaded pack.

    File/DirectoryPurpose
    The carbon.xml file in the <IS_HOME>/repository/conf directory.This contains the details about the primary keystore and internal keystore.
    The <IS_HOME>/repository/tenants directory.This contains the tenant's secondary userstore configurations.
    The <IS_HOME>/repository/deployment/server/userstores directory.This contains the super tenant secondary userstore configurations.
    The keystore in the <IS_HOME>/repository/resources/security directory.This is the primary keystore.
    The internal keystore in the <IS_HOME>/repository/security directory.This is the internal keystore.
  2. If you are using a cipher tool, copy the following files in the <IS_HOME>/repository/conf/security directory in your existing WSO2 Identity Server pack to the respective directory of the newly-downloaded pack.

    • cipher-tool.properties

    • cipher-text.properties

    • secret-conf.properties

  3. Open the secret-conf.properties file in an editor and replace the keystore.identity.location element value with the directory path of the current internal keystore.

Re-encrypting the secondary userstore passwords

Follow the steps below to re-encrypt the secondary userstore passwords:

  1. Download the password encryption tool from here and copy the .jar into the <IS_HOME>/repository/components/dropins directory.
  2. To start the modified WSO2 Identity Server pack: 

    1. Navigate to the directory where the modified WSO2 Identity Server pack is located in a command prompt.

    2. Execute the following command. 

      sh wso2server.sh -DreEncryptSecondaryUserStorePassword
  3. Observer the logs in the wso2carbon.log file in the <IS_HOME>/repository/logs directory to monitor the re-encryption of the secondary userstore passwords.

    1. The following appears when the .jar file is being read by the server. 

      "secondary userstore password re-encryption component activated"
    2. The following appears when the migration starts. 

      "secondary userstore password re-encryption started"
    3. The following appears when the migration ends. 

       "secondary userstore password re-encryption ended"
  4. Once the process ends, stop the WSO2 Identity Server.

Copying the userstore to the existing WSO2 Identity Server pack

Follow the steps below to copy the userstore to the existing WSO2 Identity Server pack:

  1. Copy the following directories in the modified WSO2 Identity Server pack into the respective directories of the original pack. 

    As a precautionary measure, take a backup of the existing userstore.

    During the directory copying process, the userstores may get unavailable for a few seconds.

    DirectoryPurpose
    The <IS_HOME>/repository/tenants directoryThis contains the tenant's secondary userstore configurations.
    The <IS_HOME>/repository/deployment/server/userstores directoryThis contains the super tenant secondary userstore configurations.
  • No labels