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 the type of third-party authentication SSO that you are using, for example, IBM HTTP Server (IHS) or SiteMinder.
IBM BPM provides the plug-in extension point and the required interfaces. You must build the plug-in and define the underlying logic that interacts with the user and your SSO solution. This requires Eclipse plug-in development skills.
If the custom authenticator configuration is completed before you install IBM Process Designer, it can be included with Process Designer.
The httpProtocolOnly property must be set to true for Process Designer, which is the default setting. 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 application. For information about setting properties, see Connections from IBM Process Designer to Process Center.

About this task

You build a custom plug-in that defines a login authenticator in Process Designer. The login authenticator must declare an extension for client-side login logic to address special authentication requirements from the server side. When authentication is triggered, Process Designer uses the custom plug-in to trigger 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 that use Java™ HTTP clients that are triggered by user Create, Read, Update and Delete (CRUD) activities in one Process Designer. This set supports inactivity timeouts on user interaction requests.
The second set of security tokens is shared during Process Designer and Process Center communication, CometD initialization, and the use of embedded browsers. This set does not support inactivity timeouts.

Note: If the authenticator API returns only one set of security tokens, all HTTP clients in Process Designer share that set. The same set of security tokens is used for polling and user actions. Active polling prevents inactivity timeouts. If you use a custom plug-in and want to support inactivity timeouts, your plug-in must support two sets of security tokens.

Procedure

In Eclipse or IBM Integration Designer, create a plug-in project for your custom authenticator plug-in.
Import the com.ibm.bpm.client.ae.security.authentication plug-in in to your workspace to make its extension point available. The JAR file is in the <pd_ install>/teamworks/eclipse/plugins/ directory.
Add a dependency to the com.ibm.bpm.client.ae.security.authentication plug-in from your new plug-in.
In your plug-in, add an extension for the com.ibm.bpm.client.ae.security.authentication.authenticators extension point. The extension includes an authenticator element that has the following attributes: class and isCustom. Add your class that implements the login API to the class attribute. You can leave IsCustom blank or set it to true. The default setting is true. For example, your plugin.xml file might contain an extension that looks similar to the following code:
```
<extension point="com.ibm.bpm.client.ae.security.authentication.authenticators">     
   <Authenticator           
      class="myauthPlugin.Authenticator1"           
      isCustom="true">
   </Authenticator>
</extension>
```
Define your class to implement the login API. Process Designer calls this API.

Implement the ILoginResult interface. It returns the results of the login API.

Note: You must define the logic to interact with the SSO system, the user, and the ILoginResult interface as described in this topic. IBM BPM does not provide the code for it.

IBM BPM includes a BPM_GENERIC_HEADER header in the response. If the HTTP return code for a particular HTTP request is less than 400, for example 302, and the BPM_GENERIC_HEADER header is not in the response, Process Designer calls the login API from the custom plug-in. In addition, if one of the following conditions are true, Process Designer also calls the custom plug-in:

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

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

The login API uses the following parameters:

userId - the userId that is returned by the previous login. It is null if it is the first login.
url - the url that is being accessed
returnCode - the HTTP return code that is returned when Process Designer accessed the URL
responseHeaders - Map<String, List<String>> containing the response headers. Keys are header names
             and values are a list of header values. 
responseBody - InputStream with the response body. Process Designer will close the InputStream.
ILoginResult - This should contain the results of your login logic, which includes the security cookies, proxy details, and userID.

exception: if login fails, throw an Exception with a localized message.

In addition to the logic that is used to set variable data for the ILoginResult interface, you must implement these four methods that Process Designer uses to get the results of the login logic.

public Collection<String> getRequestTokens();
Returns the security tokens for normal user interactions if login was needed otherwise returns null.
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

public Collection<String> getPollingTokens();
Returns polling security tokens if an inactive-session timeout is required for normal user interactions otherwise returns null.
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

public String getProxyAuthorizationHeader();
Obtains the proxy authorization header if the returnCode is 407 otherwise returns null, such as:
     	NTLM TlRMTVNTUAADAAAAGAAYAHIAAAAYABgAigAAABIAEgBIAAAABgAGAFoAA

public String getUserId();
Returns the userId of the person logged in. The userId cannot be null.

Optional: After you generate your plug-in JAR file, test it with Process Designer by placing it in the <pd_install>/teamworks/eclipse/plugins/ directory and restarting Process Designer.
Make your custom plug-in JAR file available to new Process Designer installations:
1. Place the custom authenticator plug-in JAR files in the BPM\Lombardi\tools\designer\dropins directory.
2. Download Process Designer from the Process Center console. Process Center discovers new files in the dropins directory and includes them in the downloaded IBM Process Designer.zip file.
Optional: Make your custom plug-in JAR file available to existing Process Designer installations:
1. Ensure that the new plug-in JAR files are added to the BPM\Lombardi\tools\designer\dropins directory.
2. Uninstall Process Designer.
3. Download an updated Process Designer installation .zip file from the Process Center console.