/
Removing References to Deleted User Identities

This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Removing References to Deleted User Identities

May 24, 2018

A key requirement outlined in the General Data Protection Regulation (GDPR) is the right of the data subject to be forgotten, which gives individuals the right to request an organisation to remove their personal information from a system.

To comply with this requirement, WSO2 Identity Server (WSO2 IS) supports removing references to personally identifiable information (PII) of a user when a user is deleted from the system.

You can use the Identity Anonymization tool packaged with WSO2 IS to remove references to a user’s PII that can generally be stored in metadata database tables, access logs, audit logs as well as any other log files in WSO2 IS.

Before you begin, keep the following in mind,

  • The purpose of this tool is to remove references to personally identifiable information of a user that can persist in RDBMS tables and log files of WSO2 IS after the user is deleted. Therefore, it is the responsibility of the WSO2 IS system administrator of an organization to run the tool appropriately when required. For example, the system administrator should not attempt to run the tool to remove references to a user who has not been deleted from the system. Although it is practically possible to run the tool to remove references to a user who has not been deleted from the system, attempting to do so can cause unexpected system errors.

  • This tool is designed to replace all occurrences of a deleted user’s identity with either a randomly generated UUID value, or a pseudonym that you specify when you run the tool. Therefore, running the tool does not mean that all data related to a deleted user is completely removed from the WSO2 IS when the tool is run. What actually happens is that the same pseudonym replaces each record that belongs to a deleted user in order to preserves the connection integrity of user records. Hence, even after removing all references to a deleted user's identity, the system administrator is able to track all events performed by a particular user without having any reference to the user's identity.

The following sections guide you through configuring and running the Identity Anonymization tool in WSO2 IS:

Changing default configurations of the tool 

All configurations related to this tool can be found inside the <IS_HOME>/repository/components/tools/forget-me/conf directory. The default configurations of the tool are set up to search for references of the deleted user from the following file paths:

  • Read Logs: <IS_HOME>/repository/logs

  • Read Data sources: <IS_HOME>/repository/conf/datasources/

  • Default data source name: WSO2_CARBON_DB

  • Log file name regex: wso2carbon.log

For information on changing these configurations, see Configuring the config.json file in the Product Administration Guide. 

Changing the default configuration directory location

You can change the default location of the tool configurations if desired. You may want to do this if you are working with a multi-product environment where you want to manage configurations in a single location for ease of use. Note that this is optional.

To change the default configurations location for the embedded tool, do the following:

  1. Open the forgetme.sh file found inside the <IS_HOME>/bin folder.

  2. The location path is the value given after -d  within the following line. Modify the value after -d to change the location.
    The default location path is $CARBON_HOME/repository/components/tools/forget-me/conf. 

    sh $CARBON_HOME/repository/components/tools/forget-me/bin/forget-me -d $CARBON_HOME/repository/components/tools/forget-me/conf $@

Running the tool in WSO2 IS

This tool is packaged with WSO2 Identity Server by default. Follow the steps below to run the tool:



Note

  • This tool is designed to run in offline mode (i.e., the server should be shut down or run on another machine) to prevent unnecessary load to the server. If you run the tool in online mode (i.e., when the server is running), DB lock situations on the H2 databases may occur.

  • If you configure any JDBC database other than the H2 database provided by default, copy the relevant JDBC driver to the <IS_HOME>/repository/components/tools/forget-me/lib directory.



  1. Open a new terminal window and navigate to the <IS_HOME>/bin directory. 

  2. Execute one of the following commands depending on your operating system:

    • On Linux/Mac OS: ./forgetme.sh -U <username>

    • On Windows: forgetme.bat -U <username>


    Once the tool is run, it creates copies of all log files that are defined via the log-file-name-regex value in the <IS_HOME>/repository/components/tools/forget-me/conf/config.json file, and removes references to a specified deleted user’s identity in those log file copies. You will see that the log file copies are created with the anon-<TIME_STAMP>-<OROGINAL_FILENAME>.log naming convention in the <IS_HOME>/repository/logs directory.

    Once all the references to a deleted user’s identity are removed, the tool generates relevant execution reports in the <IS_HOME>/repository/components/tools/forget-me/conf directory with the Report-<PROCESSOR>-<TIMESTAMP>.txt naming convention.

Running the tool in WSO2 IS Analytics

To use this tool with WSO2 IS Analytics, you can configure and run the tool by following the same steps given in this guide in the <IS_ANALYTICS_HOME> directory (the WSO2 IS analytics installation directory) instead of the <IS_HOME> directory.

Note

Before you run the tool, be sure to start the WSO2 IS Analytics server at least once to generate the required analytics streams.

Running the standalone version of the tool

If you are using multiple WSO2 products and you want to remove references to a particular deleted user from all the products at once, you can use the standalone version of the Identity Anonymization tool.

To remove references to a particular deleted user from multiple WSO2 products at once, you have to do necessary configuration changes in the standalone version of the tool depending on the products that you want to run the tool on.

For information on how to build, configure and run the standalone version of the Identity Anonymization tool to run on multiple WSO2 products, see Removing References to Deleted User Identities in WSO2 Products  in the WSO2 Administration Guide.