Configuring third-party authentication products
Before you begin
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
- Configure your third-party authentication product to
allow basic access authentication for the context roots that are listed
in the following table.
- 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
- 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() ''
- Connect to the wsadmin client:
- 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.
- If you use a third-party Trust Association
Interceptor (TAI), complete the following actions:
- If you do not use dedicated security domains, complete
the following actions on the global security level:
- Enable trust association.
- Using the administrative console, navigate to Security > Global Security > Web and SIP Security > Trust Association.
- Select Enable trust association.
- 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.
- 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.
- Enable trust association.
- If you use dedicated security domains, complete the
following actions at the security domain level:
- Enable trust association for each security domain. For each security
domain, security_domain_name, complete the following
actions in the administrative console:
- Navigate to Security > Security domains > security_domain_name > Trust Association.
- Select Customize for this domain.
- Select Enable trust association.
- 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.
- 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.
- Enable trust association for each security domain. For each security
domain, security_domain_name, complete the following
actions in the administrative console:
- If you do not use dedicated security domains, complete
the following actions on the global security level:
- 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
- Configuring a custom authenticator plug-in
IBM Business Process Manager Process Center supports the use of a custom authenticator plug-in to work with your third-party authentication single sign-on (SSO) environment. - Configuring the httpProtocolOnly property for Process Designer
Modify the httpProtocolOnly property to configure Process Designer to use the HTTP or HTTPS protocol instead of RMI with JMS. - 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.