wimconfig.xml is a WebSphere Application Server (WSAS) configuration file, however it is an important file in a WebSphere Portal environment. It is the main file that controls the behavior of the Virtual Member Manager component (VMM). WebSphere Portal (WP or Portal) depends on VMM services during login, user and group search and access control assignments, among other tasks. Wimconfig.xml is critical to the functioning of WebSphere Portal.

General Information and Notes

In Portal 6.1 and later VMM has replaced the WebSphere Member Manager (WMM). There is no WMM code in Portal or WSAS 6.1. Most of the terms used in WMM (realm, searchBase) translate directly to VMM and the configuration "pattern" of properties and their values represented as XML applies to VMM as well. VMM is simpler to manage in that there is only a single major configuration file while in WMM care often had to be taken to ensure consistency across multiple files.

The core Portal code does not communicate with a configured repository directly. Calls are made by VMM at the direction of Portal components; principal among these is PUMA, the Portal User Management Architecture. For example, a search for a user by CN in the Users and Groups portlet makes calls to PUMA which in turn calls VMM to fetch data from the repository. Similarly, PUMA API calls also result in method calls by VMM.

VMM is a component of Application Server. Defects fixed in VMM are delivered in Application Server Fixpacks. You may be required to upgrade the Application Server in order to resolve a defect in VMM.

Portal configuration tasks, for example wp-create-ldap, update the VMM configuration as well as other Portal resources. APARs that resolve defects in Portal configuration tasks are delivered in Portal Fixpacks and as Portal Interim Fixes.

Portal configuration tasks cover most scenarios but at times manual modification of wimconfig.xml is necessary to complete or "fine tune" a configuration. In addition, there are properties that may require update in wimconfig.xml for which no Portal configuration task exists. Manual editing of wimconfig.xml is supported and is often the most efficient way to make necessary adjustments.

If there is no Portal configuration task to modify particular properties in the wimconfig.xml, Application Server tools such as the $AdminTask facility can be used if manual modifications are not to be permitted or to script changes to the file.

VMM can be configured to retrieve user and group information from a single repository or a combination of repositories. A repository is a "container" for these data, whether it is an LDAP server, a database, a file or a Custom User Repository (CUR).

The default, out-of-the-box, Portal security configuration is the federated repository type. Configuring Portal to use a stand-alone LDAP repository by running the configuration task wp-modify-standalone-ldap effectively "converts" the configuration to the stand-alone type. If you intend to support multiple repositories or create multiple realms and associate the realms to virtual portals, you must maintain a federated configuration.

This document describes the major stanzas in wimconfig.xml as they relate to WebSphere Portal. This document is not intended to serve as an encyclopedic reference to the configuration of VMM, particularly in environments in which WebSphere Portal is not installed.

In this document, wimconfig.xml is segregated into parts and comments regarding a given section are listed below the XML. Certain markup has been removed and the syntax modified to make the document easier to read. Copying entries from this file is discouraged and may result in a non-functional Portal server.

Not all of the possible repository types are described here. An LDAP repository is used in the examples below since it is the most common repository type.

Main wimconfig.xml Stanzas

configurationProvider

This stanza appears once in wimconfig.xml. There are no Portal configuration tasks to modify the properties in this section. maxSearchResults can be adjusted to limit the number of results fetched from the LDAP.

EntityTypes

The defaultParent defines the default container where users, groups and OrganizationalUnits will be created if the Portal UI is used to add users and groups to the repository. There can be only 1 parent per EntityType no matter how many repositories are configured. defaultParents can be set per realm, however. If users and groups are created directly in the repository the parents entitie do not need to be modified from the default since they will not be used.

The defaultParent for OrgContainer is not used by WebSphere Portal. The OrgContainer defaultParent will be defined as "o=defaultWIMFileBasedRealm" even in federated multiple repository configuration unless the entry has been modified manually.

Repositories

There will be one stanza for each repository in the environment. A repository may be configured to use 1 or more realms. To map a realm to a Virtual Portal the configuration type must be federated.

For a Custom User Repository ensure the adapterClassName is set to the name of the custom class. wkplc.properties provides a default class for the LDAP and database repositories.

ldapServerType options are defined in wkplc.properties.

ldapServerConfiguration

      <baseEntries name="dc=ibm,dc=com" nameInRepository="dc=ibm,dc=com"/>

baseEntries "nameInRepository" must be a valid LDAP container (ie, the actual name of the container in the LDAP)

      <loginProperties>uid</loginProperties>

loginProperty defines the property used to login to the LDAP.

      <ldapServerConfiguration primaryServerQueryTimeInterval="15" returnToPrimaryServer="true"

          searchCountLimit="500" searchTimeLimit="120000" sslConfiguration="">

There are no tasks to modify the the ldapServerConfiguration properties.

ldapServers

        <ldapServers authentication="simple" bindDN="uid=wpsbind,cn=internal,ou=user,dc=ibm,dc=com"

            bindPassword="{xor}KC8sPTYxOw==" connectionPool="true" connectTimeout="0"

            derefAliases="always" referal="ignore" sslEnabled="false">

          <connections host="ldap.ibm.com" port="389"/>

        </ldapServers>

      </ldapServerConfiguration>

LDAP-specific properties. The bindDN must be able to bind to, search, and have permission in the LDAP to return all attributes associated to Portal users and groups. The bindDN can be any id and does not have to be the LDAP administrator id. bindDN should be set to a fully qualified distinguished name. bindPassword can be encoded with WSAS utility propFilePasswordEncoder. The "referal" (sic) property can be set to cause VMM to "follow" a referral to another LDAP.

ldapEntityTypes

      <ldapEntityTypes name="OrgContainer">

        <rdnAttributes name="o" objectClass="organization"/>

        <rdnAttributes name="ou" objectClass="organizationalUnit"/>

        <rdnAttributes name="dc" objectClass="domain"/>

        <rdnAttributes name="cn" objectClass="container"/>

        <objectClasses>organization</objectClasses>

        <objectClasses>organizationalUnit</objectClasses>

        <objectClasses>domain</objectClasses>

        <objectClasses>container</objectClasses>

      </ldapEntityTypes>

     <ldapEntityTypes name="PersonAccount" searchFilter="objectclass=inetOrgPerson">

        <objectClasses>inetOrgPerson</objectClasses>

        <searchBases>ou=user,dc=ibm,dc=com</searchBases>

      </ldapEntityTypes>

    <ldapEntityTypes name="Group" searchFilter="objectclass=groupOfUniqueNames">

        <objectClasses>groupOfUniqueNames</objectClasses>

        <searchBases>ou=role,ou=group,dc=ibm,dc=com</searchBases>

      </ldapEntityTypes>

Define the objectClasses for users (PersonAccount), Groups and OrgContainer (the OrgContainer type is not used by WebSphere Portal). The objectClasses are a primary search criteria used by VMM. Add additional searchBases on a new line. Do not use ; or : to concatenate searchBases. ObjectClasses must match the EntityType in LDAP (confirm this with an ldif export from the LDAP). Multiple ObjectClasses can be listed on separate lines.

groupConfiguration

      <groupConfiguration>

        <memberAttributes dummyMember="uid=dummy" name="member" objectClass="groupOfNames"

            scope="direct"/> (TDS and others)

        <memberAttributes dummyMember="uid=dummy" name="uniqueMember" objectClass="groupOfUniqueNames"

            scope="direct"/> (TDS and others)

        <memberAttributes dummyMember="" name="member" objectClass="group"

            scope="direct"/> (MSAD)

Group member attributes. Both the name and objectClass must match the class name in the LDAP otherwise searches will fail. Typically, this is observed in the Users and Groups portlet when a group can be retrieved but its members cannot or members of a group do not see Portal content after access control assignments.

attributeConfiguration

  <membershipAttribute name="ibm-allGroups" scope="direct"/> (TDS example)

  <membershipAttribute name="nsRole" scope="direct"/> (SunOne example)

  <dynamicMemberAttributes name="memberurl" objectClass="groupofurls"/>

memberAttributes name and objectClass must match the entityTypes definitions above. Verify using an LDIF export. membershipAttribute name can be used to "shortcut" group searches to improve performance. dynamicMemberAttributes is used to configure dynamic groups.

For both memberAttributes and membershipAttribute scope values are:

direct - The membership attribute only contains direct groups (default).
nested - The membership attribute that contains the direct groups and the nested groups.
all - The membership attribute contains direct groups, nested groups, and dynamic members.

The use of nested or dynamic groups can negatively affect search performance.

        <attributes name="unicodePwd" propertyName="password" syntax="unicodePwd"/>

        <propertiesNotSupported name="description"/>

        <propertiesNotSupported name="jpegPhoto"/>

        <propertiesNotSupported name="labeledURI"/>

        <propertiesNotSupported name="carLicense"/>

        <propertiesNotSupported name="pager"/>

        <propertiesNotSupported name="roomNumber"/>

At configure time a default list of attributes will be added to wimconfig.xml. To make additonal attributes or custom attributes available to Portal the attribute must be added to VMM and then mapped in the VMM configuration using the appropriate configuration tasks.

LDAP attributes unavailable in Portal will be shown as 'propertiesNotSupported.' An "unsupported" attribute will not be queried. You may set a an attribute as NotSupported to prevent its use in the Portal. Set a given attribute as NotSupported if the property is not indexed in the repository to increase performance.

contextPool

   <contextPool enabled="true" initPoolSize="1" maxPoolSize="20" poolTimeOut="0" poolWaitTime="3000" prefPoolSize="3"/>

VMM maintains a pool of threads (or "contexts") to communicate with the repository. Contexts are used for user and group searches and to determine membership during login. There are no config tasks to modify these properties. A context is not the same as a connection.

The Portal 6.1 Tuning Guide recommends the following pool settings: initPoolSize="10" maxPoolSize="0" poolTimeOut="0" poolWaitTime="3000" prefPoolSize="30"

In particular, maxPoolSize 0 allows the pool to grow as large as needed.

cacheConfiguration

      <cacheConfiguration>

        <attributesCache attributeSizeLimit="2000" cacheSize="4000" cacheTimeOut="1200"

            enabled="true"/>

        <searchResultsCache cacheSize="2000" cacheTimeOut="600" enabled="true"

            searchResultSizeLimit="1000"/>

      </cacheConfiguration>

By default, both VMM and the Portal User Management Architecture (PUMA) cache objects such as LDAP attributes. The cache settings can be tuned in this section.

realmConfiguration

<realmConfiguration defaultRealm="DefaultPortalRealm">

<realms delimiter="/" name="DefaultPortalRealm" securityUse="active" allowOperationIfReposDown="false">

  <participatingBaseEntries name="dc=ibm,dc=com"/>

  <participatingBaseEntries name="dc=raleigh,dc=ibm,dc=com"/>

  <uniqueUserIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/>

  <userSecurityNameMapping propertyForInput="principalName" propertyForOutput="externalName"/>

  <userDisplayNameMapping propertyForInput="principalName" propertyForOutput="principalName"/>

  <uniqueGroupIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/>

  <groupSecurityNameMapping propertyForInput="cn" propertyForOutput="externalName"/>

  <groupDisplayNameMapping propertyForInput="cn" propertyForOutput="cn"/>

</realms>

<realms delimiter="/" name="PortalRealm_Releigh" securityUse="active" allowOperationIfReposDown="false">

  <participatingBaseEntries name="dc=raleigh,dc=ibm,dc=com"/>

  <uniqueUserIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/>

  <userSecurityNameMapping propertyForInput="principalName" propertyForOutput="externalName"/>

  <userDisplayNameMapping propertyForInput="principalName" propertyForOutput="principalName"/>

  <uniqueGroupIdMapping propertyForInput="uniqueName" propertyForOutput="uniqueName"/>

  <groupSecurityNameMapping propertyForInput="cn" propertyForOutput="externalName"/>

  <groupDisplayNameMapping propertyForInput="cn" propertyForOutput="cn"/>

</realms>

</realmConfiguration>

This section defines the Portal realms. In this example, there are two realms, the default realm called "DefaultPortalRealm" and a second realm called "PortalRealm_Raleigh."

The defaultRealm (also called the "super realm" in the Portal Infocenter) must contain the participatingBaseEntries for all realms defined. Realms are usually "bound" or attached to Virtual Portals. More than one realm may be defined in a single repository. Other than the addition of new realms, baseEntries and other properties such as defaultParents, manual modification to wimconfig.xml is usually required to establish a multiple realm configuration.