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.

Before you begin

Verify what type of third-party authentication SSO that you are using. For example, IBM HTTP Server (IHS) or SiteMinder.
Complete the custom authenticator configuration before you install Process Designer.
Configure the httpProtocolOnly property for Process Designer to use the HTTP or HTTPS protocol instead of Java's Remote Method Invocation (RMI) with Java™ Messaging Service (JMS). See Configuring the httpProtocolOnly property for Process Designer.
For some external links to work properly with a custom authenticator plug-in, set add-redirect-url-credentials to false, for example, the generated report link for a process app. For information about setting properties, see Setting preferences.

About this task

You define a login authenticator in Process Designer to declare an extension for client side login logic to address special authentication requirements from the server side. When authentication is triggered, Process Designer retrieves the authenticator application programming interface (API) and starts the login logic. The authenticator extension point is an API that is provided in the Eclipse plug-in format.

The authenticator API can return two sets of security tokens. The first set of security tokens is shared among all connections using Java HTTP clients triggered by user Create, Read, Update and Delete (CRUD) activities within one Process Designer. This set supports inactivity timeout on user interaction requests. The second set of security tokens is shared during Process Designer and Process Center communication, CometD initialization, and embedded browsers. This set does not provide inactivity timeout support. If the authenticator API returns only one set of security tokens, it is shared among all HTTP clients within Process Designer. Active polling will disable inactivity timeout. The authenticator API uses the same set of security tokens for polling and inactivity timeout. If you are using a custom plug-in and want to support inactivity timeout, your environment must support two security tokens.

Procedure

Define the login authenticator extension. The Process Designer login authenticator extension point requires that:

The class is extended from the abstract Authenticator class.
You specify the contributor class name in the extension details.
The class must implement the abstract method for the custom login logic.
You can set the isCustom flag to true in the extension details. If not set, it defaults to true.

The abstract authenticator class is in the com.ibm.bpm.client.ae.security.authentication package. The subclass must implement the login API:

public abstract ILoginResult login(String userId, String url, int returnCode, 
            Map<String, List<String>> responseHeaders, InputStream responseBody) 
            throws Exception;

The parameters of the login API:

userId - the userId returned by previous login, null if it is first time to login.
url - url for the protected resource or url after redirect has been followed
returnCode - HTTP return code from the URL
responseHeaders - Map<String, List<String>>, keys are header names and values are list of header values. 
responseBody - InputStream: caller will close the InputStream
LoginResult - need to return a valid result, not null.

exception: if login failed, throw Exception with localized message.

The extension point for custom login behavior:

<!ELEMENT extension (Authenticator)
<!ATTLIST extension
  point  CDATA #REQUIRED
  id     CDATA #IMPLIED
  name   CDATA #IMPLIED

<!ELEMENT Authenticator EMPTY>
<!ATTLIST Authenticator
  isCustom  (true | false)
  class     CDATA #REQUIRED

The login API returns the results in the ILoginResult interface, which is in the com.ibm.bpm.client.ae.security.authentication package. Implement the login API:

Note: IBM Business Process Manager includes a BPM_GENERIC_HEADER in the response. If HTTP return code is less than 400, for example 302, and the BPM_GENERIC_HEADER header is not in the response, Process Designer call the custom plug-in. In addition, if one of the following conditions are true, Process Designer call the custom plug-in:

If the HTTP return code is 401
If the HTTP return code is 407

public Collection<String> getRequestTokens();
Obtains the security tokens for normal user interactions if login was needed null otherwise.
The items in collection are the external format of the cookies, such as:
     SMTRYNO=; expires=Fri, 11 Jan 2013 13:54:32 GMT; path=/; 
     domain=ibm.com; HTTPOnly

return Collection<String> - The security cookies for normal PD activities, or null if 
     login is not required

public Collection<String> getPollingTokens();
Obtains polling tokens if inactive session timeout is required. 
The items in collection are the external format of the cookies, such as:
	SMTRYNO=; expires=Fri, 11 Jan 2013 13:54:32 GMT; path=/; 
      domain=ibm.com; HTTPOnly 
      
return Collection<String> - The security cookies for polling if needed, or null

public String getProxyAuthorizationHeader();
Obtains the proxy authorization header if a forward proxy is configured with PD. Such as:
     	NTLM TlRMTVNTUAADAAAAGAAYAHIAAAAYABgAigAAABIAEgBIAAAABgAGAFoAA
 
return String - proxy authorization header if the returnCode passed to Authenticator.login 
      method is 407, otherwise return null

public String getUserId();
Return the userId of the person logged in.

return String

Deploy the custom login authenticator plug-in to Eclipse. The plug-in is exported as individual jar files.
1. Place the custom authenticator plug-in jar files in to the BPM\Lombardi\tools\designer\dropins folder.
2. Download Process Designer from the Process Center. Process Center discovers new files in the dropins folder and includes them in the downloaded IBM Process Designer.zip file.
Optional: To install a new version of the custom plug-in:
1. Add the new plug-in jar files to the BPM\Lombardi\tools\designer\dropins folder.
2. Uninstall Process Designer.
3. Download Process Designer from Process Center.