< Previous | Cookbook Contents

Overview

The OpenSocial Component functionality must be enabled at the server level in order for OpenSocial gadgets and Embedded Experiences to work in the Notes and iNotes clients. The goal of this article is to add context to the official documentation and to explain the concepts in more depth so that an administrator can make informed decisions about the configuration he or she is performing.

For more information on how the Domino Server with Shindig is utilized by Notes and iNotes clients, see Gadget rendering process.

Web SSO Configuration

Single-sign on (SSO) configuration is critical when deploying the OpenSocial Component functionality or Domino servers in general. The OpenSocial Component has some general requirements around SSO. Configuring Domino SSO is outside of the scope of this article. More information on SSO configuration can be found in the Domino product documentation, for instance:
Multi-server session-based authentication (single sign-on)
Creating a Web SSO configuration document

SSO Scenarios

• “Single Server” SSO may be configured if mail and shindig server are the same AND not enabling Notes clients. "Multi-server" SSO will work for these scenarios as well.
• “Multi-server” SSO must be configured if mail and shindig servers are different OR enabling Notes clients

iNotes Mail Server

Configuration of the iNotes Mail Server consists of two primary pieces: enabling client-side functionality and enabling automatic updates of Widgets in iNotes. If an administrator is not deploying iNotes, this entire section can be skipped.

Enabling Client-Side Functionality

By default, all OpenSocial Component functionality is disabled in the iNotes client. To enable the client-side functionality refer to:
For 9.0, Using notes.ini file settings to enable widgets, embedded experiences, live text and OpenSocial features.
For 9.0.1 Using notes.ini file settings to enable widgets, embedded experiences, live text and OpenSocial features.

Enabling Automatic Updates of Widgets

Widgets in iNotes require some extra configuration in order that they are pushed by policy and updated automatically for end users. To perform this setup, refer to:
For 9.0, Configuring automatic updates for widgets. One caveat is documented in the Widgets Live Text, and OpenSocial Admin Documentation Updates for IBM iNotes 9.0 technote. Specifically, the Widgets AutoUpdate task will run once per day by default.
For 9.0.1, Configuring automatic updates for widgets.

Automatic Updates Verification

An administrator can view more information about Widgets automatic updates by querying the DOTs framework using the task ID "UpdateWidgetsTask". Logs from the UpdateWidgetsTask will appear in the <Domino data directory>/domino/workspace-dots/logs on the iNotes mail server. See collecting support data for more information on enabling logging.

Manually run the UpdateWidgetsTask


See information about the UpdateWidgetsTask, including how often it is scheduled to run and the last time it ran

Domino Server with Shindig

Configuration of the Domino Server with Shindig is managed via a configuration settings document.

The 9.0 version of pubnames.ntf contains a new "Social Edition" tab within the configuration settings document that is used to configure the Domino Server with Shindig.
The 9.0.1 version of the pubnames.ntf contains a new field, "Configuration for Domino Server with Shindig", on the "Basics" tab within the configuration settings document. This must be enabled to display the "Social Edition" tab.

For more information, please see:
For 9.0, Creating a configuration settings document for all servers that run Shindig.
For 9.0.1, Creating a configuration settings document for all servers that run Shindig.

Note: One does not need to create a new configuration settings document. If a configuration settings document already exists for the Domino Server with Shindig, its configuration settings document can simply be updated to add the new settings.

Basics

The "Basics" tab contains required fields that are used to configure Locked domains 9.0 or Locked domains 9.0.1. These fields (Locked domain suffix, Domain name for unlocked gadgets and content fetching, Shindig server(s) host name) are explained in more detail below. Locked Domains is enabled by default. Enabling the use of Locked Domains is recommended for use with Notes and iNotes clients. The configuration of Locked Domains is the same when using Notes or iNotes clients. The Apache Shindig wiki provides some information on locked domains in an "Overview" section. The rest of the information on that page is tailored for Apache Shindig developers and deployers and may not be relevant for IBM products. See the "Locked Domains" section below for more information.

The "Basics" tab also contains two optional fields related to caching: "Total cache in memory" and "Total cache on disk". The context help in the template has explanations for the format of the values. These fields may be left blank; however, one may see CONFIG messages in the Domino Server with Shindig's workspace logs that log a stack trace if one's logging levels are set to show CONFIG level logging. These CONFIG messages can be safely ignored as default values will be used. For instance, here are the logging messages when no value is set. The stack trace has been omitted to save space.

See collecting support data for more information on enabling logging.

Locked Domains

In 9.0.1, the Locked Domain enablement field was added to the Basics tab. Its default is 'Enabled'. Enabling this field enables the use of Locked Domains and enables the Locked domain suffix field. In 9.0, you can use the Advanced tab to disable Locked Domains. See the Advanced/Locked Domains section below for more details.

Locked domain suffix

The locked domain suffix is a partial hostname that is used to generate unique domains for OpenSocial gadgets, including Embedded Experiences. A prefix that is unique to each gadget is pre-pended to the locked domain suffix to generate a unique domain within which the gadget iframe renders. This requires that the domain used in the suffix has a wildcard DNS entry so that the unique domain generation results in a valid, resolvable sub-domain.

For example, enter

and an OpenSocial gadget will render on a domain such as

Domain name for unlocked gadgets and content fetching

The "domain name for unlocked gadgets and content fetching", hereafter referred to as "the unlocked domain", is used for fetching content, as the name describes. CSS, JavaScript, images, and other static resources loaded by the OpenSocial gadget via <style>, <script>, and <img> tags will be loaded on this domain. The unlocked domain is shared amongst all OpenSocial gadgets in order to increase cacheability of these resources by the browser.

For example


IMPORTANT: To ensure security of SSO tokens, the unlocked and locked domains should be set to a separate second-level domain that is an alias of the Domino Server with Shindig. For example, if the iNotes server is loaded at "mymail.renovations.com" and SSO tokens are scoped to ".renovations.com", the unlocked domain could be something like "unlocked.renovations-gadgets.com" and the locked domain could be something like "-locked.renovations-gadgets.com". This ensures the OpenSocial gadgets don't have access to SSO tokens. Gadgets wishing to access protected resources should use OAuth.

What is a SLD (second-level-domain):
A Second level domain is the part of the domain name immediately in front of .com, .org, .edu. For example. foo.com and foobar.com are different second level domains (foo vs foobar). Browser's use second level domains to implement the same domain security policy. A page on domain "foo" cannot access cookies of domain "foobar". This is especially important when security mechanisms, such as LTPA are used that scope cookies to the SLD, such as "foo.com" to enable Single Sign On.

Shindig server(s) host name

This hostname is used by the Domino Server with Shindig when authorizing users with an OAuth provider, i.e., "doing the OAuth dance". As part of the OAuth dance, a callback/redirect URI is generated and given to the OAuth provider. The host name provided in this field is used in that callback URI.

The form of the callback URI for OAuth1.0a is as follows:


The form of the callback URI for OAuth2 is as follows:


By default, the callback URIs are generated using https, as this is the recommendation of both OAuth1.0a and OAuth2 specifications. Some OAuth providers, such as IBM Connections 4, will perform strict comparisons when doing the OAuth dance. In this case, if the callback URI provided by Domino does not match the URI used when registering the OAuth client with the provider, the OAuth dance will fail.

Use HTTPS for oAuth redirect URLs

In 9.0.1, the 'Use HTTPS for oAuth redirect URLs' field was added. Use this field to enable or disable SSL when building oAuth callback URIs to meet strict comparison requirements. Use of HTTPS is enabled by default. In 9.0, you can use the Advanced tab to configure OAuth callbacks to use http rather than https. See Advanced/Oauth Callbacks for more details.

Advanced

No settings in the "Advanced" tab are required. The default values used result in the most secure settings for a deployment, including locked domains and the requisite DNS configuration that accompanies it. In some deployments, especially those used by developers, ease of setup may be of higher concern than security. In these cases, the "Advanced" tab can be used to change settings to relax security and to configure more detailed settings. The following sections outline use cases where an administrator may wish to change the default settings.

OAuth Callbacks

As mentioned in the "Shindig server(s) host name" and 'Use HTTPS for oAuth redirect URLs' sections of this page, one may wish to override the default format of the callback URIs that are generated by the Domino Server with Shindig. Specifically, the scheme may wish to be changed to "http". To do so, one may add values in the "shindig.properties" sub-tab.

For OAuth1.0a use these settings:
Key
Value

For OAuth2 use these settings:
Key
Value

Locked Domains

In some deployments an administrator may wish to disable locked domains, such as in the case of a developer deploying their own server for development and testing purposes. Locked domains should never be disabled in a production environment, especially in the case where third-party gadgets are allowed to render as this puts users as risk of having their SSO tokens and other information stolen by gadgets on the page. The Understanding and configuring locked domains article within the Common Rendering Engine's documentation has some good high-level information about locked domains, including how locked domains help increase security and the implications of disabling them.

In 9.0, if an administrator decides to disable locked domains in a given deployment, they may be so by settings the following in the "shindig.properties" tab.
Key
Value

For disabling Locked Domains in 9.0.1, see the Basics section of this page.

IMPORTANT: When locked domains are disabled, all gadgets will render on the unlocked domain as set by the "Domain name for unlocked gadgets and content fetching" field on the "Basics" tab. To ensure security of SSO tokens, the unlocked domain should be set to a separate second-level domain that is an alias of that server.

What is a SLD (second-level-domain):
A Second level domain is the part of the domain name immediately in front of .com, .org, .edu. For example. foo.com and foobar.com are different second level domains (foo vs foobar). Browser's use second level domains to implement the same domain security policy. A page on domain "foo" cannot access cookies of domain "foobar". This is especially important when security mechanisms, such as LTPA are used that scope cookies to the SLD, such as "foo.com" to enable Single Sign On.

When locked domains are disabled, the "Locked domain suffix" field on the "Basics" tab may be left blank - its value will be ignored.

Gadget iframe Scheme

By default OpenSocial gadgets render in an iframe whose src attribute's url has the same scheme as the parent page. For instance, if the iNotes server redirects to SSL such that the scheme of iNotes is always "https" then gadget iframes will also render over "https". This is a best practice as browsers will warn users when insecure content (i.e. content using http and not https) is loaded in a page that was loaded via https. However, this option is not always practical and administrators have the option to force all gadgets to render over http. This can be done by setting the following value in the "container.js" tab.

Key
Value

Security Tokens

What are security tokens? From the Apache Shindig wiki's Security Tokens page:
"Security tokens are used by shindig to sign requests made by container pages and individual gadgets back to the shindig server. The token is typically a tuple of the container, the authenticated user, the gadget as well as an expiration time. There are two fundamental types of security tokens: secure and insecure. Insecure tokens in Shindig are unencrypted, plaintext strings and should only be used for development and testing. Secure tokens, on the other hand, are encrypted by the Shindig server and are suitable for production use.

The functioning of secure security tokens is similar to SSO systems such as Ltpa. The expiration time acts as a means to prevent request forgery by ensuring that an intercepted token is only valid for a set period of time. "secure" tokens are encrypted server side so that new tokens can only be generated by attackers with knowledge of the security key and algorithm employed by an instance of shindig."

The OpenSocial Component uses secure tokens by default that are encrypted using a key generated as part of the Credential Store configuration. See "Configuring the Credential Store" on the Database creation and configuration page in this cookbook. As mentioned above, security tokens have a set time at which they will expire, based on a configurable time-to-live (TTL) value. By default the TTLs for the OpenSocial component are as follows:

• Container tokens for locally rendering gadgets in the Notes client: 1 hour
• Gadget tokens for locally rendering gadgets in the Notes client: 4 hours
• Container tokens for iNotes and remotely rendering gadgets in the Notes client: 0.5 hours
• Gadget tokens for iNotes and remotely rendering gadgets in the Notes client: 2 hours

Before a security token expires, the token will be refreshed. For iNotes and for remotely rendering gadgets in the Notes client, this requires a network transaction to the Domino Server with Shindig. While these requests will be batched when possible, the default TTLs may incur more refreshing and server load then is desirable. Thus, an administrator may wish to change these values.

IMPORTANT: Security tokens should be treated like single sign-on tokens. They allow gadgets to make OAuth requests to any service that gadget is configured to use. If a gadget security token is compromised, it can be used by a malicious user to act as the gadget for which the token was created. A container security token has the ability to create gadget security tokens and a malicious user can thus use that token to create gadget security tokens and have access to all of the information all configured gadgets have access to. Therefore, container security tokens should be short-lived compared to gadget tokens.

To change the time-to-live of container and gadget security tokens, an administrator can enter the following key-value pairs in the "container.js" tab.

Container security token TTL key
Container security token TTL value

Gadget security token TTL key
Gadget security token TTL value

Domino Server with Shindig Verification

An administrator can verify that the settings in the "Social Edition" tab are taking effect for a given server by checking the logs in the <Domino data directory>/domino/workspace/logs. When the OpenSocial Component OSGi bundles start on Domino, which only happens after the first request is made to them as part of an OpenSocial gadget render in iNotes or a remote render in Notes, the bundles will report any errors reading the configuration. An admin can set the logging level in the "com.ibm.fiesta" namespace to CONFIG in order to see information about what configuration is being read from the configuration settings document for a given server, as well as which configuration settings document a specific server is using. See collecting support data for more information on enabling logging.

< Previous | Cookbook Contents