Configuring third-party authentication products

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

IBM® Business Automation Workflow building on IBM WebSphere® Application Server supports a set of open standards for authentication, including Security Assertion Markup Language (SAML), OpenID Connect, and Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). You can achieve single sign-on (SSO) with IBM or third-party solutions if the vendor of your SSO solution provides an implementation for the WebSphere Trust Association Interceptor (TAI), as is the case for IBM Security Access Manager and many other products.

This topic describes features that help you to configure as a participant in an SSO landscape, as well as limitations in the context of third-party authentication.

Before you begin

Ensure that all your Business Automation Workflow 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 Business Automation Workflow relies on user and group membership information from the configured user registry. For authorization of BPMN processes and tasks, group membership is retrieved from the configured user registry and asserted group membership is ignored.

Procedure

  1. Configure your third-party authentication product so that it does not intercept URLs that Business Automation Workflow uses for server to server communication.
    For information about how to configure your third-party authentication product, see the documentation for that product.
    1. 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/* Workflow Server uses this context root on Workflow Center to register or unregister with Workflow Center.
      /ProcessServerInternal/* Workflow Center uses this context root on Workflow Server for online deployment.
      /bpm/repo/v1/ejbproxy/* Desktop Process Designer (deprecated) and Workflow Server use this context root during debugging and for retrieving version information.
      rest/bpm/wle/v1/event When using document handlers in remote document management systems, ensure that the document handler can reach this REST API and authenticate as a system account.
      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!=rest/bpm/wle/v1/event;request-url!=ProcessServerInternal;request-url^=ProcessPortal|ProcessCenter|ProcessAdmin. See SPNEGO web authentication filter values.
    2. 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/* Business Automation Workflow 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/* Business Automation Workflow legacy web service API
  2. Ensure that your third-party authentication product allows URLs to contain all characters that Business Automation Workflow 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.
  3. 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 Business Automation Workflow client that you use.
    You can set a single consistent logout exit page by setting the DE level custom property Security.CommonLogoutExitPage, which is described in Security-hardening properties. If you want to set individual logout exit pages per web application, perform the following actions:
    1. Identify the IBM Business Automation Workflow 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 Automation Workflow client logout page configuration paths and attribute names
      Business Automation Workflow 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 the Advanced deployment environment.
      Business Process Choreographer Explorer
      /ServerCluster:SupportCluster
      /BPMClusterConfigExtension:
      /BPMBPCExplorer:/
      		 customLogoutPage This client is available only in the Advanced deployment environment.
      Business Rules Manager
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMBusinessRules:/
      		 customLogoutPage  
      Performance Data Warehouse Performance Admin Console
      /ServerCluster:SupportCluster
      /BPMClusterConfigExtension:
      /BPMPerformanceDataWarehouse:/
      		 customLogoutPage  
      Process Admin Console
      On Workflow Center:
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMProcessCenter:/

      On Workflow 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.
      Workflow Center Console
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMProcessCenter:/
      		 customLogoutPage  
      Process Portal, Heritage Process Portal
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMPortal:/
      		 customLogoutPage  
      REST API Tester
      On Workflow Center:
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMProcessCenter:/
      On Workflow Server:
      /ServerCluster:AppCluster
      /BPMClusterConfigExtension:
      /BPMProcessServer:/
      		 restApiTesterCustomLogout  
    2. For each Business Automation Workflow 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 &amp;
      • 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 &amp; 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.
    3. If any of the URLs of the custom logout pages are not on the same host as the Business Automation Workflow 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.
    4. For each Business Automation Workflow 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 Workflow Center Console to https://security.example.com/pclogout.html on a Windows platform, enter the following commands.
      1. Connect to the wsadmin client:
        D:\IBM\bpm8600\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()"
      2. Using the appropriate path from Table 3, get the Workflow 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)'
      3. 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
      4. Set the value of the custom logout page URL attribute:
        wsadmin>AdminConfig.modify(object,[[clp,'https://security.example.com/pclogout.html']])
''
      5. Display the new value to verify that it is correct:
        wsadmin>print AdminConfig.showAttribute(object,clp)
https://security.example.com/pclogout.html
      6. Save the changes.
        wsadmin>AdminConfig.save()
''
    5. Configure logout for IBM Content Navigator:
      1. Download the SSOLogoutPlugin.zip file from the IBM Community.
      2. Extract the ZIP file. It includes the file SSOLogoutPlugin.jar.
      3. Log in to the IBM Content Navigator administration.
      4. Click the Plug-ins link in the category list.
      5. Click New Plug-in.
      6. For JAR file path, provide the path to the SSOLogoutPlugin.jar file.
      7. Click Load to load the plug-in.
      8. If the plug-in path is correct, you are prompted for the SSO logout redirect URL, for example, if you are using the User Management Service: https://<UMS>:<port>/oidc/endpoint/ums/logout.
      9. Save the plug-in.
      10. iIn the category list, click Desktops.
      11. Select IBM Business Automation Workflow Desktop and click Edit.
      12. Select the General tab.
      13. Scroll down to the Plug-ins section and select the plug-in that you just created, which has the default name SSO Logout Plug in.
      14. Select the Menus tab.
      15. Scroll down to find Banner user session context menu and use the drop-down to change this menu to the new BannerUserSessionSSOLogoutMenu.
      16. Save the Desktop.
      Tip: For more information, see the ECM Community Blog
  4. 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.
  5. Complete the actions that are described in Configuring the propagation of HTTP headers and cookies for a third-party authentication environment.
  6. Complete the actions that are described in Configuring endpoints to match your topology.
  7. Verify that Business Automation Workflow works correctly with your third-party authentication product. For each Business Automation Workflow 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 Workflow Center, Workflow Server is not visible. If you have separate web servers for internal and external traffic, Workflow Server might not be accessible from the Workflow Center Check and adapt the endpoints to suit your setup as described in .
    Clients do not display all IBM Business Automation Workflow 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.
    The desktop Process Designer (deprecated) does not work properly. Your third-party authentication product might use a login form that desktop Process Designer cannot process. Either make sure that your third-party authentication product is not intercepting calls to the Workflow Center URL that is used by desktop Process Designer or implement an authenticator plug-in to handle the login form.
    For more information about creating a plug-in for the desktop Process Designer login authenticator extension point, see Configuring a custom authenticator plug-in.
    Tip: The desktop 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 the desktop Process Designer. Using this setting can simplify how your third-party authentication product must be configured.

Results

IBM Business Automation Workflow and its clients work correctly with your third-party authentication product.