3.5.2 Managing Referer Filtering

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.