Virtual member manager custom properties

Custom properties are used to configure advance settings that provide some additional functions in the federated repository.

preFetchData

The preFetchData custom property is added to support prefetching and caching of a set of attributes for a user or group entity type for the LDAP repository. By using this property, you can define the list of attributes that you want to prefetch and cache permanently for a particular user or group entity type.

Information Value
Data type String
Valid values String containing pairs of entity type names and its set of attributes
The valid value for this property contains pairs of entity type names and their corresponding sets of attributes. The value for the property must be defined in the following format:
EntityType1:attribute1,attribute2;EntityType2:attribute1,attribute2

If the format or value that you specified for the attributes is not correct, you might see an exception, similar to the following examples:

  • If the value for the preFetchData property is not defined in the specified format, the following message is displayed on the console during configuration:
    com.ibm.websphere.wim.exception.WIMConfigurationException:
    CWWIM1043E: The format of the value of the 'preFetchData' property is not valid. Specify a valid value, for example, "PersonAccount:sn,mail;Group:cn,description".
  • If the name of the entity type is not valid, then you might see the following exception on the console:
    com.ibm.websphere.wim.exception.WIMConfigurationException:
    CWWIM5068E: The entity type 'abc' is not valid.
    where abc is the name of the invalid entity type that is provided in the configuration of the preFetchData property. The message is displayed with the name of the configured entity type.
  • If the name of the attribute is not valid or if it is not applicable for the entity type, then the following exception is displayed on the console:
    com.ibm.websphere.wim.exception.WIMConfigurationException: 
    CWWIM4516E The 'uid1' property is not defined for the 'Group' entity type.
    where uid1 is the invalid property name of the group entity type that is provided in the configuration of the preFetchData property. The message is displayed with the property and entity type names as configured.
Use the setIdMgrCustomProperty command to define the preFetchData property in the federated LDAP repository.
$AdminTask setIdMgrCustomProperty {-id <ldap_repository_name> -name <property_name> -value <value>}
For example: $AdminTask setIdMgrCustomProperty {-id LDAP1 -name preFetchData -value “PersonAccount:sn,cn,givenName,displayName,preferredLanguage;Group:cn,description”}
The following sample shows the LDAP repository configuration with the preFetchData property:
<config:repositories xsi:type="config:LdapRepositoryType" adapterClassName="com.ibm.ws.wim.adapter.ldap.LdapAdapter"
	id="LDAP1" isExtIdUnique="true" supportAsyncMode="false" supportExternalName="false"
        supportPaging="false" supportSorting="false" supportTransactions="false" certificateFilter=""
        certificateMapMode="exactdn" ldapServerType="IDS" translateRDN="false">
   <config:baseEntries name="o=ldap" nameInRepository="o=ldap"/>
   <config:loginProperties>uid</config:loginProperties>
   <config:CustomProperties name="preFetchData" value="PersonAccount:sn,cn,givenName,displayName,preferredLanguage;Group:cn,description"/>
   <config:ldapServerConfiguration primaryServerQueryTimeInterval="15" returnToPrimaryServer="true"
          sslConfiguration="">
	<config:ldapServers authentication="simple" bindDN="cn=root" bindPassword="{xor}LTAwK25tbA=="
            connectionPool="false" connectTimeout="0" derefAliases="always" referal="ignore"
            sslEnabled="false">
	    <config:connections host="localhost" port="389"/>
        </config:ldapServers>
   </config:ldapServerConfiguration>
</config:repositories>
Here are some scenarios showing control flow based on values that are configured for the preFetchData property:
  • Scenario 1: Logging in as user user1 with the preFetchData custom property value configured as: PersonAccount:sn;Group:cn

    When an operation is performed for the first time for user1, the sn attribute is also retrieved and cached along with the login property of the user, although there is no explicit request for sn as part of the query. For groups that contain user1 as a member, the cn attribute is cached. For subsequent calls, the data to be retrieved is looked up in the cache first and only if the data is not found, a JNDI call is made for the required attribute.

  • Scenario 2: Retrieving a group with the preFetchData custom property value configured as: Group:cn

    When a search is run for group g1, the federated repository retrieves and caches the group cn according to the configuration you specified. If a subsequent call searches for the cn and description attributes, cn is then fetched from the cache, and an explicit JNDI call is made to fetch the group description.

domainNameForAutomaticDiscoveryOfLDAPServers

You can use this property to find any available LDAP server at run time that is defined in the DNS configuration file for the LDAP repository against a particular domain name.

Information Value
Data type String
Valid values Name of the domain for which the LDAP server records are defined in the DNS configuration file

Other than primary server configurations, you can also configure failover servers in the federated LDAP repository configuration. Federated repository switches to the failover server if the primary server goes down. If there are many LDAP servers with the users and groups that are defined for them, it becomes difficult to specify all of the LDAP server names in the federated LDAP repository configuration. The configuration becomes more difficult and can take longer if many nodes are configured in the WebSphere® Application Server and if each node is configured with multiple LDAPs. When there are many LDAP servers, use the domainNameForAutomaticDiscoveryOfLDAPServers property to dynamically look up the LDAP server names at run time, irrespective of which LDAP server is configured in the LDAP repository.

You can define the domain name of the LDAP for which corresponding LDAP servers are defined in the corresponding DNS configuration file in the form of SRV records, as shown in the following examples:
_ldap._tcp.ibm.com 86400 IN SRV 0 0 389 bigbox.ibm.com
_ldap._tcp.ibm.com 86400 IN SRV 10 20 1389 smallbox1.ibm.com
If the domainNameForAutomaticDiscoveryOfLDAPServers property is set, the federated repository looks for LDAP servers from the DNS configuration file and makes the subsequent JNDI calls to that particular server.

You can set the domainNameForAutomaticDiscoveryOfLDAPServers property by using the setIdMgrCustomProperty command: $AdminTask setIdMgrCustomProperty {-id <ldap_repository_name> -name <property_name> -value <value>}

For example:
$AdminTask setIdMgrCustomProperty {-id LDAP1 -name domainNameForAutomaticDiscoveryOfLDAPServers -value “dc=ibm,dc=com”}
The following sample shows an LDAP repository configuration with the domainNameForAutomaticDiscoveryOfLDAPServers property:
<config:repositories xsi:type="config:LdapRepositoryType" adapterClassName="com.ibm.ws.wim.adapter.ldap.LdapAdapter"
        id="LDAP1" isExtIdUnique="true" supportAsyncMode="false" supportExternalName="false"
        supportPaging="false" supportSorting="false" supportTransactions="false" certificateFilter=""
        certificateMapMode="exactdn" ldapServerType="IDS" translateRDN="false">
   <config:baseEntries name="o=ldap" nameInRepository="o=ldap"/>
   <config:loginProperties>uid</config:loginProperties>
   <config:CustomProperties name="domainNameForAutomaticDiscoveryOfLDAPServers" value="dc=ibm,dc=com"/>
   <config:ldapServerConfiguration primaryServerQueryTimeInterval="15" returnToPrimaryServer="true"
          sslConfiguration="">
        <config:ldapServers authentication="simple" bindDN="cn=root" bindPassword="{xor}LTAwK25tbA=="
            connectionPool="false" connectTimeout="0" derefAliases="always" referal="ignore"
            sslEnabled="false">
            <config:connections host="localhost" port="389"/>
        </config:ldapServers>
   </config:ldapServerConfiguration>
</config:repositories>
The domainNameForAutomaticDiscoveryOfLDAPServers property overrides the LDAP server configuration set in the LDAP repository and retrieves the LDAP server name and port number from the DNS configuration file.

The following federated LDAP repository URL is generated and is used to search the LDAP server records: ldap:///dc=ibm,dc=com.

When JNDI receives the URL as the domain name, then the LDAP server is retrieved from the DNS configuration file. If one of the LDAP servers goes down, then JNDI starts another LDAP server that is defined in the DNS configuration file for that domain.

minimizeContextPoolThreadBlock

The minimizeContextPoolThreadBlock custom property is used to define the thread-locking behavior when an LDAP server is down and an attempt is made to read from the server. When the value of the property is set to true, only a minimum number of threads are blocked on read operation and the remaining threads fail immediately without waiting. If the property is set to false, every thread that makes the read requests is blocked until a context is created to the requested LDAP or the context creation encounters a timeout. The default time for context creation is 120 seconds.
Information Value
Data type Boolean
Default True

maxThreadsToBlock

The maxThreadsToBlock property is used along with the minimizeContextPoolThreadBlock property. When the minimizeContextPoolThreadBlock property is set to true, maxThreadsToBlock determines the maximum number of threads that must be blocked when an LDAP read operation is performed.
Information Value
Data type Integer
Default 5

bindTimeout

The bindTimeout custom property specifies the time that is taken to track the count of quick binds in milliseconds. Any binds that take longer than the specified time are added to the log if the trace log is enabled.
Information Value
Data type Milliseconds
Default 1000
[Updated in August 2016]

com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral

The com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral property allows for an equal sign to be included in the login name, such as in tw=admin. The configureAdminWIMUserRegistry wsadmin command defines the com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral property in the federated repository. To enable the property, run the following command:

$AdminTask configureAdminWIMUserRegistry {-customProperties                 
{"com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral=true"} }

The following sample shows a WIMUserRegistry configuration with the com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral property in security.xml:

<userRegistries xmi:type="security:WIMUserRegistry"
xmi:id="WIMUserRegistry_1" serverId="" serverPassword="{xor}"
realm="defaultWIMFileBasedRealm" ignoreCase="true"
useRegistryServerId="false" primaryAdminId="wasadmin"
registryClassName="com.ibm.ws.wim.registry.WIMUserRegistry">
    <properties xmi:id="Property_1461142692714"
name="com.ibm.ws.wim.registry.allowDNPrincipalNameAsLiteral"
value="true"/>
  </userRegistries>
When this property is set, the Virtual Member Manager (VMM) determines whether the login name ends with a baseEntry. If the login name does not end with a baseEntry, it is not treated as a distinguished name (DN), and the login is successful.
Information Value
Data type String
Default False
[Updated in August 2016]

Icon that indicates the type of topic Reference topic



Timestamp icon Last updated: March 6, 2017 0:20
File name: federation_customproperties.html