Configuring third-party authentication products

To use a third-party authentication product, you must customize various configuration settings.

Before you begin

Ensure that all your IBM® Business Process Manager servers and clients are at V8.5.0.1 or later.

Attention: Users asserted by third-party authentication products must exist in the configured user registry. WebSphere® Application Server allows asserting any user name, group membership, and additional information using third-party authentication, whereas IBM BPM relies on user and group membership information from the configured user registry. For IBM BPM Standard authorization, group membership is retrieved from the configured user registry and asserted group membership is ignored.

Procedure

Configure your third-party authentication product so that it does not intercept URLs that IBM BPM uses for server to server communication. For information about how to configure your third-party authentication product, see the documentation for that product.

Configure your third-party authentication product to allow basic access authentication for the context roots that are listed in the following table.

Table 1. Context roots that require basic authentication for technical user IDs
Context roots that require basic authentication	Description
`/ProcessCenterInternal/*`	Process Server uses this context root on Process Center to register or unregister with Process Center.
`/ProcessServerInternal/*`	Process Center uses this context root on Process Server for online deployment.
`/bpm/repo/v1/ejbproxy/*`	Process Designer and Process Server use this context root during debugging and for retrieving version information.

Tip: Some forms of third party authentication, such as SPNEGO, use regular expressions to exclude specific URLs or allow basic authentication. /ProcessCenterInternal/* starts with /ProcessCenter. In the case of SPNEGO, you cannot configure a filter criteria of request-url^=ProcessPortal|ProcessCenter|ProcessAdmin. Instead, you would use request-url!=ProcessCenterInternal;request-url^=ProcessPortal|ProcessCenter|ProcessAdmin. See, SPNEGO web authentication filter values.

Configure your third-party authentication product so that it does not intercept communications with the web services that are listed in the following table.

Table 2. Web service context roots that must not be intercepted by third-party authentication products
Web service context roots that must not be intercepted	Associated service
`/bpmjaxws/*`	IBM BPM JAX-WS Web Services API
`/fncmis/*`	The embedded Enterprise Content Management Content Management Interoperability Service (ECM CMIS) web service provider
`/RemoteALWeb/*`	Remote artifact loader
`/teamworks/webservices/*`	Teamworks web services
`/webapi/*`	IBM BPM legacy web service API

Ensure that your third-party authentication product allows URLs to contain all characters that IBM BPM uses. The default configuration of your third-party authentication product might not allow the characters"<" and ">", which Process Inspector uses. For information about such restrictions and how you can configure the product to allow these characters, see the documentation for your third-party authentication product.

If your third-party authentication product requires that all logout actions in clients are redirected to special URLs, you must change the configuration settings for each IBM BPM client that you use.

Identify the IBM Business Process Manager clients that you use. For the list of clients, see the following table, noting that AppCluster is the name of your application cluster and SupportCluster is the name of your support cluster.

Table 3. IBM Business Process Manager client logout page configuration paths and attribute names
IBM BPM client	AdminConfig command configuration object containment path	Attribute name for the custom logout page URL	Notes
Business Process Archive Explorer	/ServerCluster:`SupportCluster` /BPMClusterConfigExtension: /BPMBPCArchiveExplorer:/	customLogoutPage	This client is available only in IBM BPM Advanced.
Business Process Choreographer Explorer	/ServerCluster:`SupportCluster` /BPMClusterConfigExtension: /BPMBPCExplorer:/	customLogoutPage	This client is available only in IBM BPM Advanced.
Business Rules Manager	/ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMBusinessRules:/	customLogoutPage
Performance Data Warehouse Performance Admin Console	/ServerCluster:`SupportCluster` /BPMClusterConfigExtension: /BPMPerformanceDataWarehouse:/	customLogoutPage
Process Admin Console	On Process Center: /ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMProcessCenter:/ On Process Server: /ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMProcessServer:/	processAdminCustomLogout	Tip: If you use Process Inspector in the Process Admin Console, when you log out of Process Inspector you are redirected to the custom logout page that you specify for the Process Admin Console.
Process Center Console	/ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMProcessCenter:/	customLogoutPage
Process Portal	/ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMPortal:/	customLogoutPage
REST API Tester	On Process Center: /ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMProcessCenter:/ On Process Server: /ServerCluster:`AppCluster` /BPMClusterConfigExtension: /BPMProcessServer:/	restApiTesterCustomLogout

For each IBM BPM client that you use, identify the URL of the custom logout page that you want logout actions to be redirected to.
Important: The URLs of the custom logout pages might be misinterpreted if they include the following characters.
- Spaces
- Percent signs (%) that are not part of a character coding, such as %25
- Ampersand characters (&) that are not part of a predefined entity, such as &
- Other special characters
To ensure that each URL is parsed correctly, you must replace special characters with a suitable encoding, such as %20 for spaces, %25 for percent signs, and %26 for ampersands. Substituting the predefined symbol & for ampersands might not work for all clients. If a URL is difficult to convert, you can submit it to an online URL encoder to convert it to a suitable string.
If any of the URLs of the custom logout pages are not on the same host as the IBM BPM server or do not belong to the same domain, you must set one of the com.ibm.websphere.security.allowAnyLogoutExitPageHost or com.ibm.websphere.security.logoutExitPageDomainList global security custom properties.
Tip: For more information about these custom properties, see Security custom properties.

For each IBM BPM client that you use, run the necessary administrative commands to set the appropriate custom logout page property to point to the custom logout page. For example, to set the custom logout page URL for the Process Center Console to https://security.example.com/pclogout.html on a Windows platform, enter the following commands.

Connect to the wsadmin client:

D:\IBM\bpm8500\WAS\AppServer\profiles\AdPCDmgr0Profile\bin>wsadmin.bat -conntype NONE -lang jython
WASX7357I: By request, this scripting client is not connected to any server process. Certain 
configuration and application operations will be available in local mode.
WASX7031I: For help, enter: "print Help.help()"

Using the appropriate path from Table 3, get the Process Center object and display its value:

wsadmin>path='/ServerCluster:AppCluster/BPMClusterConfigExtension:/BPMProcessCenter:/'
wsadmin>object=AdminConfig.getid(path)
wsadmin>object
'(cells/PCCell1/clusters/AppCluster|cluster-bpm.xml#BPMProcessCenter_1374114772846)'

Using the appropriate attribute name for the custom logout page URL from Table 3, display the current value of the custom logout page URL attribute:
```
wsadmin>clp='customLogoutPage'
wsadmin>print AdminConfig.showAttribute(object,clp)
None
```

Set the value of the custom logout page URL attribute:

wsadmin>AdminConfig.modify(object,[[clp,'https://security.example.com/pclogout.html']])
''

Display the new value to verify that it is correct:

wsadmin>print AdminConfig.showAttribute(object,clp)
https://security.example.com/pclogout.html

Save the changes.
```
wsadmin>AdminConfig.save()
''
```

If you use a third-party Trust Association Interceptor (TAI), complete the following actions:
1. If you do not use dedicated security domains, complete the following actions on the global security level:
  1. Enable trust association.
    1. Using the administrative console, navigate to Security > Global Security > Web and SIP Security > Trust Association.
    2. Select Enable trust association.
    3. Click Interceptors, then click New and enter the name of the TAI Java class name for your third-party authentication product. For example, for CA SiteMinder, the Java class name is com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor.
      Tip: For information about the TAI Java class name for other third-party authentication products, see the documentation for those products.
  2. Optional: To ensure that TAI is invoked before Single Sign-On (SSO), set the custom property InvokeTAIbeforeSSO. Using the administrative console, navigate to Security > Global Security > Custom properties and click New. Enter the custom property name com.ibm.websphere.security.InvokeTAIbeforeSSO, and the name of the TAI Java class for your third-party authentication provider.
2. If you use dedicated security domains, complete the following actions at the security domain level:
  1. Enable trust association for each security domain. For each security domain, security_domain_name, complete the following actions in the administrative console:
    1. Navigate to Security > Security domains > security_domain_name > Trust Association.
    2. Select Customize for this domain.
    3. Select Enable trust association.
    4. Click Interceptors, then click New and enter the name of the TAI Java class name for your third-party authentication product. For example, for CA SiteMinder, the Java class name is com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor.
      Tip: For information about the TAI Java class name for other third-party authentication products, see the documentation for those products.
  2. Optional: To ensure that TAI is invoked before Single Sign-On (SSO), set the custom property InvokeTAIbeforeSSO. Use the administrative console to set the custom property for each security domain, security_domain_name. Navigate to Security > Security domains > security_domain_name > Custom properties and click New. Enter the custom property name com.ibm.websphere.security.InvokeTAIbeforeSSO, and the name of the TAI Java class for your third-party authentication provider.
Complete the actions that are described in Configuring the propagation of HTTP headers and cookies for a third-party authentication environment.
Complete the actions that are described in Configuring endpoints to match your topology.

Verify that IBM BPM works correctly with your third-party authentication product. For each IBM BPM client that you use, verify that you can log on, that the client is fully functional, and that logging out redirects correctly. The following table describes some possible problems and how to solve them.

Table 4. Diagnosing possible problems with third-party authentication products
Problem	Possible causes	Solutions
When you are logged on to a Process Center, Process Server is not visible.	If you have separate web servers for internal and external traffic, Process Server might not be accessible from the Process Center	Check and adapt the endpoints to suit your setup as described in Modifying IBM Process Server connection properties.
Clients do not display all IBM Business Process Manager data correctly.	Calls to the remote artifact loader are being intercepted. If you have multiple deployment environments, each one has its own remote artifact loader, and the endpoints might not be configured to reflect your topology.	Make sure that your third-party authentication product is not intercepting calls to the RAL context root `/RemoteALWeb`. You might need to configure the `REMOTE_AL` endpoint for each deployment environment, as described in Configuring endpoints to match your topology.
Process Designer does not work properly.	Your third-party authentication product might use a login form that Process Designer cannot process.	Either make sure that your third-party authentication product is not intercepting calls to the Process Center URL that is used by Process Designer or implement an authenticator plug-in to handle the login form. For more information about creating a plug-in for the Process Designer login authenticator extension point, see Configuring a custom authenticator plug-in. Tip: Process Designer normally uses only HTTP calls although if httpProtocolOnly is set to `false`, a mixture of HTTP, RMI, and JMS calls are used, as described in Configuring the httpProtocolOnly property for Process Designer. Using the `true` setting can simplify how your third-party authentication product must be configured.

Results

IBM Business Process Manager and its clients work correctly with your third-party authentication product.