IBM Connections Mail-Plug-in Integration with iNotes

In this article I want to go through the installation, configuration and troubleshooting of IBM Connections Mail-Plug-in in cohesion with Domino iNotes.

Requirements:

  • SSO needs to be configured between iNotes and Connections Server.
  • If you don’t use public certificates you will have to import the self-signed Certificate into WAS.
  • Download the newest Version, currently 1.6 iFix 2, of IBM Connections Mail, from IBM Greenhouse. Take your time, this might be tricky.  🙂

Installation:

Note: You do not need to stop your WebSphere Applications before you proceed.

1. Make sure you have the newest version of Installation Manager installed.

2. Start the Installation Manager as Administrator or disable the UAC.

1

3. Add the IBM Connections Mail repository.

  2  3  2

4. Start with the installation.

2

Make sure you don´t place the installation directory under “Program Files (x86)”, I also tend to delete blanks in the folder name.

2  2  2  2

Configuration

Authorizing Users to Access the Mail Plug-In

1. Open the ISC.

2. Navigate to “Applications” –> “Application Types” –> “WebSphere enterprise applications” –> “Common”.

2

3. Select “Configuration” Tab, then “Security role to user/group mapping”.

2

4. Select the “mail-user” role via checkbox and then map it to “All Authenticated in Application´s Realm” special subject if you want to allow all Users to use the plug-in.

2

5. Click OK and save.

After that the Mail Plug-In buttons are going to be visible for all Users in the navigation panel, but you are going to get an error if you try to use them.

Enable Discovery Service for the Mail Plug-In

I have chosen to go with the following configuration, just to make sure that the Plug-In works in case that both HTTP and HTTPS is used to access Connections Server, Mail Plug-In is still going to access E-Mails on iNotes Server solely via HTTPS.

http://www-01.ibm.com/support/knowledgecenter/SSVMJU_1.6.0/icm_update_discovery.dita?lang=en

1. Copy the “socialmail-discovery-config.xsd” and “socialmail-discovery-config-template.xml” files from the mail plug-in installation folder to “WAS-root/AppServer/profiles/Dmgr01/config/cells/cell-name/LotusConnections-config”.

2

Make sure to check the optional settings in the official documentation.

2. Rename the newly copied XML file to “socialmail-discovery-config.xml”.

3. Open the XML file in your preferred editor.

4. Enter the following information:

2

Delete everything else you do not need.

5. Save the file and synchronize the nodes.

6. Apply the configuration.

7. Check the discovery service via following URL:

https://<Hostname>/connections/resources/discovery/DiscoveryServlet?email=<yourMail

The Output should be similar with the following:

1

After that mail and calendar information should be accessible in the navigation panel.

1

1  1

Activate Help Content for the Mail-Plug-in

1. Copy the “Help.ear” file to your Desktop or any other location, where you can work with it, then open the file with any archiver Software.

  • It is located under: <drive>\IBM\WebSphere\AppServer\profiles\<deployment manager profile>\config\cells\ic-cell-q\applications\Help.ear

2. Open “Help.ear” file with any archiver software and delete the following folder:

1

3. Download the Help files needed:

4.  Now you will need to extract the downloaded File and paste it in same directory from which we deleted „com.ibm.connections.mail.help“ folder.

5. Then just replace the newly edited “Help.ear” file with the new one. You will need to open ISC to do that.

1

6. Click “Browse” and locate the “Help.ear” File.

1

7. Click “Next”.

1

8. Click “Next” until you get the “Finish” button and then click “Save”.

9. After that you should synchronize the nodes.

Now you will need to add the Mail-Plug-in Help section to the Systems Help Table of Contents.

10. Start the “wsadmin” tool.

<drive>:\IBM\WebSphere\AppServer\profiles\<deployment manager profile>\bin>wsadmin -lang jython -user <user> -password <password>

11. Type the following commands:

  • execfile(“connectionsConfig.py”)
  • LCConfigHelp.setHelp(“c:/IBM/tmp”,”activities”,”blogs”,”bookmarks”,”communities”,”files”,”forums”,”homepage”,”profiles”,”wikis”,”icmail”,”ibmdocs”)

Make sure you do not get any errors in the output.

1

This will add the Mail-Plug-in Help section (“icmail”), you need to include help sections for all other application. The ones you left out will not be listed in the help application content.

12. Stop the help application.

13. Go ahead and delete the cached help files from the app server where help is installed. You will have to do this on all nodes where the help application is installed.

1

14. Start the help application.

The new help section should be available now.

1   1

Test vigorously and enjoy… 🙂

1

Troubleshooting

The Mail-Plug-in uses the same log as the “News” Application.  The following debug parameter could be set for the News Server to help you troubleshoot issues with the discovery service “com.ibm.social.pim.discovery.*=all“.

Initialy I had problems with the SSL Handshake, on the connections side there were no errors to point me in the right direction, even with the discovery service debug parameter, mentioned above, set. Here is where Daniel Nashed helped me, he provided me with the debug parameters for the HTTP task on the Domino server.

HTTP Task debug parameters:

DEBUG_SSL_CIPHERS=2
DEBUG_SSL_DHE=2
DEBUG_SSL_HANDSHAKE=2
DEBUG_SSL_IO=0

Error in the GUI:

error

Errors in the log file of the iNotes Server:

HTTP Server: SSL handshake failure, IP address [<IP_ADDRESS>], Keyring [<KeyringFile>], [SSL Error: Invalid peer], code [4171]

SSL_Handshake> After handshake state = HandshakeClientKeyExchange (11); Status = -5000
int_MapSSLError> Mapping SSL error -5000 to 4176 [SSLHandshakeNoDone]
SSLSendAlert> Sending an alert of 0x0 (close_notify) level 0x2 (fatal)
SSL_Handshake> After handshake2 state SSLErrorClose (2)
int_MapSSLError> Mapping SSL error -5000 to 4176 [SSLHandshakeNoDone]
SSL_Handshake> After handshake2 state SSLErrorClose (2)
SSL_Handshake> SSL Error: -6989
int_MapSSLError> Mapping SSL error -6989 to 4165 [SSLConnectionClosedError ]

SSLAdvanceHandshake Exit> State HandshakeClientKeyExchange (11)
SSL_Handshake> After handshake state = HandshakeClientKeyExchange (11); Status = -5000
int_MapSSLError> Mapping SSL error -5000 to 4176 [SSLHandshakeNoDone]
SSLProcessProtocolMessage> Record Content: Alert (21)
SSLProcessAlert> Got an alert of 0x50 (internal_error) level 0x2 (fatal)
SSL_Handshake> After handshake2 state HandshakeClientKeyExchange (11)
SSL_Handshake> SSL Error: -6994
int_MapSSLError> Mapping SSL error -6994 to 4171 [SSLFatalAlert]

Our iNotes Server has a 9.0.1 FP4 IF2 Domino version, on the other side I had an IBM Connections 5.0 CR3 and 8.5.5.4 version of IHS. So the problem was in the configuration of IHS, the SSL Cipher Suites were not configured, therefore the defaults were used. A fast fix for this was to set “SSLCIPHERSPEC=2F35” parameter in the “notes.ini” of the iNotes Server because at that point my IHS could not use any newer SSL Cipher. “SSLCIPHERSPEC=2F35” means that the iNotes server will accept only “RSA_WITH_AES_128_CBC_SHA” and “RSA_WITH_AES_256_CBC_SHA” ciphers.

After that the Connections Mail-Plug-in worked just fine. 🙂

Advertisements

IBM Connections Plug-ins for Notes & SSL Certificate with RSA key greater than 2048

Before installing a SSL certificate on an IBM HTTP Server, which is used for IBM Connections applications, keep in mind that if the RSA key size exceeds 2048 Notes users won’t be able to access the data in Connections using “IBM Connections Plug-ins for Notes” via HTTPS.

If you do so the following errors will appear in Notes Client:

Activities Error   Files Error

  • Cannot connect to the Activities Server. Either the URL is incorrect, the server is down, or a firewall may be preventing you from reaching the server. Check the URL, your firewall settings and the server status and try again.

Notes client trace log errors:

  • CWPST0306W: An exception occurred while invoking the target method login.
  • javax.security.auth.login.LoginException
  • javax.net.ssl.SSLKeyException: RSA premaster secret error
  • java.io.IOException: RSA premaster secret error
  • java.security.InvalidKeyException: Illegal key size or default parameters

The solution is to change the java policy files on a client with unrestricted java policy files. You can download the files needed from

https://www-01.ibm.com/marketing/iwm/iwm/web/reg/pick.do?source=jcesdk&lang=en_US.

You can check the version with the “java –version” command. You should do that in order to determine which version of java policy files you need.

java -version

In this case I would download and use “Files for older versions of the SDK”, from the URL mentioned above.

IBM Unrestricted SDK JCE policy files

To exchange the java policy files, just overwrite the files with the downloaded files in “<Notes installation directory>\jvm\lib\security”. After that the “IBM Connections Plug-ins for Notes” will work as supposed.

You should also know that after updating the Notes client, the java policy files will be overwritten with default files and the problem will occur again.

I tested and reproduced this issue on Notes 9.0.1 FP2, FP3 and FP4 client.

I hope this will help you to take all precautions so that your Notes users won´t experience this error.