Administering the technical user for the IBM BPM document store

When working with the IBM BPM document store, there are multiple scenarios that require a technical user (system user). The technical user is an identity that the system can use to act on its own. For example, a run-as technical user is required for creating default configurations for the domain, object store, and document class definition. A technical user is also required when IBM Business Process Manager connects to the IBM BPM document store using Content Management Interoperability Service (CMIS).

Before you begin

The maintainDocumentStoreAuthorization and updateDocumentStoreApplication commands are used to perform many of the tasks in this topic. The commands are run using the AdminTask object of the wsadmin scripting client. To run the commands, the following conditions must be met:

maintainDocumentStoreAuthorization command:
- The command must be run on the deployment manager node.
- One or more application cluster members must be running.
- Run the command in connected mode. Do not specify the wsadmin -conntype none option.
- You must connect to the deployment manager with a user ID that has WebSphere Application Server operator privileges.
updateDocumentStoreApplication command:
- The command must be run on the deployment manager node.
- Run the command in either local or connected mode.
- When running the command in connected mode, you must specify a user ID that has WebSphere Application Server operator and deployer privileges.

For the maintainDocumentStoreAuthorization command, start the wsadmin scripting client from the profile_root/bin directory of the deployment manager profile (or the stand-alone server profile of IBM BPM Express). For the updateDocumentStoreApplication command, start the wsadmin scripting client from the deployment_manager_profile/bin directory on either IBM Process Server or Process Center. The commands do not write to a log file, but the wsadmin scripting client always writes a profile_root/logs/wsadmin.traceout log file where you will find exception stack traces and other information.

About this task

For all of these scenarios, the same technical user is used and the credentials are saved in an authentication alias. The authentication alias that is used is the one that is mapped to the IBM BPM role type EmbeddedECMTechnicalUser. The default authentication alias is DeAdminAlias, but the authentication alias may have been customized during the configuration of the deployment environment. The technical user must have the WebSphere Application Server administrator role. Information about using the administrative console to manage authentication aliases is found in the "Authentication alias" topic.

During the maintenance of a running system, the following tasks may need to be performed:

Changing the password of the technical user
Changing the technical user
Changing the authentication alias for the technical user
Reconfiguring the user registry
Security configuration for IBM® BPM content store

These tasks are described in the following sections.

Changing the password of the technical user

The credentials of the technical user are saved in an authentication alias. The password of the technical user in the authentication alias must be changed together with the password in the user repository where the technical user is defined (such as FileRegistry or LDAP).

Note: The IBM BPM document store may still use the old credentials for a short period of time (less than a minute). Access to the IBM BPM document store may fail in this short timeframe.

Changing the technical user

To change the password or change the technical user, it is not sufficient to simply change the authentication alias. The IBM BPM document store is protected against access from unknown users. If a different technical user must be used, the user that will become the technical user must first be authorized. To accomplish this task, use the maintainDocumentStoreAuthorization admin command with the -add option to authorize the new user, as shown in the following example:

AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -add cn=newTechnicalUser,o=defaultWIMFileBasedRealm]')

You can list the currently authorized principals by using the same admin command and the -list option, as shown in the following example:

AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -list]')

Alternatively, you can authorize groups to access the IBM BPM document store.

After the new technical user is authorized for the IBM BPM document store, you can modify the authentication alias with the new principal name and password of the technical user.

Note: The BPM document store may still use the old credentials for a short period of time (less than a minute). Access to the IBM BPM document store should not fail in this short timeframe because the old technical user is still authorized to access the IBM BPM document store.

As a last step, you can remove the access of the old user using the maintainDocumentStoreAuthorization admin command and the -remove option, as shown in the following example:

AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -remove cn=oldTechnicalUser,o=defaultWIMFileBasedRealm]')

Remember: The access for the user is revoked at the domain, object store, and root folder level, but permissions on some objects in the content store are not removed. This is consistent with other products that use the content store. Because access for the user is revoked at the domain, object store, and root folder level, that user should not be able to gain access to any objects in the object store after the revoke.

If you change the technical user then a change to the application settings of IBM_BPM_DocStoreAdmin is required to allow the new technical user to access the IBM Administrative Console for Content Platform Engine.

Changing the authentication alias

In the deployment environment configuration, you can also change the authentication alias that is mapped to the EmbeddedECMTechnicalUser role. After changing the authentication alias, you must run the updateDocumentStoreApplication admin command to prevent the IBM BPM document store from using the old authentication alias:

AdminTask.updateDocumentStoreApplication('[-deName myDEname]')

Note: If your new authentication alias uses a different user from the original user, you must also follow the instructions in the above section "Changing the technical user."

Reconfiguring the user registry

Authorization to the IBM BPM document store is based on unique IDs. If the IBM BPM document store was initialized during initial server startup, only the same user (with the same unique ID) can manage the IBM BPM document store and access its documents. If you change your user registry configuration (for example, by removing the file-based repository in order to use only an LDAP server in federated repositories), a user with the same user ID and password in LDAP will not have access to the IBM BPM document store. This is also true if you simply delete a user and recreate one with the same user ID. In this situation, you lose access to the IBM BPM document store and you must rollback the configuration change.

Duplicate users are not permitted in federated repositories, which means that you cannot connect to an LDAP server that contains the same users that you have in your file-based repository. You must remove the file-based and add LDAP. A user in LDAP with the same user ID does not have access to the IBM BPM document store. As a result, you may choose to authorize all authenticated users to work with the IBM BPM document store for the duration of reconfiguration (while access has been shut down through the HTTP server).

You can use the special key word #AUTHENTICATED-USERS to authorize all users to the IBM BPM document store who successfully authenticate, as shown in the following example:

AdminTask.maintainDocumentStoreAuthorization('[-deName De1 -add #AUTHENTICATED-USERS]')

When all users are allowed to communicate with the document store, remove the user or group that is going to be deleted from the user repository.

After this configuration has been completed, you can safely re-configure your user registry without losing access to the IBM BPM document store. After the configuration change is complete and the cell is restarted, you can authorize a new user and remove the #AUTHENTICATED-USERS entry.

Security configuration for IBM BPM content store

The IBM BPM content store is used for document attachments and case management applications. You can only develop case management applications with IBM Business Process Manager Advanced. When you add or remove an administrator, many objects and metadata need to be updated. For better efficiency, you should create a Lightweight Directory Access Protocol (LDAP) group as an administrator. Then you can use the LDAP and directory tools to add and remove administrators as needed; that is, by managing the LDAP group membership.