Configuring ESAPI Validator Settings
The HTTP request header/parameter validation through the Enhanced Security Application Programming Interface (ESAPI) is configurable via the validation.properties file. The validation.properties file is created upon startup of ThingWorx and is located in the following location: /ThingworxStorage/esapi. You can configure the regex pattern to add headers/properties or to modify existing values.
Configuring a New Header
To configure a new header, add the following to the validation.properties file. The header name is not case sensitive.
"Validator.HTTPHeaderValue_{new-header-name}={regex}"
Configuring a New Parameter
To configure a new parameter, add the following to the validation.properties file: The parameter name is case sensitive.
Validator.HTTPParameterValue_{new-parameter-name}={regex}"
Default Behaviors
• ThingWorx uses the regex as defined in the validation.properties file for each header and parameter for pattern matching.
• If an HTTP request contains a header that is not defined in the validation.properties file, ThingWorx will use the regex pattern defined for Validator.HTTPHeaderValue for pattern matching.
• If an HTTP request contains a parameter that is not defined in the validation.properties file, ThingWorx will use the regex pattern defined for Validator.HTTPParameterValue for pattern matching.
• ThingWorx will empty out the value of each header and parameter in the HTTP request if a value does not match its corresponding regex pattern.
• ESAPI validates the length of the parameters and headers (via HTTPRequestHeaderMaxLength and HTTPRequestParameterMaxLength). The default for each is 2000 characters, but can be modified in the platform-settings.json. See example below:
{
"PlatformSettingsConfig": {
"BasicSettings": {
"HTTPRequestHeaderMaxLength": 2000,
"HTTPRequestParameterMaxLength": 2000
}
},
"PersistenceProviderPackageConfigs": {
"PostgresPersistenceProviderPackage": {
"ConnectionInformation": {
"jdbcUrl": "jdbc:postgresql://localhost:5432/thingworx",
"password": "password",
"username": "twadmin"
}
}
}
}
• After validating a value against a configured regular expression, ESAPI also performs the following validations:
1. Checks for multiple encoded tokens (for example, percentage signs and cookies) in the value and an error is thrown if more than one encoded token is found. This can be disabled by adding Encoder.AllowMultipleEncoding=true to the top of the validation.properties file.
2. If there are multiple encoded tokens and multiple encodings are allowed, there is also a check to ensure that multiple encodings are not of mixed types. This can be disabled by adding Encoder.AllowMixedEncoding=true to the top of the validation.properties file.
Action Required Before Upgrading from ThingWorx 6.0 and later
If you are upgrading from version 6.0 or later, you must remove the existing validation.properties file from /ThingworxStorage/esapi before upgrading. If you do not remove the file, the updated file with these additional parameters will not overwrite the current version during upgrade.
Detailed upgrade instructions are available in the Installing ThingWorx document located on the
Reference Documents site.