IBM Support

Using HTTPS When Rendering OpenSocial Gadgets

Technote (troubleshooting)


Problem

Notes® and Domino® 9.0.1 Social Edition provide some improvements in how OpenSocial gadgets render over HTTPS.

Background

When a user opens an OpenSocial gadget from the Notes client, the gadget is rendered in the embedded XULRunner browser. For OpenSocial deployments that require secure HTTPS connections between Notes clients and the Domino server with Shindig, SSL certificates verify that the connection from the server is trusted. Before the embedded browser can render the gadget, it must verify that the certificate from the server is certified by a trusted CA. If the certificate presented to the Notes client is untrusted, Notes prompts the user to create a cross certificate before it allows access to gadget data. In general, the embedded browser trusts certificates from well-known certificate authorities (CAs), such as GeoTrust or VeriSign.

CAs trusted by the Notes 9.0.1 embedded browser

By default, the embedded browser in Notes 9.0.1 Social Edition trusts the same set of root certificates as Mozilla Firefox 24 Extended Service Release. For a complete list of the certificates that are included in Firefox 24 ESR, see the following page on the Mozilla website: http://www.mozilla.org/projects/security/certs/included/.

Using self-signed certificates

It is generally best to install certificates that are signed by well-known CAs on the Domino server with Shindig. Using such well-known certificates guarantees that users are not confronted with potentially confusing cross-certification requests. Still, self-signed certificates are supported, although the embedded browser does not trust them by default. Administrators who must use self-signed certificates can establish trust for their certificates and then deploy them to Notes clients on the network. You must establish trust for any self-signed certificate used by your OpenSocial gadgets, including wildcard certificates used for locked domains and certificates used for unlocked domains.

To establish trust for a self-signed certificate, an administrator can first import the certificate into the Domino Directory, and then use a desktop policy to push it to Notes clients. Notes clients store certificates in their Contacts applications (names.nsf). After a client obtains and stores a local copy of a self-signed certificate, it is able to verify that the connection to the gadget server is trustworthy. The next time a gadget presents the certificate, Notes locates the certificate in its Contacts application, and registers an exception for it. After Notes establishes an exception, the browser can accept the certificate during future encounters without first checking for the certificate.

Even after clients obtain the necessary self-signed certificates, users can still experience problems the first time they open a gadget. For example, a gadget might re-render several times. This problem occurs the first time that the user accesses the gadget only, and only when a gadget uses an untrusted self-signed certificate. You can prevent these initial rendering issues by providing clients with a cert8.db file that lists the CA for the self-signed certificate. Because the browser automatically trusts the CAs listed in the cert8.db file, gadgets can render without issues.

XULRunner and Firefox employ the same default cert8.db file. The easiest way to establish trust for your signing authority is to add it to the default Firefox cert8.db file, and then deploy the file to clients.

Obtaining, modifying, and deploying a cert8.db file

  1. Add a new Firefox profile. For more information, see this support topic on the Mozilla website: https://support.mozilla.org/en-US/kb/profile-manager-create-and-remove-firefox-profiles.
    Use a new profile to avoid overwriting settings in your existing profile.
  2. From the new Firefox profile, open a web page that uses the untrusted certificate. If the browser has not previously accepted the certificate, it displays a message warning that the connection is untrusted.
  3. Click I understand the risks to bypass the warning, and then following the prompts to add and confirm a security exception. By confirming the exception, you establish trust for the site's certificate. After the page renders, the certificate authority is automatically added to the cert8.db file for the Firefox profile.
  4. Confirm that the certificate authority was added to the cert8.db file by running the following command:
    certutil.exe -L -d "
    Path_to_Firefox_profile"

    For information on how to download certutil, see this support question on the Firefox website:http://support.mozilla.org/en-US/questions/952035.
  5. Deploy the updated cert8.db file to users' workstations. Details about methods for deploying the certificate file are beyond the scope of this technote.
  6. After you distribute the cert8.db file to users, use settings in the Notes plugin_customization.ini file to copy the cert8.db file to the correct directory. In a text editor, open the Notes plugin_customization.ini file in notes_install/framework/rcp/, and specify values for the following settings:

    com.ibm.rcp.browser/cert8DBVersion = version_identifier (alphanumeric value)
    com.ibm.rcp.browser/cert8DBFilePath = path_to_cert8.db_source

    On a Linux workstation, the default notes_install directory is /opt/ibm/notes/framework/rcp; on Windows, the default directory is C:\Program Files (x86)\IBM\Notes\framework\rcp
  7. Set the value of cert8DBFilePath to the full path name for the cert8.db file that you deployed to workstations in Step 5.
  8. After you save the file, push the settings in the plugin_customization.ini file to users by configuring a desktop policy. For more information on using desktop policies to modify settings on Notes clients, see Assigning Eclipse preference settings using a desktop policy in the Domino Administrator Help.
Each time that you change the version identifier for the variable com.ibm.rcp.browser/cert8DBVersion, the file that is referenced by the variable com.ibm.rcp.browser/cert8DBFilePath is copied to users' Notes browser profile in notes_data /workspace/BrowserProfile.

Thus, any time you want to force an update of the cert8.db file on the Notes client, you can do so by changing the value of com.ibm.rcp.browser/cert8DBVersion.

Requirements for using self-signed certificates in iNotes

IBM® iNotes® uses inline frames (iframes) to render gadgets. Because most modern browsers require a trusted certificate to render content within iframes, you must deploy self-signed certificates used by OpenSocial gadgets to iNotes users' browsers. For information on how to deploy self-signed certificates to a browser, refer to the documentation for your browser.


Cross reference information
Segment Product Component Platform Version Edition
Messaging Applications IBM iNotes OpenSocial AIX, Linux, Windows 9.0.1

Document information

More support for: IBM Domino
OpenSocial

Software version: 9.0.1

Operating system(s): AIX, Linux, Windows

Reference #: 1654086

Modified date: 28 July 2017