Additional configuration for collaboration

This topic provides information for editing the CSEnvironment.properties file to support additional configurations offered by collaboration for IBM Lotus Team Workplace and IBM Lotus Instant Messaging and Web Conferencing. Some tips are provided in this topic to demonstrate possible configurations.

Important: The configuration tasks that you use to configure WebSphere Portal to use products such as Domino and Lotus Instant Messaging and Web Conferencing 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

Configuration settings for using collaboration with WebSphere Portal have been consolidated into a single file: CSEnvironment.properties. The CSEnvironment.properties file, is installed in the

  • Windows/UNIX: wp_root\shared\app\config directory.

This file contains the following information about the portal environment:

  • A flag to indicate whether the Collaborative Services are being used within the portal context
  • Location, protocol, port and version of Lotus Team Workplace server
  • Location, protocol, port and version of Discovery Server server
  • Location, protocol, port and version of Domino Directory server (needed for Notes portlets)
  • Location, protocol, port and version of Lotus Instant Messaging and Web Conferencing server
  • Configuration and Performance tuning settings specific to Lotus Collaborative Services.

 

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 Instant Messaging and Web Conferencing

This section contains information for setting values related to Lotus Instant Messaging and Web Conferencing when it is configured with Portal Server.

 

Specify to use the LTPA token for logging into Lotus Instant Messaging and Web Conferencing

You can override the credential settings in the CSEnvironment.properties file to enable an LTPA token for logging in to Lotus Instant Messaging and Web Conferencing.

By default, an internal Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing instead of the LTPA token.

 

Specify server connection properties for obtaining Lotus Instant Messaging and Web Conferencing tokens for users

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

  • Port through which the Lotus Instant Messaging and Web Conferencing 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

  • Lotus Instant Messaging and Web Conferencing reconnect interval

    The property is: CS_SERVER_SAMETIME_1.reconnect

    To change the reconnect interval in seconds to the Lotus Instant Messaging and Web Conferencing 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.

  • Lotus Instant Messaging and Web Conferencing timeout value

    The property is: CS_SERVER_SAMETIME_1.timeout

    The maximum amount of time in seconds to wait for a response from the Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing 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, Lotus Instant Messaging and Web Conferencing data (and Lotus Team Workplace 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 Lotus Instant Messaging and Web Conferencing server, and the name used to log in to Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing 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 Lotus Instant Messaging and Web Conferencing are configured in the following ways:

  • WebSphere Portal and Lotus Instant Messaging and Web Conferencing are configured to work together so that portlets can use People Awareness
  • Lotus Instant Messaging and Web Conferencing uses a native Domino Directory as the repository for Lotus Instant Messaging and Web Conferencing user names
  • Portal uses an LDAP server (such as IDS) that is different from the Domino Directory that is used by Lotus Instant Messaging and Web Conferencing

Configuration settings for server-to-server connections for WebSphere Portal and the Lotus Instant Messaging and Web Conferencing server are in the file: CSEnvironment.properties. 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 Lotus Instant Messaging and Web Conferencing 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 Windows/UNIX: wp_root\shared\app\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 Windows/UNIX: wp_root\shared\app\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 Sametime 3.1 to support portlet features

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

  • People awareness does not work, or a user cannot log in to the Sametime server with the Sametime Connect portlet, if WebSphere Portal and Sametime 3.1 use different LDAP servers (for example, WebSphere Portal uses iPlanet or IBM Directory Server and Sametime 3.1 uses a native Domino Directory).
  • People awareness may not work with Sametime 3.1 in your discussion and teamroom portlets when WebSphere Portal and Sametime 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. You can 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 Windows/UNIX: wp_root\shared\app\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. Windows/UNIX: This utility is called PropFilePasswordEncoder.bat or PropFilePasswordEncoder.sh (for UNIX systems). This utility is installed in the was_root/bin directory. 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. Windows/UNIX: For example: 
      PropFilePasswordEncoder.bat new_text_file_name CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd

      where new_text_file_name is the name of the new text file, and CS_SERVER_DOMINO_DIRECTORY_1.encryptedpwd is the property.

      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 signon (SSO) 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

 

Use case 1: Overriding the logged in user credential with a custom user name

The settings in this example show how to customize or override the logged in user's credentials through a custom user name.

These settings are useful for for mapping principal user identities (fully-qualified user names or DNs) between two LDAP systems. In this case, the user name (USERID) is retrieved from the header. USERID is the name of the attribute that holds the data. 

CS_SERVER_CUSTOM_CRED.enabled=true
CS_SERVER_CUSTOM_CRED.useridAttribSource=header 
CS_SERVER_CUSTOM_CRED.useridAttrib=USERID

 

Use case 2: Overriding the logged in user credential with a custom SSO token

The settings in this example show how to customize or override the logged in user's credentials with a custom SSO token that is generated from an external security manager, such as SiteMinder. In this case, the tokenAttribName setting is retrieved from the cookie. 

CS_SERVER_CUSTOM_CRED.enabled=true
CS_SERVER_CUSTOM_CRED.ssoTokenAttribSource=cookie
CS_SERVER_CUSTOM_CRED.ssoTokenAttrib=SESSION

 

Use case 3: Enabling settings when both a custom SSO token and a custom user name are required

If your configuration requires the use of a custom SSO token and two LDAP servers, you can enable the settings as shown below. 

CS_SERVER_CUSTOM_CRED.enabled=true
CS_SERVER_CUSTOM_CRED.useridAttribSource=header 
CS_SERVER_CUSTOM_CRED.useridAttrib=USERID 
CS_SERVER_CUSTOM_CRED.ssoTokenAttribSource=cookie
CS_SERVER_CUSTOM_CRED.ssoTokenAttrib=SESSION

 

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

Home | Support | Terms of use | Feedback

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.