Administering the technical user for the BPM document store

Edit online
Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15
When working with the 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 Automation Workflow connects to the BPM document store using Content Management Interoperability Service (CMIS).

Before you begin

The maintainDocumentStoreAuthorization and updateDocumentStoreApplication commands perform many of the tasks in this topic. Run the commands with the AdminTask object of the wsadmin scripting client. The following conditions must be met:

  • maintainDocumentStoreAuthorization Command:
    • Run the command on the deployment manager node.
    • Ensure that one or more application cluster members are running.
    • Run the command in connected mode. Do not specify the wsadmin -conntype none option.
    • Connect to the deployment manager with a user ID that has WebSphere® Application Server operator privileges.
  • updateDocumentStoreApplication Command:
    • Run the command on the deployment manager node.
    • Run the command in either local or connected mode.
    • When you run the command in connected mode, 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. For the updateDocumentStoreApplication command, start the wsadmin scripting client from the deployment_manager_profile/bin directory on either Workflow Server or Workflow Center. The commands do not write to a log file. However, the wsadmin scripting client writes a profile_root/logs/wsadmin.traceout log file. You find exception stack traces and other information in this log file.

About this task

All scenarios use the same technical user. The credentials are saved in an authentication alias. The authentication alias is mapped to the Business Automation Workflow role type EmbeddedECMTechnicalUser. The default authentication alias is DeAdminAlias. However, the authentication alias might be customized during the configuration of the deployment environment. The technical user requires the WebSphere Application Server administrator role. For information about managing authentication aliases with the administrative console, see Modifying authentication aliases.

During system maintenance, perform the following tasks as needed:
  • Changing the password of the technical user
  • Adding a new technical user
  • Changing the authentication alias for the technical user
  • Reconfiguring the user registry

The following sections describe these tasks.

Changing the password of the technical user

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

To change the password of the technical user, complete the following steps:

  1. Stop the application servers.
  2. Identify the authentication alias that is mapped to the EmbeddedECMTechnicalUser role. In the WebSphere Application Server administrative console, navigate to Servers > Deployment Environments > myDEname > Authentication aliases.
  3. Change the password of the user that is associated with the authentication alias that you identified in step 2. In the WebSphere Application Server administrative console, navigate to Security > Global Security > Java Authentication and Authorization Service > J2C authentication data.
  4. Change the password for the relevant user in the user registry:
    • If you are using an embedded Content Platform Engine, change the password in the Manage Users section in the WebSphere Application Server administrative console.
    • If you are using an external Content Platform Engine that uses LDAP, change the password at the LDAP level.
  5. Change the password for the admin user in the IBM Administration Console for Content Platform Engine (ACCE):
    1. Log in to the ACCE (https://BAW_host:BAW_port /acce).
    2. Click BPM domain. Click the Properties tab and change the values for the System User Name and System User Password. Click Save.
  6. Start the application servers.
Note: The BPM document store might still use the old credentials for a short period (less than a minute). Access to the BPM document store might fail in this short time frame.

Adding a new technical user

Changing the authentication alias alone is not sufficient to change the technical user. The BPM document store is protected against access from unknown users. If you use a different technical user, authorize the new user first. Use the maintainDocumentStoreAuthorization admin command with the -add option to authorize the new user. See the following example:
AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -add cn=newTechnicalUser,o=defaultWIMFileBasedRealm]')
Important: The maintainDocumentStoreAuthorization command updates the permissions for the new technical user, but does not map the new technical user to the system user in ACCE. To map the new technical user, complete step 5 in Changing the password of the technical user.
To list the currently authorized principals, use the same admin command with the -list option. See the following example:
AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -list]')

Alternatively, authorize groups to access the BPM document store.

After you authorize the new technical user for the BPM document store, modify the authentication alias with the new principal name and password of the technical user.
Note: The BPM document store might still use the old credentials for a short period (less than a minute). Access to the BPM document store does not fail in this short time frame. The old technical user is still authorized to access the BPM document store.
As a final step, remove the access of the old user. Use the maintainDocumentStoreAuthorization admin command with the -remove option. See the following example:
AdminTask.maintainDocumentStoreAuthorization('[-deName myDEname -remove cn=oldTechnicalUser,o=defaultWIMFileBasedRealm]')
Remember: Access for the user is revoked at the domain, object store, and root folder level. However, permissions on some objects in the content store are not removed. This behavior is consistent with other products that use the content store. After the revoke, the user cannot gain access to any objects in the object store.

If you change the technical user, change the application settings of IBM_BPM_DocStoreAdmin. This change allows the new technical user to access the IBM Administration Console for Content Platform Engine (ACCE). When you create the Business Automation Workflow deployment environment, the DE admin user becomes the admin user for the embedded IBM Content Navigator and Content Platform Engine components. The Business Automation Workflow server uses the DE admin user to connect to these components.

Changing the authentication alias

In the deployment environment configuration, change the authentication alias that is mapped to the EmbeddedECMTechnicalUser role. To map the new authentication alias to the EmbeddedECMTechnicalUser role, see step 2 in Changing the password of the technical user.

After you change the authentication alias, run the updateDocumentStoreApplication admin command. This command prevents the BPM document store from using the old authentication alias:
AdminTask.updateDocumentStoreApplication('[-deName myDEname]')
Important: If your new authentication alias uses a different user from the original user, you must also follow the instructions in the Changing the technical user section. The updateDocumentStoreApplication command does not apply to environments configured with an external Content Platform Engine.

Reconfiguring the user registry

Authorization to the BPM document store is based on unique IDs. If the document store was initialized during initial server startup, only the same user (with the same unique ID) manages the document store and accesses its documents. If you change your user registry configuration (for example, remove the file-based repository to use only an LDAP server in federated repositories), a user with the same user ID and password in LDAP does not have access to the document store. This behavior also occurs if you delete a user and re-create one with the same user ID. In this situation, you lose access to the document store. Roll back the configuration change.

Duplicate users are not permitted in federated repositories. You cannot connect to an LDAP server that contains the same users in your file-based repository. Remove the file-based repository and add LDAP. A user in LDAP with the same user ID does not have access to the document store. As a result, authorize all authenticated users to work with the document store during reconfiguration. Shut down access through the HTTP server during this time.

Use the special keyword #AUTHENTICATED-USERS to authorize all users who successfully authenticate to the document store. See 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 from the user repository.

After you complete this configuration, reconfigure your user registry without losing access to the document store. After you complete the configuration change and restart the cell, authorize a new user and remove the #AUTHENTICATED-USERS entry.

For information about configuring the user registry, see Configuring the user registry.