Configuring the user registry

To use an external security provider, you must add the provider to the federated repository. Several types of repositories are supported, including the local operating system registry, a standalone Lightweight Directory Access Protocol (LDAP) registry, a standalone custom registry, and federated repositories.

About this task

The default installation of IBM® Business Process Manager provides a federated repository that contains the WebSphere® Application Server file registry.

The following steps show an example of configuring an LDAP security provider (such as Microsoft Active Directory) with the federated repository. For more information about how to configure other supported repositories, such as IBM Security Directory Suite (formerly IBM Tivoli Directory Server), refer to the Configuring LDAP as the user account registry section of the IBM Business Process Manager V7.5 Production Topologies IBM Redbook.

Note: IBM recommends that you configure the LDAP security provider using a federated repository (also referred to as virtual member manager).

Restriction:

You must search for users by the user ID in stand-alone LDAP user repositories. Searching for users by user first name or last name is not supported in this configuration.
If you are using Active Directory as a user repository, and you search for a user name that contains a letter with a diacritical mark, the search will ignore the diacritical mark and will return all user names that contain the character, regardless of whether the character has a diacritical mark. For example, a search on user names that contain the letter e with an accent mark will return not just those user names, but also user names that include e with any other accent mark or e with no accent mark.

Important: The connection with an embedded Enterprise Content Management (ECM) system might be lost if users are deleted and recreated. Refer to Administering the technical user for the IBM BPM document store.

In the LDAP configuration, you can specify one or multiple login properties, such as uid and mail, to allow users to log in to WebSphere Application Server. To give an example, for the following LDAP entry: uid=john1; cn=John Doe; mail=john@company.com, if you specified uid and mail as the login properties, the user can log in with john1 and john@company.com but not with John Doe. Values of login properties must be unique across all repositories participating in a realm. For example, do not use cn as a login property because it might not be unique. The first login property must also be stable. For example, mail is not a stable property because its value can change for events such as a marriage or divorce. The login properties are specified by using the WebSphere Application Server administrative console.

Note: The first login property becomes the user name in the IBM Business Process Manager database. This property must not change. If you change the first login property, it results in the creation of a new user name and a duplicate user entry in the IBM Business Process Manager database. In the example, john1 is the value of the first login property and is the user name in the IBM Business Process Manager database. But, if the first login property changes from uid to mail, the next time the user is synchronized, another entry is created for the user name john@company.com in the IBM Business Process Manager database. Additionally, the next time John logs in, he will not see any of the tasks that were assigned to him prior to the change as he is now considered a new (unrelated) user.

Procedure

Log in to the WebSphere Application Server administrative console.
Click Security > Global security.
Under User account repository, select Federated repositories from the list of Available realm definitions.
Click Configure.
Under Related items, click Manage repositories.

Click Add > LDAP Repository and specify parameters for the provider that you want to add. For example, to add Microsoft Active Directory, specify values such as the following examples:

Table 1. Parameters for adding a provider
Parameter	Example values
Repository identifier	`SALOMLDAP // change to suit`
Directory type	`Microsoft Windows Active Directory`
Primary host name	`10.1.5.18`
Bind distinguished name	`cn=LDAP_USER,CN=Users,DC=COMPANYQA,DC=com`
Bind password	`pwsaaswp`

Click OK and then Save.

On the Federated repositories page, click Add Base entry to Realm and specify values such as the following examples:

Table 2. Parameters for adding a base entry to a realm
Base entry name	Example values
Distinguished name of a base entry that uniquely identifies this set of entries in the realm	`cn=Users,DC=COMPANYQA,DC=com`
Distinguished name of a base entry in this repository	`cn=Users,DC=COMPANYQA,DC=com`

Click OK and then Save.
If your external security provider (LDAP) contains many entries, you must increase the maximum number of search results in federated repositories. A full synchronization queries all entries in LDAP. This process is limited by the maximum search value in the wimconfig.xml. In WebSphere Application Server, the default maximum search results is 4500 entries. This value is not the maximum number of LDAP users or groups that WebSphere Application Server can handle; rather, it is the maximum number that is returned based on the configuration value in the wimconfig.xml file. Check the SystemOut.log file for the CWWIM1018E error code. If you have this issue, you can increase the maximum search results in the wimconfig.xml file as described in the MaxResultsExceededException occurs during LDAP repository search topic in the WebSphere Application Server Information Center. After the change, restart the IBM BPM servers, then complete a full synchronization
On the Global Security page, click Set as current and then click Apply.
Shut down all IBM BPM servers. For a network deployment environment, you must shut down all of the servers, node agents, and deployment manager.
Make sure that no duplicate users exist in the WebSphere Application Server file registry and the security provider that you just added. If duplicate users exist, errors will occur when you run IBM Business Process Manager product components.

Although you do not necessarily need to set any Virtual Member Manager (VMM) properties, you can use the 100Custom.xml file to set one or more of the VMM properties in the following table (if the properties are applicable to your environment):

Table 3. IBM Business Process Manager VMM properties
Property	100Custom.xml structure	Description
user-full-name-prop	`<common merge="mergeChildren"> <security> <vmm-options> <user-full-name-prop>cn </user-full-name-prop> </vmm-options> </security> </common>`	The LDAP displayname attribute is no longer automatically retrieved for use as the fullName by IBM Business Process Manager. A user's full name is now derived from the LDAP cn attribute. However, if you still want to derive a user's full name from the displayname attribute, you can use the user-full-name-prop property. The default value for this property is `cn`. For more information about this property, see the topic Retrieving a user's full name in an easier-to-read format.
normalize-whitespaces-for-distinguished-names-prop	`<common merge="mergeChildren"> <security> <vmm-options> <normalize-whitespaces-for-distinguished-names-prop>true </normalize-whitespaces-for-distinguished-names-prop> </vmm-options> </security> </common>`	Enables or disables the action of detecting and removing white spaces in distinguished names in a VMM LDAP repository. The default value for this property is `true`. For more information about this property, see the topic Configuring IBM BPM to handle white space and letter case variations in the LDAP server
normalize-case-for-distinguished-names-prop	`<common merge="mergeChildren"> <security> <vmm-options> <normalize-case-for-distinguished-names-prop>INSQL </normalize-case-for-distinguished-names-prop> </vmm-options> </security> </common>`	Enables or disables the action of normalizing capitalization in distinguished names in a Virtual VMM LDAP repository. The default value for this property is `INSQL`. For more information about this property, see the topic Configuring IBM BPM to handle white space and letter case variations in the LDAP server
group-user-member-prop	`<common merge="mergeChildren"> <security> <vmm-options> <group-user-member-prop>groupusermember </group-user-member-prop> </vmm-options> </security> </common>`	Configures IBM Business Process Manager and VMM by using a group membership property that reflects all users in a group. There is no default value for this property. For more information about this property, see the topic Configuring IBM BPM and VMM by using a group membership property that reflects all users in a group.
group-member-prop	`<common merge="mergeChildren"> <security> <vmm-options> <group-member-prop>groupmember </group-member-prop> </vmm-options> </security> </common>`	Configures IBM Business Process Manager and VMM by using a group membership property that reflects direct users in a group. There is no default value for this property. For more information about this property, see the topic Configuring IBM BPM and VMM by using a group membership property that reflects direct users in a group.
group-name-prop	`<common merge="mergeChildren"> <security> <vmm-options> <group-name-prop>cn </group-name-prop> </vmm-options> </security> </common>`	Specifies the name of the property in federated repositories that is considered the group name. This property can be mapped to an attribute with different names in multiple connected repositories. The default value for this property is `cn`.
user-id-prop	`<common merge="mergeChildren"> <security> <vmm-options> <user-id-prop>principalName </user-id-prop> </vmm-options> </security> </common>`	Specifies the name of the property in federated repositories that is considered the user ID. The default value for this property is `principalName`. The default value automatically maps to the first login property in each of the federated repositories. This is the correct value, but the value is still configurable for backwards compatibility.
threshold-for-existing-user-retrieval-mode	`<common merge="mergeChildren"> <security> <vmm-options> <threshold-for-existing-user-retrieval-mode>1000 </threshold-for-existing-user-retrieval-mode> </vmm-options> </security> </common>`	Determines whether calls to VMM are done for each user or as one call for all users. The default value for this property is `1000`, which indicates 1000 available users. For more information about this property, see the topic Synchronizing users.

Additional information about LDAP properties is found in the topic Security configuration properties. For information about the attributes in the user registry that are replicated and the elements of the registry that must be unique and stable, see the topic Synchronizing users and groups.

Start all IBM BPM servers. For a network deployment environment, you must restart all of the servers, node agents, and deployment manager.
If you have configured a server cluster for your runtime environment, stop and restart all servers in the cluster.