Working with LDAP Attributes

This section describes how to:

Perform a query on attributes.
Add new attributes to your user registry.
Map attributes between WebSphere Portal and your LDAP server.
Remove attributes from your database.

After installing IBM® WebSphere® Portal and configuring your LDAP user registries, you can query the defined attributes to see what attributes are flagged as unsupported or if the attribute is mapped to a different LDAP attribute.

To perform a query:

Run the ./ConfigEngine.sh wp-query-attribute-config -DWasPassword=password task, from thewp_profile_root/ConfigEngine directory, any time during the configuration process or at runtime to query an overview of the currently defined attributes.

This task creates the availableAttributes.html report, located in the wp_profile_root/ConfigEngine/logdirectory. The report contains one table that lists the available attributes for Users (PersonAccount) and one table that lists the available attributes for Groups. For each configured repository, there is a column that indicates if the attribute is flagged as unsupported or if the attribute is mapped to a different LDAP attribute.

Note: This task does not validate the existence of attributes in the LDAP schema.

The VMM is configured with a default attribute schema that might not be compatible with your LDAP server. If this is the case, extend the VMM attribute schema by adding new attributes that you can map between IBM® WebSphere® Portal and your user registry.

Perform the following steps to add new attributes to your user registry:

Install the required Enterprise Archive (.ear) file on WebSphere Application Server.
1. Open a command prompt.
2. Navigate to the wp_profile_root\\ConfigEngine directory.
3. Run the ./ConfigEngine.sh wp-la-install-ear -DWasPassword=password task.
Stop and restart the appropriate servers to propagate the changes. For specific instructions, see the following link under Related tasks: Starting and stopping servers, deployment managers, and node agents.
Use a text editor to open the wkplc.properties file, located in the wp_profile_root\\ConfigEngine\\properties directory.
Enter a value for the following required parameters in the wkplc.properties file under the VMM Property Extension Properties heading:
Note: See the properties file for specific information about the required parameters and for advanced parameters.
la.providerURL
la.propertyName
la.entityTypes
la.dataType
la.multiValued
Save your changes to the wkplc.properties file.
Run the ConfigEngine.sh wp-add-property -DWasPassword=password task to add the attribute to the user registry.
Note: This task performs an EJB call to WebSphere Application Server, which must authenticate against WebSphere Application Server. Depending on the configuration in the sas.client.props file, you may receive a popup window or a command line prompt asking for user identity and password. Enter the WebSphere Application Server user ID and password.
Remember: If you have multiple properties to add, repeat all steps, except for the wp-la-install-ear task, until all new attributes are added.
Stop and restart the appropriate servers to propagate the changes.

After you install and configure your LDAP user registry and after you query the defined attributes, you can map the attributes so they match the configured LDAP servers and your business needs.

Perform the following steps to map attributes between WebSphere Portal and your LDAP server; if you have multiple LDAP servers, you will need to perform these steps for each LDAP server:

Use a text editor to open the wkplc.properties file, located in the wp_profile_root\\ConfigEngine\\properties directory.
For a stand-alone repository, enter a value for the following sets of parameters in the wkplc.properties file to identify your LDAP server. The parameters are found under the LDAP attribute configuration heading:
Note: Make sure you use the same values you used to configure your LDAP server.
standalone.ldap.id
standalone.ldap.host
standalone.ldap.port
standalone.ldap.sslEnabled
standalone.ldap.bindDN
standalone.ldap.bindPassword
standalone.ldap.baseDN
Note: See the properties file for specific information about the required parameters and for advanced parameters.
For a stand-alone repository, run the following task from the wp_profile_root\\ConfigEngine directory. This task checks that all defined attributes are available in the configured LDAP user registry:
ConfigEngine.sh wp-validate-standalone-ldap-attribute-config -DWasPassword=password
Open the ConfigTrace.log file, located in the wp_profile_root\\ConfigEngine\\log directory, to review the following output for the PersonAccount and Group entity type:
The following attributes are defined in WebSphere Portal but not in the LDAP server
This list contains all attributes that are defined in WebSphere Portal but not available in the LDAP. Flag attributes that you do not plan to use in WebSphere Portal as unsupported. Map the attributes that you plan to use to the attributes that exist in the LDAP; you must also map the uid, cn, firstName, sn, preferredLanguage, and ibm-primaryEmail attributes if they are contained in the list.
The following attributes are flagged as required in the LDAP server but not in WebSphere Portal
This list contains all attributes that are defined as "MUST" in the LDAP server but not as required in WebSphere Portal. You should flag these attributes as required within WebSphere Portal; see the step below about flagging an attribute as either unsupported or required.
The following attributes have a different type in WebSphere Portal and in the LDAP server
This list contains all attributes that WebSphere Portal might ignore because the data type within WebSphere Portal and within the LDAP server do not match.
Use a text editor to open the wkplc.properties file, located in the wp_profile_root\\ConfigEngine\\properties directory.
For a stand-alone repository, enter a value for the following sets of parameters in the wkplc.properties file to correct any issues found in the config trace file. The following parameters are found under the LDAP attribute configuration heading:
Note: See the properties file for specific information about the required parameters and for advanced parameters.
standalone.ldap.id
standalone.ldap.attributes.nonSupported
standalone.ldap.attributes.nonSupported.delete
standalone.ldap.attributes.mapping.ldapName
standalone.ldap.attributes.mapping.portalName
standalone.ldap.attributes.mapping.entityTypes
For example, the following values will flag certificate and members as unsupported attributes and will map ibm-primaryEmail to mail and ibm-jobTitle to title for both the PersonAccount andGroup entityTypes:
standalone.ldap.attributes.nonSupported=certificate, members
standalone.ldap.attributes.nonSupported.delete=
standalone.ldap.attributes.mapping.ldapName=mail, title
standalone.ldap.attributes.mapping.portalName=ibm-primaryEmail, ibm-jobTitle
standalone.ldap.attributes.mapping.entityTypes=PersonAccount, Group
Save your changes to the wkplc.properties file.
For a stand-alone repository, run the following task from the wp_profile_root\\ConfigEngine directory. This tasks updates the LDAP user registry configuration with the list of unsupported attributes and the proper mapping between WebSphere Portal and the LDAP user registry:
./ConfigEngine.sh wp-update-standalone-ldap-attribute-config -DWasPassword=password
Stop and restart the appropriate servers to propagate the changes. For specific instructions, see the following link under Related tasks: Starting and stopping servers, deployment managers, and node agents.
Optional: Perform the following steps to flag an attribute as either unsupported or required for the entire WebSphere Portal environment instead of just for the specified LDAP:
1. Enter a value for the following required parameters in the wkplc.properties file:
  Note: See the properties file for specific information about the required parameters and for advanced parameters.
  user.attributes.required
  user.attributes.nonsupported
2. Save your changes to the wkplc.properties file.
3. Run the following task from the wp_profile_root\\ConfigEngine directory:
  ./ConfigEngine.sh wp-update-attribute-config -DWasPassword=password
4. Stop and restart all necessary servers to propagate your changes.

Due to a Virtual Member Manager (VMM) limitation, there is currently no task to update an attribute. Therefore, if you added an attribute to your property extension database or when adapting attributes to match your LDAP server that were spelled incorrectly or already added due to migration, you must remove the attribute from the database. Use caution when performing these steps.

Perform the following steps to remove an attribute from your database:

Important: Do not remove attributes that have already been populated with user values because this can cause database inconsistencies.

Cluster note: In a clustered environment, perform the following steps on the deployment manager and then resynch the nodes.

Open the tool you use to edit your database.
Verify that your attribute name is available in the LAPROP table.
Delete the required attributes from the LAPROP table.
Open the wimxmlextension.xml file, located in the wp_profile_root/config/cells/cellname/wim/model directory.

Locate and delete the propertySchema definition for the attributes that you deleted from the LAPROP table; for example:

    <wim:propertySchema nsURI="http://www.ibm.com/websphere/wim" dataType="String"
        multiValued="true" propertyName="attribute_name">
      <wim:applicableEntityTypeNames>PersonAccount</wim:applicableEntityTypeNames>
    </wim:propertySchema>

Save your changes to the wimxmlextension.xml file.
Open the wimconfig.xml file, located in the wp_profile_root/config/cells/cellname/wim/config directory.
Locate and delete the propertiesNotSupported definitions for the attributes that you deleted from the LAPROP table; for example:
<config:propertiesNotSupported name="attribute_name">
Save your changes to the wimconfig.xml file.
Stop and restart the server1 and WebSphere_Portal servers from the wp_profile_root/bin directory.