4 Filtering Tunneled Parameters

This chapter describes an application that filters tunneled parameters. This enhancement enables tighter security by allowing only xparameters that are explicitly allowed.

For general information about xparameters, see the discussion of parameter tunneling in Application Developer's Guide.

About the XParameter Filter Application

The filter application blocks requests that contain xparameters that are not configured as allowed xparameters. Filtering is on a global, not application, level.

The application is implemented by the x-param-filter-interceptor interceptor. When the application is on and Services Gatekeeper starts up, the application reads a configuration file that lists the allowed xparameters. If the list of allowed xparameters changes, you must update the configuration file and redeploy the filtering application.

The application is deployed as a standalone EAR file: interceptor_xparam/xparam_interceptors.ear.

The filter application, named interceptor_xparam, is installed with Services Gatekeeper. To turn the application on, configure the customized interceptor chain and enable interceptor_xparam. When the filter application is on, you need to configure the xparameters that you want to allow as described in "XParameter Filter Configuration File"; otherwise all requests that contain xparameters will be rejected.

XParameter Filter Configuration File

The xparameter filter configuration file is xparam_filter_config.xml. It is located in interceptor_xparam/xparam_interceptors.ear./APP-INF/classes.

To allow an xparameter in a request, list its key as an <xParamKey> sub element in the <allowedXParams> element in xparam_filter_config.xml. For example:

<allowedXParams>
 <xParamKey>sms.protocol.id</xParamKey>
 <xParamK>sms.service.type<xParamKey>
 . . .
</allowedXParams>

The xparameter keys are listed by communication service in the sections on tunneled parameters in the chapters in the Communication Service Guide. Some communication services do not support any xparameters.

XParameter Rejection

If an xparameter is not configured in xparam_filter_config.xml, a SOAP request that passes it will be rejected.

The following is an example of a rejection response to a request that passed the dest_addr_subunit xparameter:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
 <env:Body>
    <env:Fault>
       <faultcode>env:Server</faultcode>
       <faultstring/>
       <detail>
          <v2:ServiceException xmlns:v2="http://www.csapi.org/schema/parlayx/common/v2_1">
             <messageId>SVC0001</messageId>
             <text>A service error occurred. Error code is %1</text>
             <variables>Error validating the request, xparam: dest_addr_subunit in the request data is not allowed.</variables>
          </v2:ServiceException>
       </detail>
    </env:Fault>
 </env:Body>
</env:Envelope>

See "Internal XParameters" for information about exceptions for xparameters that are not rejected.

Internal XParameters

It is possible for custom interceptors to insert xparameters on behalf of an application. To prevent these internal xparameters from being rejected by the filter, make sure that any custom interceptor that adds xparameters is executed after the x-param-filter-interceptor in the interceptor stack

See the discussion of the service interceptors in Platform Development Studio Developer's Guide for information about the order of execution of custom interceptors.

Xparameters added to a request through the <contextAttribute> of an SLA are not rejected because the InjectValuesInRequestContextFromSLA interceptor executes after x-param-filter-interceptor.