3.5.2 Managing Referer Filtering

LiveCycle provides a Referer Filter to specify Referers that are allowed access to your server resources. By default, the Referer filter does not filter requests that use a safe HTTP method, e.g. GET, unless CSRF_CHECK_GETS is set to true. If the port number for an Allowed Referer entry is set to 0, LiveCycle will allow all requests with Referers from that host regardless of the port number. If no port number is specified, only requests from the default port 80 (HTTP) or port 443 (HTTPS) are allowed. Referer Filtering is disabled if all the entries in the Allowed Referer list are deleted.

When you first install Document Services, the Allowed Referer list is updated with the address of the server on which Document Services is installed. The entries for the server include the server name, the IPv4 address, the IPv6 address if IPv6 is enabled, the loopback address, and a localhost entry. The names added to the Allowed Referer list are returned by Host operating system. For example a server with an IP address of 10.40.54.187 will include the following entries: http://server-name:0, https://10.40.54.187:0, http://127.0.0.1:0, http://localhost:0. For any unqualified name retuned by Host operating system (names that do not have IPv4 address, IPv6 address or qualified domain name) white list is not updated. Modify the Allowed Referer list to suit your business environment. Do not deploy the LiveCycle server in the production environment with the default Allowed Referer list. After modifying any of the Allowed Referers, Referer Exceptions, or URIs, ensure that you restart the server for the changes to take effect.

Managing Allowed Referer list

You can manage the Allowed Referer list from the User Management Interface of Administration Console. The User Management Interface provides you with the functionality to create, edit, or delete the list. Refer to the Preventing CSRF attacks section of the Administration Help for more information on working with the Allowed Referer list.

Managing Allowed Referer Exception and Allowed URI lists

LiveCycle provides APIs to manage the Allowed Referer Exception list and the Allowed URI list. You can use these APIs to retrieve, create, edit, or delete the list. Following is a list of available APIs:

  • createAllowedURIsList

  • getAllowedURIsList

  • updateAllowedURIsList

  • deleteAllowedURIsList

  • addAllowedRefererExceptions

  • getAllowedRefererExceptions

  • updateAllowedRefererExceptions

  • deleteAllowedRefererExceptions

Refer to the LiveCycle API Reference for more information on the APIs.

Use the LC_GLOBAL_ALLOWED_REFERER_EXCEPTION list for Allowed Referer Exceptions at the global level i.e. to define exceptions that are applicable to all applications. This list contains only URIs with either an absolute path (e.g. /index.html) or a relative path (e.g. /sample/). You can also append a regular expression to the end of a relative URI, e.g. /sample/(.)*.

The LC_GLOBAL_ALLOWED_REFERER_EXCEPTION list ID is defined as a constant in the UMConstants class of the com.adobe.idp.um.api namespace, found in adobe-usermanager-client.jar. You can use the LiveCycle APIs to create, modify, or edit this list. For example, to create the Global Allowed Referer Exceptions list use:

addAllowedRefererExceptions(UMConstants.LC_GLOBAL_ALLOWED_REFERER_EXCEPTION, Arrays.asList("/index.html", "/sample/(.)*")) 

Use the CSRF_ALLOWED_REFERER_EXCEPTIONS list for application-specific exceptions.

Disabling the Referer Filter

In the event that the Referer Filter completely blocks access to the LiveCycle server and you cannot edit the Allowed Referer list, you can update the server startup script and disable Referer Filtering.

Include the -Dlc.um.csrffilter.disabled=true JAVA argument in the startup script and restart the server. Ensure that you delete the JAVA argument after you have appropriately reconfigured the Allowed Referer list.

Referer Filtering for Custom WAR files

You may have created custom WAR files to work with LiveCycle in order to meet your business requirements. To enable Referer Filtering for your custom WAR files, include adobe-usermanager-client.jar in the class path for the WAR and include a filter entry in the web.xml file with the following parameters:

CSRF_CHECK_GETS controls the Referer check on GET requests. If this parameter is not defined, the default value is set to false. Include this parameter only if you want to filter your GET requests.

CSRF_ALLOWED_REFERER_EXCEPTIONS is the ID of the Allowed Referer Exceptions list. The Referer Filter prevents requests originating from Referers in the list identified by the list ID, from invoking any resource on the LiveCycle server.

CSRF_ALLOWED_URIS_LIST_NAME is the ID of the Allowed URIs list. The Referer Filter does not block requests for any of the resources in the list identified by the list ID, regardless of the value of the Referer header in the request.

CSRF_ALLOW_NULL_REFERER controls the Referer Filter behavior when the Referer is null or not present. If this parameter is not defined, the default value is set to false. Include this parameter only if you want to allow Null Referers. Allowing null referers may allow some types of Cross Site Request Forgery attacks.

CSRF_NULL_REFERER_EXCEPTIONS is a list of the URIs for which a Referer check is not performed when the Referer is null. This parameter is enabled only when CSRF_ALLOW_NULL_REFERER is set to false. Separate multiple URIs in the list with a comma.

Following is an example of the filter entry in the web.xml file for a SAMPLE WAR file:

<filter> 
       <filter-name> filter-name </filter-name> 
       <filter-class> com.adobe.idp.um.auth.filter.RemoteCSRFFilter </filter-class> 
     <!-- default is false --> 
     <init-param> 
      <param-name> CSRF_ALLOW_NULL_REFERER </param-name> 
      <param-value> false </param-value> 
     </init-param> 
     <!-- default is false --> 
     <init-param> 
      <param-name> CSRF_CHECK_GETS </param-name> 
      <param-value> true </param-value> 
     </init-param> 
     <!-- Optional --> 
     <init-param> 
       <param-name> CSRF_NULL_REFERER_EXCEPTIONS </param-name> 
       <param-value> /SAMPLE/login, /SAMPLE/logout  </param-value> 
     </init-param> 
     <!-- Optional --> 
     <init-param> 
      <param-name> CSRF_ALLOWED_REFERER_EXCEPTIONS </param-name> 
      <param-value> SAMPLE_ALLOWED_REF_EXP_ID </param-value> 
     </init-param> 
     <!-- Optional --> 
     <init-param> 
      <param-name> CSRF_ALLOWED_URIS_LIST_NAME </param-name> 
      <param-value> SAMPLE_ALLOWED_URI_LIST_ID     </param-value> 
     </init-param> 
</filter> 
    ........ 
    <filter-mapping> 
      <filter-name> filter-name </filter-name> 
      <url-pattern>/*</url-pattern> 
    </filter-mapping>

Troubleshooting

If legitimate server requests are being blocked by the CSRF filter, try one of the following:

  • If the rejected request has a Referer header, carefully consider adding it to the Allowed Referer list. Add only Referers that you trust.

  • If the rejected request does not have a Referer header, modify your client application to include a Referer header.

  • If the client can work in a browser, try that deployment model.

  • As a last resort you can add the resource to the Allowed URIs list. This is not a recommended setting.

// Ethnio survey code removed