Reference: Additional configuration for Lotus Collaborative Components

 

This topic provides information for editing the CSEnvironment.properties file to support additional configurations offered by Lotus Collaborative Components for Lotus QuickPlace and Lotus Sametime. possible configurations.

Use the IBM Web Administration for iSeries Create WebSphere Portal wizard when configuring WebSphere Portal instances. The wizard creates the necessary servers (HTTP and WebSphere Application Server), configures the server for Portal, configures the database for Portal, configures security (LDAP) for Portal, and deploys the portlets installed with the WebSphere Portal product. You can edit the Portal instance configuration manually after you have used the WebSphere Portal wizard.

Important: The configuration tasks that you use to configure WebSphere Portal to use products such as Lotus Domino and Lotus Sametime do not configure the settings referenced in this topic. For all settings in this topic, manually edit the CSEnvironment.properties file, and then stop and start WebSphere Portal before any changes take effect.

• Overview
• Basics of editing the CSEnvironment.properties file
• Additional configuration for Lotus Sametime
• Additional configuration for Lotus Domino
• Additional configuration for User Credential customization
• Performance tuning parameter for Domino Directory

 

Overview

Configuration settings for using collaboration with WebSphere Portal have been consolidated into a single file: CSEnvironment.properties. The CSEnvironment.properties file, installed in the WebSphere Portal /config directory. This file contains the following information about the portal environment:

• A flag to indicate whether the Lotus Collaborative Components are being used within the Portal Server context

• Location, protocol, port and version of QuickPlace server

• Location, protocol, port and version of Domino Directory server (needed for Notes portlets)

• Location, protocol, port and version of Sametime server

• Configuration and Performance tuning settings specific to Lotus Collaborative Components.

 

Basics of editing the CSEnvironment.properties file

In general, to change the properties that are listed in this topic, do the following:

1. Stop WebSphere Portal.

2. Edit the CSEnvironment.properties file to include the desired values.

3. Remove the comment tag (#) from the beginning of each line.

4. Save the changes.

5. Restart WebSphere Portal.

 

Additional configuration for Lotus Sametime

This section contains information for setting values related to Lotus Sametime when it is configured with Portal Server.

 

Specify to use the LTPA token for logging into Sametime

You can override the credential settings in the CSEnvironment.properties file to enable an LTPA token for logging in to Sametime.

By default, an internal Sametime token is used. To override this setting so that the LTPA token will be used, change the setting for CS_SERVER_SAMETIME_1.useLTPAToken to true, and remove the pound sign (#) at the beginning of the line. The following example shows the syntax.

CS_SERVER_SAMETIME_1.useLTPAToken=true

If CS_SERVER_CUSTOM_CRED.enabled is set to true, and the value for CS_SERVER_CUSTOM_CRED.ssoTokenAttrib is set, the token that is set will be used for logging into Sametime instead of the LTPA token.

 

Specify server connection properties for obtaining Sametime tokens for users

The following Sametime settings pertain to the server-to-server connection between WebSphere Portal and the Sametime server. The sole purpose for this connection is to obtain Sametime tokens for users which are used to log users into Sametime from their Web browsers.

• Port through which the Sametime server should connect

  The property is: CS_SERVER_SAMETIME_1.serverappPort

  To connect directly to the server, a value for the port can be set explicitly. For example: CS_SERVER_SAMETIME_1.serverappPort=1516

• Sametime reconnect interval

  The property is: CS_SERVER_SAMETIME_1.reconnect

  To change the reconnect interval in seconds to the Sametime server after being disconnected, or not connected. For example: CS_SERVER_SAMETIME_1.reconnect=10 Use 0 to indicate that a reconnection should not be attempted. If not set, the internal default of 30 seconds is used.

• Sametime timeout value

  The property is: CS_SERVER_SAMETIME_1.timeout

  The maximum amount of time in seconds to wait for a response from the Sametime server. If not set, the internal default of 60 seconds is used. For example: CS_SERVER_SAMETIME_1.timeout=120

• Specify the name format to use when resolving the portal logged in user with the Sametime server

  The following setting is important for resolving name formats between two user registries that use different schemas. For example, if the user registry for Sametime is native Domino Directory, and the user registry for the portal is an LDAP directory such as IBM Directory Server, then setting the nameFormatForResolve value will resolve name mapping issues between Sametime and the portal.

  The property is: CS_SERVER_SAMETIME_1.nameFormatForResolve

  Valid values include cn, dn, and loginName. For example: CS_SERVER_SAMETIME_1.nameFormatForResolve=dn

  Note: The loginName or cn value must be used if a multi-ID setup is used. For example, if the following is true:

  • Portal Server points to a user directory.

  • Domino Directory is used for Domino data, Sametime data (and QuickPlace data)

  • Domino Directory contains mapping entries to the Portal Server user directory (DN, cn, and uid, explicitly)

• Specify the character to use to separate distinguished names

  The property is: CS_SERVER_SAMETIME_1.dnNameSeparator

  The value is a character that is used to resolve names with the Sametime server, and the name used to log in to Sametime from a browser. A valid value is the single character comma (,) or slash (/)

  For example: CS_SERVER_SAMETIME_1.dnNameSeparator=,

  Tip: Domino servers use slashes in the distinguished name.

 

Tip: Configuring People Awareness to work if Sametime uses the native Domino Directory and Portal uses a separate LDAP server such as IBM Directory Server

The instructions provided below are required for environments where WebSphere Portal and Sametime are configured in the following ways:

• WebSphere Portal and Sametime are configured to work together so that portlets can use People Awareness

• Sametime uses a native Domino Directory as the repository for Sametime user names

• Portal uses an LDAP server (such as IDS) that is different from the Domino Directory that is used by Sametime

Configuration settings for server-to-server connections for WebSphere Portal and the Sametime server are in the file: CSEnvironment.properties. You must add the correct values for two properties in the CSEnvironment.properties files so that People Awareness will work properly. After you make these changes, name mapping issues between the Sametime server and the Portal Server will resolve. Perform the following steps:

1. Access the machine where WebSphere Portal is installed.

2. Stop WebSphere Portal

3. Open the CSEnvironment.properties file. The CSEnvironment.properties file is installed in the WebSphere Portal /config directory.

4. Locate the property CS_SERVER_SAMETIME_1.nameFormatForResolve. Perform the following steps:

   1. Remove the comment tag (#) from the beginning of the line, if a comment tag is present.

   2. Change the value for this property to loginName or cn. For example, CS_SERVER_SAMETIME_1.nameFormatForResolve=loginName

      Note: The value loginName is the preferred setting. The value loginName in the LDAP for Portal should be present in the Domino Directory as the Short Name/UserID field. If cn is specified, the Common Name in the LDAP for Portal should be present in the Domino Directory, as one of the entries in the User Name field.

5. Locate the property CS_SERVER_SAMETIME_1.dnNameSeparator. Perform the following steps:

   1. Remove the comment tag (#) from the beginning of the line, if a comment tag is present.

   2. Change the value for this property to /. For example, CS_SERVER_SAMETIME_1.dnNameSeparator=/.

6. Save and close the CSEnvironment.properties file. Restart WebSphere Portal so that the changes take effect.

 

Tip: Configuring People Awareness to resolve name formats

In an environment where names in a directory are not unique, provide the appropriate value for the CS_SERVER_SAMETIME_1.nameFormatForResolve property so that People Awareness will resolve the name format. Select a value for this property that equals the user value within the People Awareness view. If it is most important to have a common name light up and the exact common name is unique, use cn for the setting. For example, assume the following is true:

• The common name (cn) for John Smith is "John Smith."

• Only one exact "John Smith" is in the directory.

• Another common name includes the string "John Smith," such as "John Smithy."

If the preceding is true, set the value for the CS_SERVER_SAMETIME_1.nameFormatForResolve property to cn so that when John Smith logs in to the portal, the name format will resolve, and the name John Smith will show online awareness.

An example of changing this setting is provided in the following steps:

1. Access the machine where WebSphere Portal is installed.

2. Stop WebSphere Portal

3. Open the CSEnvironment.properties file. The CSEnvironment.properties file is installed in the WebSphere Portal /config directory.

4. Locate the property CS_SERVER_SAMETIME_1.nameFormatForResolve. Perform the following steps:

   1. Remove the comment tag (#) from the beginning of the line, if a comment tag is present.

   2. Change the value for this property to cn. For example: CS_SERVER_SAMETIME_1.nameFormatForResolve=cn

5. Save and close the CSEnvironment.properties file.

6. Restart WebSphere Portal so that the changes take effect.

 

Note: Configuring People Awareness with Sametime 3.1

You may require additional configuration when using People Awareness with Sametime 3.1 and one of the following situations occurs.

• People Awareness may not work with Sametime 3.1 in your portal server environment when WebSphere Portal uses IBM Discovery Server and the Sametime 3.1 server uses Domino for LDAP.
• People awareness may not work with Sametime 3.1 in your discussion and teamroom portlets when your portal server and sametime servers use IBM Directory Server for LDAP.

   Configuration steps:

1. Ensure that your sametime server is set to allow both sttoken and ltpa token for authentication. This setting can be found in your sametime administration page under Configuration - Community Services.
2. Select Allow users to authenticate using either LTPA or Sametime Token.
3. Modify CSEnvironment.properties to use these settings:
   • CS_SERVER_SAMETIME_1.useLTPAToken=false
   • CS_SERVER_SAMETIME_1.dnNameSeparator=loginName
   • CS_SERVER_SAMETIME_1.nameFormatForResolve=/

 

Additional configuration for Lotus Domino

The following settings pertain to an optional configuration of Domino Directory in which two instances of Domino Directory are used. The following properties are disabled by default. In addition, information for configuring authenticated LDAP and encrypting a password is provided.

To retrieve user information from a secondary server, you can set values for the properties related to the mail server and mail file server, and email address. The secondary server is specified for the property CS_SERVER_DOMINO_DIRECTORY_1.custom_ldap_host

The following example shows the syntax with comments.

 # Optional advanced settings 
 # The following fields are disabled, by default.
 # If it is enabled (determined by custom_ldap_host) and a different server is specified,
 # The following user information will be retrieved from this secondary server.
 # Mail Server,  Mail file and Email address 
 #   
 #CS_SERVER_DOMINO_DIRECTORY_1.custom_ldap_host=my.server.com
 #CS_SERVER_DOMINO_DIRECTORY_1.custom_ldap_port=389
 #CS_SERVER_DOMINO_DIRECTORY_1.custom_ldap_ssl=true
 #CS_SERVER_DOMINO_DIRECTORY_1.custom_ldap_searchBase=base

 # Optional LDAP User credential overrides
 # default - uses Portal credentials or anonymous
 # Use tool PropFilePasswordEncoder.bat and 
 # PropFilePasswordEncoder.sh to encrypt the password
 # and copy the encrypted password to this file (see the example below).   
 #CS_SERVER_DOMINO_DIRECTORY_1.userid=username
 #CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd=pwd

 # Mail server and Mail File Queries: 
 #CS_SERVER_DOMINO_DIRECTORY_1.mailfileserver_objectclass=person
 #CS_SERVER_DOMINO_DIRECTORY_1.mailserver_attrib=mailserver 
 #CS_SERVER_DOMINO_DIRECTORY_1.mailfile_attrib=mailfile

 # Email Address query
 CS_SERVER_DOMINO_DIRECTORY_1.email_objectclass=person
 CS_SERVER_DOMINO_DIRECTORY_1.email_attrib=internetaddress

 

Tip: Configuring support for authenticated LDAP and encrypting the password

Features of the portal require that LDAP users access specific attribute types in Domino. For example, within the edit mode of some collaborative portlets, a picker list of available servers displays if the user has access to LDAP. Set up LDAP to be accessed by authenticated users by modifying following settings. Instructions for configuring support for authenticated LDAP and encrypting the password are provided.

To enable authenticated LDAP and encrypt the password, perform the following steps:

1. Open the CSEnvironment.properties file in a text editor. The CSEnvironment.properties file is installed in the WebSphere Portal /config directory.

   Note: It is a good practice to make a backup copy of the CSEnvironment.properties file before making any changes.

2. Remove the comment tags (#) from the beginning of the following two lines, if comment tags are present:

    CS_SERVER_DOMINO_DIRECTORY_1.userid=username
    CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd=pwd
   

3. Change the value for the CS_SERVER_DOMINO_DIRECTORY_1.userid property. For example, type:

   CS_SERVER_DOMINO_DIRECTORY_1.userid=cn=username, o=domain
   

4. Change the value for CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd property. For example, type:

   CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd=password
   

5. Save the CSEnvironment.properties file.

6. Perform the following steps to encrypt the password so that it does not appear as plain text within the file.

   WebSphere Application Server includes a utility that encodes passwords for you. This utility is called PropFilePasswordEncoder. Run the utility from a command line. The following instructions provide example steps for encoding the password for the value CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd in the CSEnvironment.properties file.

   1. Copy the line CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd=password and paste it into a new text file.

   2. Make sure a comment tag (#) is not at the beginning of the line. The PropFilePasswordEncoder utility removes lines that have a comment tag at the beginning.

   3. Save the new text file in the was_root/bin directory.

   4. Run the PropFilePasswordEncoder utility from the was_root/bin directory.

      If successful, the utility encrypts the password and saves the new text file. In addition, the utility creates a backup copy of the file.

   5. Open the new text file and copy the line CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd=encrypted_password.

   6. Paste this line into the CSEnvironment.properties. Make sure that you copy over the existing line that contains the CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd property.

7. Save and close the CSEnvironment.properties file.

8. Restart WebSphere Portal so that the changes take effect.

 

Additional configuration for User Credential customization

These advanced settings allow custom user credentials through the CSEnvironment.properties. An example is that an alternate Single Sign On token can be specified, instead of an LTPA token.

The following are custom credential settings with the possible values shown as variables:

CS_SERVER_CUSTOM_CRED.enabled=true/false
CS_SERVER_CUSTOM_CRED.useridAttribSource=header/cookie
CS_SERVER_CUSTOM_CRED.useridAttrib=useridAttribName
CS_SERVER_CUSTOM_CRED.ssoTokenAttribSource=header/cookie
CS_SERVER_CUSTOM_CRED.ssoTokenAttrib=tokenAttribName

 

Performance tuning parameter for Domino Directory

The following property is available to improve performance for Domino Directory. If you are using Domino Directory as the primary (and only) LDAP server for WebSphere Portal, you can set the following property to false.

CS_PERF_PROP_USEWMM.enabled=true