Widgets created from an OpenSocial gadget

A widget created from an OpenSocial gadget is referred to as an OpenSocial widget. After a client user has added an OpenSocial widget or a Web widget configured for embedded experience to the widget catalog, the Domino® administrator must follow an approval process to review, approve, and make the widget available as an embedded experience to client users. Only OpenSocial widgets and Web widgets that provide client users with embedded experiences must be approved and require some additional configuration.

During the approval process, you configure:
  • Proxy settings - required. Proxy settings are defined on the Configure Proxy dialog box. The Gadget Proxy tab contains the settings for the endpoints an OpenSocial widget can use with Shindig's proxy. The Content Proxy tab contains settings for the data that may be fetched anonymously from OpenSocial widgets. The content proxy settings apply to resources that the gadget requests, such as CSS and JavaScript™, as well as any resources retrieved using the gadgets.io.getProxyUrl() OpenSocial API.
  • OAuth client consumer information (keys and secrets) - required only if a gadget uses OAuth.
  • IP filter(s) - optional
You initiate the approval process for an OpenSocial gadget from a widget document in the widget catalog. When the approval process is complete, you can return to the widget document, and select the Edit Proxy Data action to edit the proxy data, or select Edit in the OAuthData table to edit OAuth data.

Proxy Settings

Proxy settings for each OpenSocial widget are specified in the Configuration Proxy dialog box on both the Gadget Proxy and Content Proxy tabs.
You can specify as many proxies as you need for resources that are accessed by the OpenSocial widget you are approving. The proxy settings function as a whitelist that specifies the appropriate security settings for all such resources, allowing client users to access seamlessly everything needed for full functionality of the widget.
Tip: If you do not know whether the OpenSocial widget you are approving accesses any resources that require proxies, check with the original provider or developer of the gadget that was used to create the OpenSocial widget.
You can provide definitions on the Gadget Proxy tab for:
  • The widget location (automatically added).
    • GET action only, default headers, no additional cookies.
  • The URLs requiring settings for the OAuth Token flows.
    • If OAuth 1.0a is used, Request Token and Access Token URLs with action = GET and Authorization (used together with the default value for the Headers field).
    • If OAuth 2.0 is used, Access Token URL with action = POST, and client_id, client_secret (used together with the default value for the Headers field).
    Note: If the URLs for OAuth 1.0a and OAuth 2.0 are present in the gadget.xml, they are added. You may need to add them if the gadget.xml files do not contain the URLs.
  • URLs accessed using OAuth-enabled requests
    • Actions as needed, authorization, together with default for headers, and other headers and cookies as needed.
  • Other URLs accessed without OAuth
    • Actions, headers, and cookies as needed
You provide definitions on the Content Proxy tab for resources that include static content, such as Javascript files, images, or HTML content.
Note: When you define proxy settings, define the narrowest scope that allows the OpenSocial widget to function to its fullest capability. While you can configure a proxy setting with * as the destination URL, avoid this practice because it may allow the server to be used for unauthorized activities.

On the Notes® client, OpenSocial widgets are rendered from a local gadget server using the proxy settings defined in the widget catalog application that is replicated to the Notes® client. OAuth-enabled widgets are always rendered on a Domino® server running Shindig; never from the gadget server on the Notes® client. The Domino® server uses proxy rules (settings) contained within the credential store. Proxy settings configured using the widget catalog application are pushed by the PushToCredStore agent to the credential store.

At runtime, the URL contained in the request made by a gadget is compared against each of the URLs listed as proxies for the OpenSocial widget. When a match is found, the specified actions, headers, cookies, and MIME type restrictions are applied to the request.

IP Filters

The IP Filters consist of Allow and Deny Filters.

The Deny filters are applied to the address, then the Allow filters are applied. The typical pattern for Allow filters is to deny a wide range of addresses, and then to allow only a specific server. There is no benefit to defining Allow filters without defining a Deny filter.

OAuth configuration

If an OpenSocial widget requests OAuth-enabled services, during the approval process use the Configure OAuth Consumer Information dialog box to specify values appropriate to the type of OAuth service the gadget is requesting. The fields in the dialog box differ according to whether the widget is requesting OAuth 1.0a or OAuth 2.0 authentication flows.

You can complete fields in this document with information received from the OAuth provider. If all of the OAuth information is not immediately available, save the dialog box with the information you have. You can modify the information the information later by selecting the Edit button in the OAuth Data table in the widget document.

The Consumer Key and Secret are stored as encrypted items in the Consumer Key document in the credential store. When editing the widget document, the original values cannot be retrieved for display. If the widget document is saved without entering additional content in those fields, the original values are used. If new content is entered in those fields, the new content is encrypted and stored back in the Consumer Key document.

Self-signed certificates

If an OpenSocial widget (for example, an IBM® Connections widget) uses SSL but also uses self-signed certificates, you must import both the SSL certificate and cross-certificate into your Domino® server running Shindig, or the OpenSocial widget can not render properly. For instructions on importing certificates, see the related topics.