Configuring SSO between HCL Docs, File Viewer and WebSEAL

After you configure SSO between HCL Connections and WebSEAL, you must then configure HCL Docs, HCL File Viewer and WebSEAL.

About this task

The following steps assume that HCL Docs and HCL Connections are in the same cell.

Procedure

  1. Ensure that the WebSEAL, IBM HTTP Server, Connections, HCL Docs, and Document Format Conversion servers can ping each other.
  2. Optional: Import Active Directory users to IBM Security Access Manager (ISAM).
    Note: If you already imported the users to Security Access Manager when you configured Connections, you can ignore this step and go to step 3.

    Launch pdadmin and log in:

    1. Import the user:

      user import –gsouser user-id user-full-dn

      For example: user import –gsouser test2 "cn=test2,ou=org1,dc=cn,dc=ibm,dc=com"

    2. Validate the user:

      user modify user-id account-valid yes

      For example: user modify test2 account-valid yes

  3. Create a transparent path junction for the /docs, /docs/rtc, /viewer, and /conversion url:
    Launch pdadmin, log in to the WebSEAL server, and run the following command:
    server task WebSEAL-instance-name create -t ssl -h backend-server-name -x -p backend-server-port -i -b ignore -f -A -2 -F ltpa-token -Z ltpa-password -k /docs

server task WebSEAL-instance-name create -t ssl -h backend-server-name -x -p backend-server-port -i -b ignore -f -A -2 -F ltpa-token -Z ltpa-password -k -l soft-worker-limit -L hard-worker-limit /docs/rtc

server task WebSEAL-instance-name create -t ssl -h backend-server-name -x -p backend-server-port -i -b ignore -f -A -2 -F ltpa-token -Z ltpa-password -k /viewer

server task WebSEAL-instance-name create -t ssl -h backend-server-name -x -p backend-server-port -i -b ignore -f -A -2 -F ltpa-token -Z ltpa-password -k /conversion

    Where:

    WebSEAL-instance-name is the name of the WebSEAL server. Use the following syntax:
    • WebSEAL_instance-webseald-tam_server, for example, default-webseald-server.name.example.com.
    • backend-server-name is the domain name of the Connections server for which Security Access Manager is managing authentication, for example, IBM® HTTP Server configured for Connections.
    • backend-server-port is the port that is used by the backend server.
    • ltpa-token is the name of the file that you created to store the keys that you exported from WebSphere® Application Server.
    • ltpa-password is the password that you defined to encrypt the key file.
    • soft-worker-limit is the value (percent) on the junction that defines the soft limit for consumption of worker threads.
    • hard-worker-limit is the value (percent) on the junction that defines the hard limit for consumption of worker threads. As in the global hard limit setting, this option causes warning messages to be issued when the junction tries to consume more worker threads than allowed by the setting. In addition, the user is sent a 503 "Service Unavailable" message.
    For example:
    server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password -k /docs

server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password -k -l 40 -L 80 /docs/rtc

server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password -k /viewer

server task default-webseald-server.name.example.com create -t ssl -h another.server.name.example.com -x -p 443 -i -b ignore -f -A -2 -F C:\WAS7_ltpa.keys -Z password -k /conversion

    The /docs/rtc junction is used for the long polling for co-editing. Each co-editing request keeps a connection (thread) in WebSEAL, so you must have a separate junction to handle such requests.

  4. Attach the default ACL for the created transparent path junction. Use the ACL that is created for Connections, for example, lc3-default-acl

    acl attach /WebSEAL/tam_server-WebSEAL_instance/docs lc3-default-acl

    acl attach /WebSEAL/tam_server-WebSEAL_instance/viewer lc3-default-acl

    acl attach /WebSEAL/tam_server-WebSEAL_instance/conversion lc3-default-acl

    Where:
    • tam_server is the host name of the Security Access Manager server
    • WebSEAL_instance is the name of the instance of the WebSEAL server that is configured to manage Connections, for example, default
    • lc3-default-acl is the access control list (ACL) that you defined in step 5 of Enabling single sign-on for Security Access Manager when you configured Connections, for example, acl attach /WebSEAL/tam.example.com-default/docs lc3-default-acl.
  5. Revise the webseald.conf file to enable large size post and special characters:

    Open the webseald.conf file and add the following parameters:

    dynurl-allow-large-posts = yes

    suppress-dynurl-parsing-of-posts = yes

  6. Change server_url in concord_config.json for Connections Docs:
    1. Find the configuration file concord-config.json on Deployment Manager and edit it. The default folder is <WAS_Home>/profiles/Dmgr01/config/cells/cellname/IBMDocs-config.
    2. Find the following section:
      {
              "config": {
                "server_url": "https://example.com/files",
                "j2c_alias": "connectionsAdmin"
              },
              "id": "lcfiles",
              "class": "com.ibm.docs.repository.files.LCFilesCMISRepository"
            },

      Change the host name (for example, example.com) in server_url to WebSEAL host name. The host name must be consistent with interService URL values in the LotusConnections-config.xml file.

    3. Find the following section:
      {
              "config": {
                "auth_type": "FORM",
                "auth_host": "https://example.com" 
              },
              "id": "lcfiles",
              "class": "com.ibm.docs.authentication.filters.LotusConnectionsAuth"
            },

      Revise or add the variables. The value of auth_type is TAM, and the value of auth_host is the WebSEAL host name.

    4. Find the following section:
      "conversionService": {
            "s2s_token": "fallseason2011",
            "numberofretry": "120",
            "resulturl": "http://example.com/conversion/ConversionResult",
            "socketTimeout": "30000",
            "serviceurl": "http://example.com/conversion/ConversionService",
            "j2c_alias": "docsAdmin",
            "intervalofretry": "1000"
          }

      Change the host name (for example, example.com) in resulturl and serviceurl to WebSEAL host name.

    5. Change other hostnames that are related with Connections url to webseal host names.
  7. Change server_url in viewer_config.json for the Connections Viewer:
    1. Find the configuration file viewer-config.json on Deployment Manager and edit it. The default folder is <WAS_Home>/profiles/Dmgr01/config/cells/cellname/IBMDocs-config.
    2. Find the following section:
      "class":"com.ibm.concord.viewer.lc3.auth.LotusConnectionsAuth",
     "config" :
          {
               "auth_type": "FORM",
               "auth_host": "https://example.com"
                                                                }

      Revise or add the variables. The value of auth_type is TAM, and the value of auth_host is the WebSEAL host name.

    3. Find the following section:
      "conversionService":
           {
                "serviceurl":"http://example.com/conversion/ConversionService",
                "resulturl":"http://example.com/conversion/ConversionResult",
                "j2cAlias": "docsAdmin",

      Change the host name (for example, example.com) in resulturl and serviceurl to WebSEAL host name.

  8. Change viewer_url in conversion-config.json for Connections Conversion:
    1. Find the configuration file conversion-config.json on Deployment Manager and edit it. The default folder is <WAS_Home>/profiles/Dmgr01/config/cells/cellname/IBMDocs-config.
    2. Find the following section:
      "topology": {
"viewer": "http://example.com/viewer"
},
      Change the host name (for example, example.com) in "viewer" to WebSEAL host name.
  9. Change server_url in docs-daemon-config.json and viewer-daemon-config.json:
    1. Find the configuration file docs-daemon-config.json and viewer-daemon-config.json on Deployment Manager and edit it. The default folder is <WAS_Home>/profiles/Dmgr01/config/cells/cellname/IBMDocs-config.
    2. Find the line of server_url, and change the host name in server_url to WebSEAL host name in the two files.
  10. Update docsAdmin to a user in LDAP:
    1. In the WebSphere Application Server administration console, select Security > Global security.
    2. In the Authentication area, expand Java Authentication and Authorization Service, and click J2C authentication data.
    3. Click the docsAdmin alias to edit it. Change the user to one in LDAP.
    4. Apply and save the changes.
    5. In the WebSphere Application Server administration console, expand Applications > Application Types and then select WebSphere enterprise applications. Find and click IBMDocs.
    6. Click Security role to user/group mapping. Find the role docsAdmin in the Role column and then click Map users or Map groups. In the Search String box, type the name of the user from step c and then click Search. If the user or group exists in the directory, it is displayed in the Available list. Select the user from the list and then move it to the Selected column. Click OK and then click Save to save the changes.
  11. Update viewerAdmin to a user in LDAP:
    1. In the WebSphere Application Server administration console, select Security > Global security.
    2. In the Authentication area, expand Authentication and Authorization Service, and click J2C authentication data.
    3. Click the viewerAdmin alias to edit it. Change the user to one in LDAP.
    4. Apply and save the changes.
    5. In the WebSphere Application Server administration console, expand Applications > Application Types and then select WebSphere enterprise applications. Find and click ViewerApp.
    6. Click Security role to user/group mapping. Find the role viewerAdmin in the Role column and then click Map users or Map groups. In the Search String box, type the name of the user used in step c and then click Search. If the user or group exists in the directory, it is displayed in the Available list. Select the user from the list and then move it into the Selected column. Click OK and then click Save to save the changes.
  12. Save these files and synchronize to all nodes, and restart Docs Cluster, Viewer Cluster and Conversion Cluster.