BPM leverages both its own model of users and groups as well as leveraging the underlying WebSphere Application Server security sub-systems. User administration of the BPM private security is performed through the BPM Process Admin Console in the User Management section (see: Process Admin - User Management).

Unless you are running a pure sand-box development environment or simply are not concerned about security, one of the first tasks that should be performed against BPM after installation is changing the passwords for the default userids. BPM documents the default passwords and until those are changed from their default values, the system must be considered completely in-secure. A BPM TechNote was written on the subject:

  • 1448216 - How to Change the Default User Passwords (including tw_admin) on WebSphere Lombardi Edition

Some of the passwords needed for operation are stored in encoded formats in files on the file system within the sub directories associated with the BPM product configuration. These passwords are not encrypted but rather "re-arranged" so that a simple eyeball of the content of the file will not expose their values. If an administrator needs to know the value of the encoded password, a web site on the Internet can be used to enter the value and return the plain text representation. Note that nothing is known about this web site other than its existence so users beware:

Security Groups

Group management of the IBPM supplied private group system is performed in the BPM Process Admin Console under theUser Management > Group Management section.

A new group can be created by clicking upon the New Group link.

A dialog appears in which the name of the new group can be entered:

Once created, user members can be added to the group:

A dialog appears into which users can be selected and added:

Existing groups can be listed by typing in "spaces" or the prefix of the names to be shown.


A team is used to represent a set of users in your organization or enterprise locally within an application. Teams can be found in the Processes category within PD. The members of a Team are local to the application in which it is defined. Security Groups provide a global mechanism to define groups. It is key to understand that a Team is a logical group that does not exist outside of the concept of the Process App in which it is defined.

During the creation of a new Team, the name desired for the new group is prompted:

Once created, the details of the new Team can be seen. When newly created, a Team has no members associated with it.

Within the Members section is where we define who belongs to the team. The Members selection criteria can be one of three types:

  • Standard Members
  • Using Expression (Deprecated)
  • System (Deprecated)

Using the Standard Members selection, the members of the participant group are taken from the users and groups defined in the Process Admin Console or from the underlying WebSphere Application Server security system.

Since the other two types of Member selection are deprecated, we will no longer discuss these.

An alternative mechanism to define who are the members of a team is to click on the "Specify Team Using Service" check box. If selected, then the result of executing a BPM service will be used to determine who the members of the team are. The service has to have a specific signature and can be built from the "Team Retrieval Service Template".

This service has an input called "name" which is the name of the team who's members are to be determined. The service returns an output called "team" which is an instance of the Team business object. This defines who will be members of the team.

As well as supplying the members of a team, you can also determine who the manager or managers of the team will be. This is itself achieved by defining another team that can contain one or more members who will be considered the managers. From there you can then name that management team.

When a Task is added to a BPD, that task is added to a lane within the diagram. A default Team can be associated with that lane. Unless otherwise specified, that task will be associated with the members of the associated Team at run-time. Selecting the lane and viewing the properties allows us to select a Team:

From within the Process Admin Console, the set of users associated with a Team can be changed at run-time. To achieve this start the Process Admin Console and select Installed Apps:

A list of the installed application is shown. Select the application that contains the Participant Groups that are to be changed:

From there, a list of the Participant Groups can be found with their associated members within the Role Bindings section. Members can be added or removed.

Securing Access to the repository

The Process Center repository is secured as it hosts the projects within the enterprise. We typically do not want just anybody to either see the content of or make changes to our Process Applications. In the Admin section of the Process Center console, we can select to Manage Users. From here we can add new users and groups to the list of authorized users.

When the Add button is clicked, a dialog appears into which the additional users and groups can be added:

If a user wishes to login through PD, the user must be authorized to login or else the following error will be produced:

Notice that users and groups of users can also be removed from Process Center access. It is vital that this be done with care. If no users are defined to have Admin rights to Process Center then you have effectively locked yourself out. Simply put, don't do this. Take great care that this does not happen.

Securing development of a Process Application

Granting a user authority to access the Process Center allows them to login through the PD but this does not mean that they now have privileges to work on or even see all the Process Apps in the environment. Process Apps and Toolkits are individually controlled with their own access control lists. From within the Process Apps section of the PD or the Process Center Console, an application can be selected and the Manage tab selected. In there we have a section into which users and groups may be associated. These define the permissions for those entities.

There are three roles a user or group can have:

  • Read – This allows a user or group to see the project and see the artifacts within it. The read role can not be removed without removing the user or group association completely. If a user or group is not associated with the a Process App then the user or group has no authorities on that application. If an artifact is opened and the user only has Read authority, the artifact is flagged as Read-Only in the editor.

  • Write – This role allows the user or group to update or add artifacts into the Process Application.
  • Admin – This role allows the user or group to administer the Process Application.

Securing the ability to start an application

Typically, we do not wish just any arbitrary user to be able to start a new instance of a process application. Instead, we want to allow only sufficiently authorized users. In the Overview page of a BPD we can find a section called Exposing.

In there is an attribute called "Expose to start". This can be set to the name of a participant group. Only the members of this participant group will be allowed to start a process. If a user is not in this group, they will not be allowed to start the process:

Securing ability to work with tasks (Human Services)

An activity in the BPD has a Routing section. Within there, the names of the potential staff members who can work on the task are defined. If a user is in this list, then the task will appear in their process portal page and they can work upon it. If they don't appear in this list, then they can't work upon it.

Securing Process Portal capabilities

Many of the tasks of interacting with IBPM are performed through the Process Portal. We wish to control who can do what through this interface.

IBPM exposes a set of configuration parameters that define the role a user must have in order to be able to perform a function. The different functions available for configuration are:

Capability Description
ACTION_ABORT_INSTANCE Terminate an instance of a process.
ACTION_SUSPEND_INSTANCE Suspend an instance of a process.
ACTION_RESUME_INSTANCE Resume a previously suspended instance of a process.
ACTION_ADD_COMMENT Add a comment to an instance of a process.
ACTION_ADD_HELP_REQUEST Create a help request associated with this instance of a process.
ACTION_RESPOND_HELP_REQUEST Respond to a help request previously raised against a process.
ACTION_ASSIGN_TASK Assign the task to the current user making the request.
ACTION_ASSIGN_AND_RUN_TASK Run a task and assign it to the current user.
ACTION_REASSIGN_TASK Return the task to the original group to which it was originally assigned.
ACTION_REASSIGN_TASK_USER_ROLE Assign the task to a different user or role.
ACTION_CHANGE_TASK_DUEDATE Change the due date on a task.
ACTION_CHANGE_INSTANCE_DUEDATE Change the due date on a process instance.
ACTION_CHANGE_TASK_PRIORITY Change the priority of a task.
ACTION_MOVE_TOKEN Skip the current task in the BPD and move to the next one.
ACTION_INJECT_TOKEN Start an ad-hoc event. Note that by default, only admin users can start ad-hoc events. This trips up a lot of folks.
ACTION_VIEW_PROCESS_DIAGRAM Ability to view the process diagram.
ACTION_VIEW_PROCESS_AUDIT Ability to view historical data about process variables.
ACTION_CHANGE_CRITICAL_PATH Update the projected path in a Gantt chart.
ACTION_ADD_DOCUMENT Add a document (believed to be legacy).
ACTION_UPDATE_DOCUMENT Update a document (believed to be legacy).
ACTION_DELETE_DOCUMENT Delete a document (believed to be legacy).
ACTION_DELETE_INSTANCE Delete a process instance.
ACTION_FIRE_TIMER Manually fire a timer.

The configuration for these parameters previously was achieved via XML customizations and the instructions for that are shown later. However from 8.5 onwards, wsadmin scripting can be used to perform this task. There is an AdminConfig object called "BPMPolicyActions" that has methods on it to list, set and get values. This will probably be used to provide scripted or programmatic access. Fortunately, IBM has supplied a sample script to work with these options. The script can be found at <ROOT>/util/Security/ Asking it for its usage shows:

Usage: Use this script to get/modify the configured security properties.

       -E|--de DE_name -option
                       -g|--get property_name
                       -s|--set property_name , new_value
                       -a|--add console_property_name , constraint_value
                               |action_policy_name , role to be added
                       -r|--remove console_property_name , constraint_value
                               |action_policy_name , role to be removed

An example of running the command would be:

C:\IBM\BPM\v8.5\util\Security> wsadmin -f -lang jython -user kolban -password password -E De1 -g ACTION_ABORT_INSTANCE
WASX7209I: Connected to process "dmgr" on node Dmgr using SOAP connector;  The type of process is: DeploymentManager
WASX7303I: The following options are passed to the scripting environment and are available as arguments that are stored in the argv variable: "[-E, De1, -g, ACTION_ABORT_INSTANCE]"

Current value for property ACTION_ABORT_INSTANCE in DE De1 is:

The configuration settings for these capabilities are made in the 100Custom.xml file. The default settings can be found in the 99Local.xml file found in:


The default section in this XML file looks as follows:

		<action type="ACTION_ABORT_INSTANCE">
		<action type="ACTION_RESUME_INSTANCE">
		<action type="ACTION_ADD_COMMENT">
		<action type="ACTION_ADD_HELP_REQUEST">
		<action type="ACTION_ASSIGN_TASK">
		<action type="ACTION_ASSIGN_AND_RUN_TASK">
		<action type="ACTION_REASSIGN_TASK">
		<action type="ACTION_MOVE_TOKEN">
		<action type="ACTION_INJECT_TOKEN">

The <role> entry names a security group (see: Security Groups) which is a global group with defined members. If no <role> is defined within an action tag then all users are allowed to perform that action.

The following is an example of an entry that can be made in the 100Custom.xml file to change the authorities:

			<role>Test Group 1</role>

It is strongly recommended not to edit the content of the 99Local.xml file. Instead, edit the 100Custom.xml file and add/replace all changes there. When Process Server starts, it will merge the 99Local.xml with the 100Custom.xml producing a combined result. Editing only 100Custom.xml keeps all the changes in one place and aids in maintainability. Changes made to these configuration files don't take effect until after the next restart of the Process Server/Process Center.

Securing access to publish Integration Designer projects

In order to publish modules from Integration Designer, the connected user must have the WAS Administrative permissions of "deployer" or "configurator". If this is not set, an error similar to the following may be seen:

which isn't particularly helpful, however, if we were to look in the WAS logs, we might see messages similar to the following:

[5/7/15 12:40:07:649 CDT] 0000011e RoleBasedAuth A   SECJ0305I: The role-based authorization check failed for admin-authz operation Server:getState.  The user kolban (unique ID: user:defaultwimfilebasedrealm/uid=kolban,o=defaultwimfilebasedrealm) was not granted any of the following required roles: monitor, auditor, configurator, administrator, deployer, operator, adminsecuritymanager.

These can be set from the WAS admin console under Security > Global Security > Administrative Security:

Lightweight Directory Access Protocol - LDAP

LDAP is a commonly used registry of information and is typically used to hold organizational information including the definitions of users, passwords and group membership. WAS can leverage an LDAP server for management of users and passwords. IBM's implementation of LDAP is called IBM Tivoli Directory Server.

Tivoli Directory Server

As of August 2014, the latest version of Tivoli Directory Server is 6.3.

The installer for TDS looks as follows:

There is an executable called "install_tds" that can be found in the "tds" folder of the extracted installation parts.

Apache Directory Server

The Apache Directory Server is an implementation of LDAP completely written in Java and made available as Open Source. The home page for this free product is:

It is a relatively small download (9.8 Mbytes) and is self contained for execution. Once installed, here are some basic properties that are useful:

Userid uid=admin,ou=system
Password secret
Default port 10389

Installation of Apache Directory Server

What follows is a walk through of the installation of the Apache Directory Server.

When initially downloaded, the server comes as a single setup file.

Once launched, the common boiler plate is shown.

Next comes the license agreement. Read and accept if you agree.

There are installation choices, a Full setup is what is shown in this walkthrough.

The file system location where the Apache Directory Server is to be installed is configurable.

An LDAP directory contains data describing the structure of an organization. The location on the file system of where this data is stored can be configured.

The Apache Directory Server is written in Java and needs a Java runtime. The location of the Java runtime to be used must be supplied.

Finally, the installation progresses.

At the conclusion, a completion page is shown.

Apache Directory Server Studio

Another free Apache product is the Apache Directory Server Studio. This is a fantastic configuration tool for the Apache Directory Server and other LDAP servers.

Installation of Apache Directory Studio

The Apache Directory Studio can be found at

The download itself is about 136 Mbytes.

Installation of Apache Directory Server Studio Eclipse Plugins

Apache Directory Server Studio can be installed as a set of Eclipse plugins. This set of Eclipse plugins that can be installed into ID or RAD. This provides a set of LDAP maintenance tools as well as an in-built LDAP server that is excellent for development and testing.

It can be installed directly into ID through dynamic retrieval.

Web site for Eclipse plugins:

Go to Help >

For the download URL for the eclipse plugins, enter:

The packages will now be dynamically downloaded from the web and installed into WID.

Once installed, a new perspective called LDAP is available:

In addition to being able to work with external LDAP Servers, the Studio provides its own LDAP server instance. This provides the ability to quickly create an LDAP instance for testing but realize that once the studio has been shut down, the LDAP server shuts down too. It is probably much safer to run an LDAP server outside of the Studio.

To create a Studio hosted LDAP server, create a New Server definition.

Give the new server a name:

Provide any properties that are specific to the new server.

Start (run) the Server from the Servers panel.

Create a connection to the new server to access and populate it with content.

Installation of JXplorer

JXplorer is an Open Source GUI LDAP browser tool. If you don't install the Apache LDAP Directory Studio, this can provide a useful alternative. It can be found at:

A walk through of the installer is shown next.

First comes the basic welcome/setup screen.

The license agreement is shown next and should be read. If agreed, accept the license and continue.

The directory in which the tool will be installed is shown next.

Following this, installation is ready to progress.

After installation is complete, a summary is shown.

The tool can now be found in the Start Menu under the JXplorer folder.

Getting locked out of WAS

While configuring WAS for LDAP, if an error is made during this time, you might find yourself getting "locked out". This means that you can't login to WAS to perform repairs. The resolution to this is to stop the WAS server and temporarily switch off security. Unfortunately, if you have lost admin access to WAS, you won't be able to stop it cleanly. You will have to locate the process id at the operating system level of the Java JVM running WAS and kill it. Process Explorer is a good tool for finding the correct process ID and killing it.

Once WAS has been stopped, we can run a wsadmin command to disable security.

wsadmin -conntype NONE
wsadmin> securityoff
wsadmin> exit

When the WAS server is restarted, security will be off. Access to the WAS admin console can then be made through a browser at:


Configuring WAS for LDAP

If this is your very first time configuring a WAS server for LDAP, rather than shoot for gold with a full IBM BPM environment, I recommend creating a simple WAS stand-alone server for testing. Get it working with LDAP using the following notes and, once done, you can apply those same settings to your real server and then delete the test environment. Doing this will ensure that you don't regress your BPM environment and also since starts and stops of the server may be required, a simple server will start and stop much quicker than a full BPM environment.

In order to include an LDAP server in the mix of security repositories, configuration must be performed through the WAS Admin Console. Let us assume we have an Apache Directory server with base dn of ou=system.

We login to the WAS Admin console. In the Security settings, we select "Global security":

Next we click on the Configure... button associated with Federated repositories:

Click the Manage repositories link:

Click the Add button and select LDAP:

Enter values for the "Repository identifier", "Primary host name" and "port".

Back in the Global security page, click the Configure button again.

Click the Add repositories... button:

Ensure the correct repository is selected and now supply the root DN for the searches for this repository.

After we restart all the servers, it will now include our LDAP provider in the security story.

Adding Users

To define an actual user, we create an LDAP entry of type "inetOrgPerson" under ou=system. In the following screen shots we use Apache Directory Studio to achieve the task.

We click on the ou=system entry in the DIT and create a New Entry...

We wish to create our new entry from scratch.

Our new entry will be based on the class called "inetOrgPerson".

We give the new entry the RDN of uid=smith resulting in a fully distinguished name of uid=smith,ou=system.

There are some mandatory properties that need values including "cn" and "sn". Simply enter the name of the user. We must also add an optional attribute to hold the user's password. Click on the button to allow us to add a new attribute to this entry.

The attribute type we wish to add is called "userPassword".

We can give the password a value which will be the password the user will use to login to BPM.

After completion, we will see a new entry in the LDAP DIT.

Adding groups

Groups are added as entries of type "groupOfNames".

Debugging WAS LDAP

The wsadmin commands such as:

  • AdminTask.getUser
  • AdminTask.getGroup uniqueName securityDomainName clearCache
  • AdminTask.searchUsers
  • AdminTask.searchGroups securityDomainName description cn timeLimit countLimit clearCache

For example:

AdminTask.searchGroups('-cn *')

might be especially useful for examining whether or not users and groups can be resolved. It appears that these commands also have a "-clearCache clearEntity" and "-clearCache clearAll" options.

Configuring LDAP for IBPM

IBPM expects the following resources to be available:

  • user – tw_portal_admin
  • user – tw_user
  • group – teamworks_admin
  • group – teamworks_authors
  • group – tw_admins
  • group – TWSecurityProviderUsers

Debugging LDAP

If the authentication system being used by WebSphere is LDAP, then it can occasionally be useful to examine the requests and responses flowing to and from the LDAP server. TDS has a an audit log where one can see requests being sent to it but there is no obvious way to see the responses being returned. In addition, other LDAP providers may be used that you are not familiar with. A solution to tracing the LDAP flows is to use the package called SLAMD. Although this package is all about performance and load testing, as part of this package, in the tools folder, a tool called ldap-decoder is provided. This tool acts as a proxy/interceptor between an LDAP client and an LDAP server and displays LDAP queries and responses.

Here is a quick cheat sheet on using ldap-decoder. First, understand that it is a DOS command window tool and hence must be run from the DOS prompt. It sits between a real LDAP provider and a client (such as IBPM) that is making LDAP requests. When IBPM makes a query against LDAP, it is really making the request to ldap-provider. Ldap-decoder then forwards the request to the real LDAP provider which in turn sends a response back to the ldap-decoder tool. This in turn sends the response back to IBPM. This means that ldap-decoder sees both the requests to LDAP and the responses returned from LDAP. Ldap-decoder knows how to parse the LDAP data stream (which is binary) and displays the requests and corresponding responses in the DOS console window.

The ldap-decoder tool can be found in the tools sub folder of the slamd installation directory. Before starting the tool, edit the file called set-java-home.bat and change the JAVA_HOME environment variable to point to a Java runtime.

To run ldap-decoder, execute the following from the <slamd>/tools folder:

ldap-decoder -h LDAPProviderHostname -p LDAPProviderPort -L LocalListenPort

For example:

ldap-decoder -h localhost -p 10389 -L 10390

Ldap-decoder will then start listening on the LocalListenPort and when it receives a request, it will be forwarded to the LDAPProviderHostname at port LDAPProviderPort.

Importing Browser Certificates

When WAS is installed and configured, it generates self signed SSL certificates. This means that when a browser connects to the WAS server, the SSL certificate is not trusted forcing the user to accept the apparent issue through an intervening warning screen. This is inconvenient and there is a solution. What we have to do is export the trust root from WAS and import it into the browser.

  1. Open the WAS Admin Console
  2. Navigate to "Security > SSL certificate and key management > Key stores and certificates"

  1. Select the "NodeDefaultTrustStore"

  1. Select "Signer certificates"

  1. Select the entry called "default" and click "Extract"

  1. Export the file to a directory and file name you remember. The file type should be ".cer".

  1. Open up Chrome and visit its settings page. Click on the "Show advanced settings..." expansion and click on the "Manage certificates..." button.

  1. Click to the "Trusted Root Certification Authorities" tab and click the "Import..." button.

  1. Pass through the welcome screen. In the "Certificate Import Wizard", supply the file name you previously saved for the exported certificate.

  1. Ensure that the certificate store is "Trusted Root Certification Authorities".

  1. You will now see a review screen. Click "Finish". A security warning will appear similar to the following. It must be accepted.

  1. We can verify that the certificate has been installed:

When accessing WAS via a browser, we must use the WAS servers real hostname and not localhost. The certificate is not signed for localhost.

Security and browser sessions

When working with browsers which login to WAS, the current security credentials are stored as Cookies by the browser. This means that once we establish a login context with WAS in a browser session, we can make multiple requests back and forward. This works great. However, there are times when we might wish two browser windows open (which is the same as having two tabs open) where one window is logged in as one user and another window is logged in as a different user. Unfortunately, we run into trouble here. The reason is that both windows share the same Cookie value and hence the last user that signs in sets the value of the Cookie which can either break or invalidate the other window. This can obviously make our workflow more difficult as it would appear that we would have to restrict our browser usage to only a single browser. Fortunately, there is a solution. When we start a browser, we can ask (or switch) to a logical different browser user. This means that there are separate definitions (cookie values) for each of the different browser users. Here is how to achieve that in Chrome.

  1. Start the Chrome browser and switch to the browser settings:

Open up the Settings dialog:

Add a new user ...

  1. Give the new user a name:

and click the Create button

  1. Switch users as needed:

You will now find that your Chrome has an Icon in the upper left that shows you your current Browser user and allows you to switch between them in different windows:

Using this recipe you can now have two browser windows both of which can be logged into WAS servers with distinct user ids and not tread on each other.

No Comments
Back to top