CSRF Validation Security Configurations

What are the changes?

A number of configuration keys related to enhancing CSRF prevention policies, and resolving CSRF validation errors, have changed.

In summary, the config file used is security.properties instead of server.properties, and the keys themselves now start with security.

	Version 23.0.7 and earlier	Version 23.0.8 and later
Configuration location	`[app-path]/server/server.properties`	`[app-path]/server/security.properties`
Enable validation config key	`server.csrf-check.validate-request-origin`	`security.csrf-check.validate-request-origin`
Unknown origin config key	`server.csrf-check.deny-unknown-origin`	`security.csrf-check.deny-unknown-origin`
Allowed domain config key		`security.csrf-check.allowed-domain-list`

Regardless of the version in use, these keys retain the same behavior in both 23.0.7 and earlier, and 23.0.8 and later - with the allowed-domain-list key only configurable in 23.0.8 and later.

About updating the security.properties file

The changes mentioned here will only be automatically visible to you as an admin if your PaperCut NG/MF version 23.0.8 (or later) installation is a “fresh” install - not an upgrade.

Due to the fact that we cannot overwrite your security.properties file, if you are upgrading your server to version 23.0.8 or later, you will need to manually add the 3 new security config values to the security.properties file, with 2 values mirroring their predecessors inside server.properties and 1 brand new value that came into effect as of PaperCut 23.0.8. You will need admin privileges at the OS level to edit the security.properties file.

The old values inside server.properties are now no longer functional and the server will no longer take their values into consideration. You may safely delete them if you prefer, (or not).

The security.properties.template has a good example of what you need to put in the new file. You may copy and paste the related content from there.

Configuration key definitions

security.csrf-check.validate-request-origin

(or server.csrf-check.validate-request-origin in version 23.0.7 and earlier)

Defines whether we should filter every HTTP request coming into the MF server, and compare their origin (or sometimes proxy set up) against the web address of the MF server itself.

When enabled, if it is not a perfect match from scheme to hostname to port number etc, we drop the request and return an error. This value is by default enabled (Y).

security.csrf-check.deny-unknown-origin

(or server.csrf-check.deny-unknown-origin in version 23.0.7 and earlier)

Defines the behaviour of the server when there is no clear origin information about the incoming request.

When enabled, it also blocks all requests with no clear origin information. This value is also by default enabled (Y).

security.csrf-check.allowed-domain-list

Defines a list of domains allowed to send POST requests to the PaperCut app server. Unlike the previous 2 items that expect a Y or N value, this value expects a string value as specific as possible about a known and legitimate source that may send POST requests to the PaperCut server. It accepts multiple semicolon ; separated values as one string.

This can be useful for servers that run payment gateways. For example, if you reasonably expect a domain such as paypal.com will send POST requests to your app server, because you are running a PayPal Payment Gateway module on your app server, you may add paypal.com to the key. If you also expect nelnet.com to send POST requests to your server, you may enter the value as paypal.com;nelnet.com.

Even if the security.csrf-check.validate-request-origin key has been enabled (set to Y), requests from defined external domains may still come through. This config value allows all the incoming traffic coming from domains that end with at least one of the semicolon separated values.

The values inside this string can be used to allow POST backs from defined domains if:

The domain where the POST request originates from ends with your defined domain, e.g. www.paypal.com ends with paypal.com, so if you add paypal.com to the security.csrf-check.allowed-domain-list, any POST requests from domain www.paypal.com will be allowed through. If you need to add multiple values, you can separate these with a ; e.g. paypal.com;nelnet.com
The defined “allowed domain” value has at least 5 characters, e.g. .com will be considered too short because it only has 4 characters. In the interest of your security, be as specific as possible. For example, paypal.com is better than l.com, although both are permitted. This rule applies to each part that is separated by the semicolon(s). Any part that is shorter than 5 characters will not take effect.
The domains added to the security.properties file do not support wild card expressions such as *.

By default, this key has an empty value, meaning it does not make any exceptions for external hosts to send POST requests to your PaperCut Application server.

Legacy information

PaperCut 17.3 introduced a security enhancement to improve the coverage of HTTP header origin checks, in line with OWASP recommendations. However, in some cases, attempting to log into the Admin or User web interface after upgrading to 17.3, sometimes produces a CSRF (Cross Site Request Forgery) validation error message. This was based on the way the PaperCut web server was configured to redirect users to new pages (i.e. the site’s proxy configuration and the way it was configured to handle host header overrides).

This was resolved in PaperCut 17.3.4, only for sites using a standard proxy server configuration to redirect users to new pages (i.e. sites using the server.force-host-header in the server.properties file , to configure the proxy to override host headers).

However, this issue will continue to persist for sites using a non-standard reverse proxy server configuration to redirect users to new pages (i.e. sites using a proxy running in FRONT of PaperCut, to override host headers).

Depending on a site’s proxy configuration and the version of PaperCut being run, the following resolutions may apply:

Any site with any proxy server configuration, running PaperCut 17.3.0 or above but below 23.0.8:

Disable the CSRF security enhancement:

In a text editor, open [app-path]/server/server.properties
Either, search for and find the line: server.csrf-check.validate-request-origin, or add a new line: server.csrf-check.validate-request-origin
Set server.csrf-check.validate-request-origin to N.
Restart the service PaperCut Application Server.

Note: When editing an existing setting, please remove the leading # character.

Sites with a non-standard reverse proxy server configuration, running PaperCut 17.3.0 or above:

(i.e. host headers are overridden by a proxy that is configured to run in FRONT of PaperCut)

Update the proxy configuration to rely on the X-Forwarded-Host header instead of overriding the host header

Sites with a standard proxy server configuration (server.force-host-header) , running PaperCut 17.3.0–17.3.3:

upgrade to PaperCut 17.3.4 (or above)

OR
update the infrastructure so it doesn’t require host header overrides.

Other known issues:

Requests to the PaperCut server will fail CSRF validation if the host name contains an underscore (_). This is due to a known JRE bug.

CSRF Security Configs

This page applies to: