JR48172: PROVIDE ADMIN SCRIPTS TO SYNCHRONIZE USERS AND GROUP MEMBERSHIPS BETWEEEN VMM INCLUDING LDAP DIRECTORIES AND THE BPM DB

Version 8.5 Refresh Pack 5 for the IBM Business Process Manager products
Download Version 8.0.1 Fix Pack 3 for the IBM Business Process Manager products
Version 8.5.0 Fix Pack 2 for the IBM Business Process Manager products

APAR status

• Closed as new function.

Error description

• Currently, the set of available users can be synchronized from
  VMM to the BPM DB using the Process Admin Console.
  This mechanism is not performant enough for a large number of
  users and an administrative approach is missing.
  In addition, there is no mechanism available to synchronize
  group memberships from VMM to the BPM DB.
  For both aspects, corresponding administrative scripts are
  requried.
  

Local fix

• N/A
  

Problem summary

• For large numbers of users in the user registry, the provided
  mechanism to synchronize user availability between the user
  registry and the BPM DB may require long execution times.
  No administrative mechanism is provided to synchronize group
  membership for users between the user registry and the BPM DB.
  
  PROBLEM DETAILED DESCRIPTION:
  Currently, user availability can be synchronized between the
  user registry and the BPM DB by issuing corresponding commands
  via the Process Admin Console. For large numbers of users
  command execution can last long.
  In addition, there are no administrative means to trigger the
  synchronization of group membership for users between the
  user registry and BPM DB.
  For both aspects of synchronization, administrative scripts are
  required.
  

Problem conclusion

• NOTE: All scripts below may imply execution times which exceed
  the default timeout setting for wsadmin script execution.
  Change the default to reflect the execution time required in
  your set-up. For this, open the file
  
  <install-root>/profiles/<profile>/properties/soap.client.props
  
  and change the value for com.ibm.SOAP.requestTimeout, e.g. set
  it 0 to imply no timeout.
  
  NOTE: consider executing the scripts during idle time, as they
  may impose a high load on the system.
  
  I. User synchronization
  
  Two new administrative scripts are provided to trigger user
  synchronization between the user registry and the BPM DB.
  Versions are available for both Windows and Linux environments
  and can be found at the location:
  <install-root>/profiles/<profile>/bin
  
  a. To synchronize a set of specified users, use the following
  script:
    usersSync.[bat|sh] [options...] <userID1> <userID2> ...
    <userIDn>
  
  Options:
  -?, -help                            This help message
  -u <username>, -username <username>  user name of admin user
  -p <password>, -password <password>  user password (unencrypted)
  -host <host>                         server host name, must be
                                       used with port
  -port <port>                         server SOAP port number
  
  userIDn: a list of user IDs which are to be synchronized.
  
  To execute the script, switch to the directory containing the
  script and trigger the execution.
  The script execution result indicates the number of synchronized
  users.
  Users that are not available in the user registry are skipped
  from synchronization.
  
  b. To synchronize all users in the user registry, use the
  following script:
  
  usersFullSync.bat [options...]
  
  Options:
  -?, -help                            This help message
  -u <username>, -username <username>  user name of admin user
  -p <password>, -password <password>  user password (unencrypted)
  -host <host>                         server host name, must be
                                       used with port
  -port <port>                         server SOAP port number
  
  To execute the script switch to the directory containing the
  script and trigger the execution.
  The script execution result indicates the number of synchronized
  users.
  
  NOTE: consider with care executing usersFullSync as it will
  insert ALL users available from the WAS user repository into
  the BPM DB.
  
  For increased performance, both scripts employ VMM interface
  calls, in case Federated Repositories (aka VMM) are configured
  for security.
  
  If VMM is used along with LDAP directories, tune your LDAP
  configuration in wimconfig.xml to allow for potentially
  retrieving all users in one VMM query. Consult the VMM tuning
  documents. In particular, select an appropriate setting
  for configurationProvider->maxSearchResults and consider
  adapting other values, e.g. ldapServers->connectTimeout,
  attributesCache->cacheSize.
  
  The wimconfig.xml file is located at
    <install-root>/profiles/<profile>/config/cells/<cell>
      /wim/config/wimconfig.xml
  (in a cluster, on the Deployment Manager for every server of the
  cluster).
  
  II. Group membership synchronization
  
  Two new administrative scripts are provided to trigger
  synchronization for (direct and indirect) user members of groups
  between the user registry and the BPM DB.
  Versions are available for both Windows and Linux environments
  and can be found at the location:
  <install-root>/profiles/<profile>/bin
  
  NOTE: synchronization for group membership takes into account
  users that
  a. are already in the BPM DB and
  b1. either have logged in BPM, after installing this ifix
  b2. or have been synchronized to BPM using one of the above user
  synchroniztation scripts.
  All other users will not be considered as group members, when
  applying the synchronization scripts for group membership.
  Consider with care, whether your set-up is appropriate for using
  the scripts.
  
  a. To synchronize group membership for the resolved (direct and
  indirect) user members of a set of specified groups, use the
  following script:
    syncGroupMembershipForGroups.[bat|sh] [options...]
      <groupName1> <groupName2> ... <groupNameN>
  
  Options:
  -?, -help                            This help message
  -u <username>, -username <username>  user name of admin user
  -p <password>, -password <password>  user password (unencrypted)
  -host <host>                         server host name, must be
                                       used with port
  -port <port>                         server SOAP port number
  
  groupNames: a list of group names the members of which are to be
  updated for membership.
  
  Note that, in the context of a group, the group membership is
  synchronized for the members of the group with respect to this
  group.
  
  To execute the script, switch to the directory containing the
  script and trigger the execution.
  The script execution result indicates the number of synchronized
  groups.
  Groups can be skipped from synchronization for a number of
  reasons:
  - groups are not available in the user registry
  - groups with a (short) name occuring more than once in the user
  registry
  - groups that are already defined with the same (short) name in
  BPM as non-security groups (e.g. groups created via the Process
  Admin Console)
  
  b. To synchronize group membership for the user members of all
  available groups, use the following script:
  syncGroupMembershipForAllGroups.[bat|sh] [options...]
  
  Options:
  -?, -help                            This help message
  -u <username>, -username <username>  user name of admin user
  -p <password>, -password <password>  user password (unencrypted)
  -host <host>                         server host name, must be
                                       used with port
  -port <port>                         server SOAP port number
  
  To execute the script switch to the directory containing the
  script and trigger the execution.
  The script execution result indicates the number of synchronized
  groups.
  Groups can be skipped from synchronization for a number of
  reasons:
  - groups with a (short) name occuring more than once in the user
  registry
  - groups that are already defined with the same (short) name in
  BPM as non-security groups (e.g. groups created via the Process
  Admin Console)
  
  For increased performance, both scripts employ VMM interface
  calls, in case Federated Repositories (aka VMM) are configured
  for security.
  
  The scripts require that the VMM entity type Group is extended
  to include an additional property representing
  either
  a. the set of (direct and indirect) user members of the group
  (referred to below as "groupusermember")
  or
  b. the set of direct (user or subgroup) members of the group
  (referred to below as "groupmember").
  
  Perform the configuration steps listed below:
  
  1. Check whether attached LDAP directories expose for a group
  entry an attribute listing all (direct or indirect) user
  members. For instance, the Tivoli Directory Server exposes
  for a group entry the "ibm-allmembers" attribute which can be
  directly queried to retrieve all user members of the group.
  
  If such an attribute exists, make sure it is configured for user
  member retrieval (see step 3 below).
  
  In case no such attribute exists, use in the steps below the
  LDAP attribute by which (user or subgroup) members of a
  group entry are identified in the LDAP directory, for instance
  "members" or "uniqueMembers".
  
  2. Define a VMM property for identifying either
  a. all user members of a Group entity
  or
  b. the direct user and subgroup members of a Group entity.
  
  Extend the VMM entity type Group to include an additional
  property with name "groupusermember" or "groupmember".
  For this, include or extend the file wimxmlextension.xml (in a
  cluster, on the Deployment Manager for every server of the
  cluster) at the location
  <install-root>/profiles/<profile>/config/cells/<cell>/wim/model
  
  The file is to contain the extension definition:
  <sdo:datagraph xmlns:sdo="commonj.sdo"
      xmlns:wim="http://www.ibm.com/websphere/wim">
    <wim:schema>
   <wim:propertySchema nsURI="http://www.ibm.com/websphere/wim"
    dataType="STRING" multiValued="true"
    propertyName="groupusermember">
   <wim:applicableEntityTypeNames>Group
    </wim:applicableEntityTypeNames>
      </wim:propertySchema>
    </wim:schema>
  </sdo:datagraph>
  
  or
  
  <sdo:datagraph xmlns:sdo="commonj.sdo"
      xmlns:wim="http://www.ibm.com/websphere/wim">
    <wim:schema>
   <wim:propertySchema nsURI="http://www.ibm.com/websphere/wim"
    dataType="STRING" multiValued="true"
    propertyName="groupmember">
   <wim:applicableEntityTypeNames>Group
    </wim:applicableEntityTypeNames>
      </wim:propertySchema>
    </wim:schema>
  </sdo:datagraph>
  
  
  3. For every LDAP directory configured for VMM, define the
  mapping between the VMM property name "groupusermember" or
  "groupmember" and the corresponding available LDAP attribute,
  e.g.  "ibm-allMembers" or "uniqueMembers", repectively.
  
  For this, include in
    <install-root>/profiles/<profile>/config/cells/<cell>
     /wim/config/wimconfig.xml
  (in a cluster, on the Deployment Manager for every server of the
  cluster) the entry:
  
  <config:repositories xsi:type="config:LdapRepositoryType" ...>
   ...
   <config:attributeConfiguration>
   ...
   <config:attributes name="ibm-allMembers"
  propertyName="groupusermember">
     <config:entityTypes>Group</config:entityTypes>
   </config:attributes>
   ...
    </config:attributeConfiguration>
  </config:repositories>
  
  or
  
  <config:repositories xsi:type="config:LdapRepositoryType" ...>
   ...
   <config:attributeConfiguration>
   ...
   <config:attributes name="uniqueMembers"
  propertyName="groupmember">
     <config:entityTypes>Group</config:entityTypes>
   </config:attributes>
   ...
    </config:attributeConfiguration>
  </config:repositories>
  
  4. For every LDAP directory configured for VMM, tune your LDAP
  configuration in wimconfig.xml to allow for potentially
  retrieving all groups in one VMM query. Consult the VMM tuning
  documents.
  In particular, select an appropriate setting for
  configurationProvider->maxSearchResults and consider adapting
  other values, e.g. ldapServers->connectTimeout,
  attributesCache->cacheSize.
  
  5. Enable using the "groupusermember" or "groupmember" property
  by BPM.
  Include in 100Custom.xml (in a cluster, on the Deployment
  Manager for every server of the cluster) the entry:
   <common merge="mergeChildren">
    <security>
     <vmm-options>
      <group-user-member-prop>groupusermember
       </group-user-member-prop>
     </vmm-options>
    </security>
   </common>
  
  or
  
   <common merge="mergeChildren">
    <security>
     <vmm-options>
      <group-member-prop>groupmember</group-member-prop>
     </vmm-options>
    </security>
   </common>
  
  The file is located at
    <install-root>/profiles/<profile>/config/cells/<cell>
     /nodes/<node>/servers/<server>
     /process-center|process-server/config
  (in a cluster, on the Deployment Manager for every server of the
  cluster).
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

• Fixed component name

  BPM STANDARD

• Fixed component ID

  5725C9500

Applicable component levels

• R801 PSY

     UP