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 CMIS.

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

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]')

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 need to 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 than 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 need to 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 need to 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]')

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 old user as well as the #AUTHENTICATED-USERS entry.