Standalone LDAP over SSL

Configure IBM® WebSphere® Portal to use a standalone LDAP user registry over SSL to store all user account information for secure authorization.

In a single server environment the following task does not have a dependency on the server status; therefore, the WebSphere_Portal and server1 servers can be either stopped or started. In a clustered environment you must stop all application servers on the system including WebSphere_Portal and server1 and then start the nodeagent and deployment manager servers before starting the following task.

Perform the following steps to configure a standalone LDAP user registry over SSL:

Note: Use the wp_security_xxx.properties helper file, located in the wp_profile_root/ConfigEngine/config/helpersdirectory, when performing this task to ensure the correct properties are entered. In the instructions below, when the step refers to thewkplc.properties file, you will use your wp_security_xxx.properties helper file.

1. Complete the following steps to add the SSL certificate for the LDAP server to the server trust store and the client trust store:

   1. Choose one of the following to add the certificate to the server trust store:

      The following table describes the options for adding the SSL certificate to the server trust store:

      Option	Steps
      Add the certificate to the server trust store	Log in to the WebSphere Application Server Administrative Console. Navigate to Security -> SSL certificate and key management -> SSL configurations. Click the appropriate SSL configuration from the list. For example, Stand-alone environments:NodeDefaultSSLSettings Clustered environments: CellDefaultSSLSettings Click Key stores and certificates. Click the appropriate trust store from the list. For example, Stand-alone environments: NodeDefaultTrustStore Clustered environments: CellDefaultTrustStore Click Signer certificates, click Add, and then enter the following information: Type the Alias the key store uses for the signer certificate. Type the File name where the signer certificate is located. Click OK and then click Save to save the changes to the master configuration.
      Retrieve the certificate from the port	Log in to the WebSphere Application Server Administrative Console. Navigate to Security -> SSL certificate and key management -> SSL configurations. Click the appropriate SSL configuration from the list. For example, Stand-alone environments:NodeDefaultSSLSettings Clustered environments: CellDefaultSSLSettings Click Key stores and certificates. Click the appropriate trust store from the list. For example, Stand-alone environments: NodeDefaultTrustStore Clustered environments: CellDefaultTrustStore Click Signer certificates, click Retrieve from port, and then enter the following information: Type the Host name used when attempting to retrieve the signer certificate from the SSL port. Type the SSL Port used when attempting to retrieve the signer certificate. Type the Alias the key store uses for the signer certificate. Clustered environments: Ensure the setting for SSL configuration for outbound connection matches your SSL settings. Click Retrieve signer information to retrieve the certificate from the port. Click OK and then click Save to save the changes to the master configuration.

   2. Add the certificate to the client trust store:

      • See "Secure installation for client signer retrieval."

      • Run the retrieveSigners task from the wp_profile_root/bin directory; see retrieveSigners command for information. In a deployed environment, you will need to run the retrieveSigners task, for any federated node, against the Deployment Manager.

        Note: This task might report an error, but it does successfully update the trust store. You can ignore the error message.

        Example task:

        Stand-alone environments

        retrieveSigners.sh NodeDefaultTrustStore ClientDefaultTrustStore -autoAcceptBootstrapSigner -conntype SOAP -port port_number

        Clustered environments

        retrieveSigners.sh CellDefaultTrustStore ClientDefaultTrustStore -autoAcceptBootstrapSigner -conntype SOAP -port port_number

        When prompted, enter the following:

        Realm/Cell Name: name

        Username: user_ID

        Password: password

        The following message displays: CWPKI0308I: Adding signer alias “alias_name" to local keystore “ClientDefaultTrustStore" with the following SHA digest: ssl_certificate_fingerprint

      • Update the trust store properties file.

        Clustered environments:

        Perform the following steps on the primary node then resynchronize through the Deployment Manager to propagate the changes.

        Check each node to ensure that ssl.client.props contains the same values as on the primary node. If the values in ssl.client.props are not identical for a particular node, restart that server to synchronize the changes.

        Open ssl.client.props with any text editor in the following directory: wp_profile_root/properties

        Change the com.ibm.ssl.trustStore parameter and the related trust store parameters to match the trust file specified in the SSL configuration. For example,

        Stand-alone environments:

        To use the default trust store, enter the following: com.ibm.ssl.trustStore=wp_profile_root\\config\\cells\\cell_name\\nodes\\node_name\\trust.p12

        Clustered environments:

        To use the default trust store, enter the following: com.ibm.ssl.trustStore=wp_profile_root/config/cells/cell_name/trust.p12

        Save your changes.

2. Use a text editor to open the wkplc.properties file, located in the wp_profile_root/ConfigEngine/properties directory.

3. Required: Enter a value for the following required parameters in the wkplc.properties file under the VMM Stand-alone LDAP configuration heading:

   Note: See the properties file for specific information about the required parameters and for advanced parameters.

   standalone.ldap.id
   standalone.ldap.host
   standalone.ldap.port
   standalone.ldap.bindDN
   standalone.ldap.bindPassword
   standalone.ldap.ldapServerType
   standalone.ldap.userIdMap
   standalone.ldap.groupIdMap
   standalone.ldap.groupMemberIdMap
   standalone.ldap.userFilter
   standalone.ldap.groupFilter
   standalone.ldap.serverId
   standalone.ldap.serverPassword
   standalone.ldap.realm
   standalone.ldap.primaryAdminId
   standalone.ldap.primaryAdminPassword
   standalone.ldap.primaryPortalAdminId
   standalone.ldap.primaryPortalAdminPassword
   standalone.ldap.primaryPortalAdminGroup
   standalone.ldap.baseDN
   

4. Required: Enter a value for the following required entity types parameters in the wkplc.properties file under the LDAP entity types heading:

   Note: See the properties file for specific information about the required parameters and for advanced parameters.

   standalone.ldap.et.group.objectClasses
   standalone.ldap.et.group.objectClassesForCreate
   standalone.ldap.et.group.searchBases
   standalone.ldap.et.personaccount.objectClasses
   standalone.ldap.et.personaccount.objectClassesForCreate
   standalone.ldap.et.personaccount.searchBases
   

5. Required: Enter a value for the following required group member parameters in the wkplc.properties file under the Group member attributes heading:

   Note: See the properties file for specific information about the required parameters and for advanced parameters.

   standalone.ldap.gm.groupMemberName
   standalone.ldap.gm.objectClass
   standalone.ldap.gm.scope
   standalone.ldap.gm.dummyMember
   

6. Required: Enter a value for the following required relative distinguished name (RDN®) parameters in the wkplc.properties file under the Default parent, RDN attribute heading:

   Note: See the properties file for specific information about the required parameters and for advanced parameters.

   standalone.ldap.personAccountParent
   standalone.ldap.groupParent
   standalone.ldap.personAccountRdnProperties
   standalone.ldap.groupRdnProperties

7. Enter a value for the following parameters to enable Secure Socket Layers (SSL):

   Note: See the properties file for specific information about the required parameters and for advanced parameters.

   Required parameters:

   standalone.ldap.sslEnabled
   standalone.ldap.sslConfiguration
   

   Optional parameters:

   standalone.ldap.certificateMapMode
   standalone.ldap.certificateFilter
   

8. Save your changes to the wkplc.properties file.

9. Run the ConfigEngine.sh validate-standalone-ldap -DWasPassword=password task to validate your LDAP server settings.

   Attention: If you have not deleted the default file repository, WasPassword is the value entered during installation and not a value found in your LDAP user registry.
   Note: During the validation task, you may receive the following prompt: Add signer to the trust store now?. Press y and then Enter.

10. Run the ConfigEngine.sh wp-modify-ldap-security -DWasPassword=password task, from thewp_profile_root/ConfigEngine directory, to set the standalone LDAP user registry.

11. 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.

12. Run the ConfigEngine.sh wp-validate-standalone-ldap-attribute-config -DWasPassword=password task, from thewp_profile_root/ConfigEngine directory, to check that all defined attributes are available in the configured LDAP user registry.

    Important: When you finish configuring your LDAP user registry, see "Adapting the attribute configuration" for information about adding and mapping attributes to ensure proper communication between WebSphere Portal and the LDAP server.

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.

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:

1. 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.

2. 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.

3. Use a text editor to open the wkplc.properties file, located in the wp_profile_root/ConfigEngine/properties directory.

4. 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

5. Save your changes to the wkplc.properties file.

6. 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.

7. 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:

1. Use a text editor to open the wkplc.properties file, located in the wp_profile_root/ConfigEngine/properties directory.

2. Enter a value for one of the following sets of parameters in the wkplc.properties file to identify your LDAP server:

   Note: Make sure you use the same values you used to configure your LDAP server.

   The following table contains information on how to identify your LDAP server in the wkplc.properties file:

   Repository type	Parameters
   Stand-alone	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.host standalone.ldap.port standalone.ldap.sslEnabled standalone.ldap.bindDN standalone.ldap.bindPassword standalone.ldap.baseDN

3. Run one of the following tasks to check that all defined attributes are available in the configured LDAP user registry.

   The following table describes the task to check that all defined attributes are available in the configured LDAP user registry.

   Repository type	Task
   Stand-alone	ConfigEngine.sh wp-validate-standalone-ldap-attribute-config -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory.

4. 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.

5. Use a text editor to open the wkplc.properties file, located in the wp_profile_root/ConfigEngine/properties directory.

6. Enter a value for one of the following sets of parameters in the wkplc.properties file to correct any issues found in the config trace file.

   The following table describe the parameters that you can define in the wkplc.properties file to correct any issues found in the config trace file.

   Repository type

   Parameters

   Stand-alone

   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 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

7. Save your changes to the wkplc.properties file.

8. Run one of the following tasks to update the LDAP user registry configuration with the list of unsupported attributes and the proper mapping between WebSphere Portal and the LDAP user registry.

   This table describes the task to update the LDAP user registry configuration with the list of unsupported attributes and the proper mapping between Portal and the LDAP user registry.

   Repository type	Task
   Stand-alone	ConfigEngine.sh wp-update-standalone-ldap-attribute-config -DWasPassword=password task, from the wp_profile_root/ConfigEngine directory

9. 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.

10. 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 ConfigEngine.sh wp-update-attribute-config -DWasPassword=password task, from thewp_profile_root/ConfigEngine directory.

    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.

1. Open the tool you use to edit your database.

2. Verify that your attribute name is available in the LAPROP table.

3. Delete the required attributes from the LAPROP table.

4. Open the wimxmlextension.xml file, located in the wp_profile_root/config/cells/cellname/wim/model directory.

5. 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>
   

6. Save your changes to the wimxmlextension.xml file.

7. Open the wimconfig.xml file, located in the wp_profile_root/config/cells/cellname/wim/config directory.

8. Locate and delete the propertiesNotSupported definitions for the attributes that you deleted from the LAPROP table; for example:

   <config:propertiesNotSupported name="attribute_name">

9. Save your changes to the wimconfig.xml file.

10. Stop and restart the server1 and WebSphere_Portal servers from the wp_profile_root/bin directory.

By default, WebSphere Portal is enabled for static groups. However, the Virtual Member Manager (VMM) allows users to be members of either static or dynamic groups. Static groups are those where a persistent binding exists between a group and its members. Dynamic groups are those where a search query is defined to retrieve the members of a group. If you have your LDAP server configured to use dynamic groups, complete the steps in this task for WebSphere Portal to use dynamic group queries when you setup your LDAP server.

Perform the required tasks to configure either a stand-alone or federated LDAP server security.

The steps in this task use groupOfURLs as the object class for dynamic groups and memberURL as the dynamic membership attribute. The actual values for object classes and dynamic membership attributes can vary depending on your LDAP server. For this reason, you should export an LDIF file to verify the object classes and dynamic membership attributes. Either refer to your LDAP documentation or ask your LDAP administrator for instructions on exporting an LDIF file.

Clustered environments: Perform the following steps on the Deployment Manager then synchronize the nodes.

To configure WebSphere Portal to use dynamic groups, do the following:

1. Choose the appropriate set of steps, depending on your LDAP server environment:

   This table describes the steps for enabling dynamic groups:

   LDAP server environment	Steps to perform
   Stand-alone LDAP server or federated LDAP server(s)	Navigate to the following directory: wp_profile_root/cells/cell_name/wim/config. Locate and open wimconfig.xml with any text editor. Add the following line to the <config:groupConfiguration>tag: <config:dynamicMemberAttributes name="memberurl" objectClass="groupofurls"/>

2. Stop and restart the appropriate servers to propagate the changes.

Referrals redirect object requests from one LDAP server to another when objects do not exist or cannot be located in a particular directory tree. You should enable referrals if your environment has more than one user registry existing on multiple servers or domains.

To configure your portal to use LDAP referrals, do the following:

1. Use any text editor to open the wkplc.properties file in the following directory: wp_profile_root/ConfigEngine/properties.

2. Specify values for the following parameters:

   • et.ldap.id=ID_of_your_LDAP_server

   • et.ldap.host=hostname_of_your_LDAP_server

   • et.ldap.referral=follow

3. Save and close wkplc.properties.

4. Run the following task from the wp_profile_root/ConfigEngine directory to create an LDAP entity type:

   UNIX: ./ConfigEngine.sh wp-update-et-ldap -DWasPassword=password Windows: ConfigEngine.bat wp-update-et-ldap -DWasPassword=password i: ConfigEngine.sh wp-update-et-ldap -DWasPassword=password

5. Stop and restart the appropriate servers to propagate the changes.