This documentation is for WSO2 API Manager 2.2.0. View documentation for the latest release.

All docs This doc
||
Skip to end of metadata
Go to start of metadata
 What is GDPR?

The General Data Protection Regulation (GDPR) is a new legal framework that was formalized by the European Union (EU) in 2016. It comes into effect from 28, May 2018. GDPR requires any organization that processes Personally Identifiable Information (PII) of individuals who live in Europe, to be compliant with the regulations. Organizations that fail to demonstrate GDPR compliance are subjected to financial penalties.

Do you want to learn more about GDPR?

If you are new to GDPR, we recommend that you take a look at our tutorial series on Creating a Winning GDPR Strategy.

For more resources on GDPR, see the white papers, case studies, solution briefs, webinars, and talks published on our WSO2 GDPR homepage. You can also find the original GDPR legal text here.

The Forget-Me tool, pre-packed with API-M 2.2.0, can be used to remove identities of an external user who is deleted according to the system administrator's request. This tool removes user identities stored in the database and in log files, in order to meet GDPR requirements. The following sections guide you through configuring and running this tool in WSO2 API Manager.

Changing the default configurations of the tool

All configurations related to this tool can be found inside the <API-M_HOME>/repository/components/tools/forget-me/conf directory. The default configurations are set up as follows:

  • Read Logs: <API-M_HOME>/repository/logs

  • Read Datasource: <API-M_HOME>/repository/conf/datasources/

  • Default datasource name: WSO2AM_DB, WSO2_CARBON_DB

  • Log file name regex: (.)*(log|out)

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

Changing the location of the default configuration

To change the location of the default configurations for the pre-packed tool, do the following:

  1. Open the forgetme.sh file found inside the <API-M_HOME>/bin folder. This file contains the following.

    sh $CARBON_HOME/repository/components/tools/forget-me/bin/forget-me -d $CARBON_HOME/repository/components/tools/forget-me/conf $@
  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.

Running the tool in API Manager

Before you begin!

  • Before you start removing PII stored by the WSO2 API Manager, be sure that the relevant user has been inactive in the system for a sufficient amount of time. This will ensure that all of the user's PII contained in log files are successfully archived. You can then follow the instructions given below to remove the user's PII references from the archived log files.
  • Note that this tool is designed to run in offline mode (i.e., the server should be shut down or run on another machine) in order to prevent unnecessary load to the server. If this tool runs in online mode (i.e., when the server is running), DB lock situations on the H2 databases may occur. This DB lock may happen if at least one of your databases point to H2. For example, let's say you have the User, REG and AM databases pointed to MySQL but your Carbon DB is in  H2; even then you can get this DB lock error when running in online mode.
  • If you have configured a database other than the default H2 database, copy the relevant driver to the <API-M_HOME>/repository/components/tools/forget-me/lib directory.

This tool is packaged with WSO2 API Manager by default. Follow the steps below to run this tool.

  1. Open a new terminal window and navigate to the <API-M_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>

    The command specified above uses only the -U <username> option, which is the only mandatory option to run the tool. There are several other optional command line options that you can specify based on your requirement. The supported options are described in detail below.

  3. The following is a list of all the command line options that can be used with this command.

    Command line optionDescriptionRequiredDefault ValueSample value
    UThe name of the user whose identity references you want to remove.Yes
    -U alex.doe
    d

    The configuration directory to use when the tool is run.

    If you do not specify a value for this option, the default conf directory is used.

    No
    -d /users/alex/forgetme/config
    TThe tenant domain.No carbon.super

    -T example-company

    TID

    The tenant ID.

    Note

    If you have specified a tenant-domain, it is mandatory to specify the tenant ID.
    No
    -TID 1234
    DThe userstore domain.No PRIMARY

    -D Finance-domain

    puThe pseudonym with which the username should be replaced.NoA random UUID value is generated as the pseudonym.

    -pu “123-343-435-545-dfd-4”

    carbon

    The CARBON HOME.

    This should be replaced with the variable $CARBON_HOME in directories configured in the main configuration file.

    No
    -carbon “usr/bin/wso2am/wso2am2.2.0”

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

Note

The tool removes references to a deleted user’s identity from all RDBMS tables as well as from all log file copies that are created at the time the tool is run. It is the responsibility of the organization’s system administrator to manually remove the original log files that contain a deleted users information at an appropriate time.

Once all the references to a deleted user’s identity are removed, you can view the generated execution reports in the <API-M_HOME>/repository/components/tools/forget-me/conf directory with the Report-<processor>-<Timestamp>.txt naming convention.

Running the tool in API Manager Analytics

Shown below is an example data stream used by API Manager Analytics. Note that the user ID/username, emails and the IP are Personally Identifiable Information (PII) of the user.

Stream NameAttribute List
org.wso2.analytics.apim.ipAccessSummary
  • userId
  • ip
org.wso2.analytics.apim.alertStakeholderInfo
  • userId
  • emails

These PII references can be removed from the Analytics database by using the Forget-Me tool. Follow the steps given below.

  1. Add the relevant drivers for your Analytics-specific databases to the <API-M_ANALYTICS_HOME>/repository/components/tools/forget-me/lib directory. For example, if you have changed your Analytics databases from the default H2 instances to MySQL, copy the MySQL driver to this given directory.
  2. Create a folder named 'streams' in the <API-M_ANALYTICS_HOME>/repository/components/tools/forget-me/conf/ directory. 
  3. Create a new file named streams.json with content similar to what is shown below based on the streams used, and store it in the /streams directory that you created in the previous step. This file holds the details of the streams and the attributes with PII that need to be removed from the database.

    {
        "streams": [
            {
          		"streamName": "org.wso2.analytics.apim.ipAccessSummary",
          		"attributes": ["userId", "ip"],
          		"id": "userId"
        	},
            {
          		"streamName": "org.wso2.analytics.apim.alertStakeholderInfo",
          		"attributes": ["userId", "emails"],
          		"id": "userId"
        	}
        ]
    }

    The above configuration includes the following: 

    • Stream Name: The name of the stream.
    • Attributes: The list of attributes that contain PII.
    • id: The ID attribute, which holds the value that needs to be anonymized (replaced with a pseudonym).
  4. Create a new file named config.json in the <API-M_ANALYTICS_HOME>/repository/components/tools/forget-me/conf/ directory with the content shown below.

    {
        "processors": [
            "analytics-streams"
        ],
        "directories": [
            {
                "dir": "streams",
                "type": "analytics-streams",
                "processor": "analytics-streams"
            }
        ]
    }
  5. Open a command prompt and navigate to the <API-M_ANALYTICS_HOME>/bin directory.
  6. 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>

Running the tool in standalone mode

This tool can run in standalone mode and therefore, cater to multiple products. This means that if you are using multiple WSO2 products and need to delete the user's identity from all products at once, you can do so by running the tool in standalone mode.

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

  • No labels