Configuring the propagation of HTTP headers and cookies for a third-party authentication environment

If you use a third-party authentication product, you must configure the web Process Inspector façade and federated REST API façade to ensure that the HTTP headers and cookies are propagated from the incoming request of a transaction through to the outgoing IBM® BPM REST request.

About this task

You can specify a list of headers and cookies that the Process Inspector must propagate. You can also specify a URL prefix for outgoing requests from the façade to the IBM BPM REST service. If you use IBM BPM Advanced, you must also specify a list of headers and cookies that the federated REST API must propagate.

Note: If the REST API façade returns a timeout exception while waiting for a response from the database, you can configure the web Process Inspector façade to increase the default connection time, which is 240 seconds. See Modifying the stateful session bean cache.

Procedure

If you use Process Inspector on the Inspector tab of the Process Admin Console, complete the following actions.
1. For each application cluster member in your deployment environment, edit the 100Custom.xml file.
  Tip: For information about the 100Custom.xml configuration file, including its location, see The 99Local.xml and 100Custom.xml configuration files.
2. Add the names of the headers and cookies that are to be propagated. Use the <propagate> tag in the <process-inspector> section, as illustrated in the following example for CA SiteMinder:
```
<server merge="mergeChildren">
    <process-inspector merge="mergeChildren">
         <propagate merge="append">
            <header name="SM_TRANSACTIONID"/>
            <header name="SM_SDOMAIN"/>
            <header name="SM_AUTHTYPE"/>
            <header name="SM_USER"/>
            <header name="SM_USERDN"/>
            <header name="SM_SERVERSESSIONID"/>
            <header name="SM_SERVERSESSIONSPEC"/>
            <header name="SM_TIMETOEXPIRE"/>
            <header name="SM_SERVERIDENTITYSPEC"/>
            <cookie name="SMSESSION"/>
        </propagate>
    </process-inspector>
</server>
```
  For information about the header and cookie names that are used by other third-party authentication products, see the documentation for those products.
  Tip: The LTPA token and LtpaToken2 cookies are propagated by default.
3. Save your changes.
If you use IBM BPM Advanced, configure the header and cookie propagation settings for the federated REST API. If you want all headers and cookies to be forwarded, you can skip this step because that is the default behavior.
Important: The deny and allow rules are defined by Java™ regular expressions. The strings "" and ".*" match all headers and cookies. The semantics of the forwarding rules for headers and cookies are that the deny rule is evaluated before the allow rule. These semantics mean that headers and cookies that match both the deny rule and the allow rule are forwarded.
1. Connect to the wsadmin client:
```
wsadmin.bat -conntype NONE -lang jython
```
```
wsadmin.sh -conntype NONE -lang jython
```
2. Get and display the BPMDispatchConfiguration object:
```
wsadmin>path='/Cell:%s/BPMFederationConfiguration:/BPMApiFederation:/BPMApiDomain:default
    /BPMDispatchConfiguration:/' % cellName
wsadmin>dc=AdminConfig.getid(path)
wsadmin>dc
```
3. Set the values of the denyForwardHttpHeader and denyForwardHttpCookie attributes to deny the forwarding of all headers and cookies:
```
wsadmin>AdminConfig.modify(dc,[['denyForwardHttpHeader','.*']])
wsadmin>AdminConfig.modify(dc,[['denyForwardHttpCookie','.*']])
wsadmin>AdminConfig.save()
```
4. Set the value of the allowForwardHttpHeader and allowForwardHttpCookie attributes to forward only the specified headers and cookies. For example, if you use CA SiteMinder, enter the following commands:
```
wsadmin>AdminConfig.modify(dc,[['allowForwardHttpHeader',
   'SM_TRANSACTIONID|SM_SDOMAIN|SM_AUTHTYPE|SM_USER|SM_USERDN|
    SM_SERVERSESSIONID|SM_SERVERSESSIONSPEC|SM_TIMETOEXPIRE|
    SM_SERVERIDENTITYSPEC']])
wsadmin>AdminConfig.modify(dc,[['allowForwardHttpCookie','SMSESSION']])
wsadmin>AdminConfig.save()
```
  For information about the header and cookie names that are used by other third-party authentication products, see the documentation for those products.
If you modified any 100Custom.xml configuration files, restart the server to activate the changes.