Approving a widget created from an OpenSocial gadget

Approving an OpenSocial widget or Web widget configured for embedded experiences that has been added to the widget catalog consists of reviewing, approving and making the widget available to client users. The widgets that provide client users with embedded experiences in Domino® require some additional configuration.

Before you begin

Approving an OpenSocial widget requires at least one manager with the [Admins] role in the ACL of both the widget catalog and the credential store applications.

There is no XPages user interface in the catalog application for approving and signing widgets. However, after you change the launch options to those in the procedure, you and other administrators can still see the classic user interface and have the Review button available for approving and signing widgets. To do so, open the catalog in the Domino Administrator client without the Notes® client running.

If you must run the Notes client, in Notes 9.0.1 Social Edition, you can open the classic user interface from a new Administration link at the end of the widget view list.
Note: If you are still running Notes 9.0 Social Edition, there is no Administration link, but you can open the classic user interface using a URL such as Notes://ServerName/dbFilename.nsf/Toolbox-MainFrameset?OpenFrameset, where ServerName is the name of your server and dbFilename.nsf is the full path to the widget catalog application relative to the server's data directory.

Procedure

  1. From the Domino® Administrator client, click Files.
  2. Select the widget catalog and click to open the catalog.
  3. Expand the Administration > All Widgets by Approval view.
  4. Look for widgets with an approval status of Needs Review.
  5. Open the widget document, click Review. A new Security section in the widget document is populated. The widget's approval status changes to Approval Needed.
    Note: If a widget does not have security data requiring approval, the Approval Needed does not apply to that widget.
  6. If new security data is displayed, review the information.
    Tip: You can also expand and check the approval history section.
  7. If the widget should be approved, click Approve. The Configure Proxy dialog box opens.
  8. Complete the proxy settings on both the Gadget Proxy and Content Proxy tabs.
    Note: One or more default Gadget Proxy entries will be automatically created for you using information from the widget. To edit the default entries, select one and click the Edit button.
    Table 1. Configure Proxy dialog box settings
    Field Description
    URL (required field) The URL pattern for the proxy. The URL can include an asterisk ( * ) as a wildcard character, but only in its last path component. For example, the URL may contain http://www.example.com/images/*. However, http://www.example.com/*/images is not valid.

    For example, this URL http://www.example.com/foobar/test/* is valid and matches http://www.example.com/foobar/test/test.jsp, or http://www.example.com/foobar/test/someOtherstuff. A proxy URL such as http://www.example.com/foobar/test* is not the same, and is not likely to match any target URLs.

    At runtime, the URL contained in the request made by the gadget is compared against each of the different proxy URLs for the gadget. When a match is found, the Actions, Headers, Cookies, and MIME type restrictions are applied to the request.

    Actions (required field) Select one or more of these actions: GET, POST, PUT, DELETE, HEAD. Any action entered here is permitted for any request matching the URL. By default, no actions are permitted.
    Headers Defines the headers that can to be added to a request made from the gadget server. Headers are values sent by a request to a server indicating how the request should be treated and how the response should be returned. The HTTP specification defines a number of headers as a standard. The token value [default] can now be used instead of specifying the individual headers.

    Applications can add additional headers to the request. A gadget's request can include additional headers to be set. However, if those additional headers are not permitted by the proxy setting, then the headers are not allowed. If a request depends on additional headers, those headers must be defined.

    Use commas to separate individual entries in a list of headers. Follow the Internet specification for header names. Header names may contain a wildcard character (*) to match parts of names. For example, if the header name is MyH*, then both MyHeader and MyHome are permitted.

    If nothing is specified, the default set of headers containing Cache-Control, Pragma, User-Agent, Accept*, Content* is used. If an additional header is required, the header list must contain the desired default headers, as well as the required additional header. For example, to add client_secret to the list of headers, the field would contain Cache-Control, Pragma, User-Agent, Accept*, Content*,client_secret. The token value [default] can be used here to represent the default headers, so adding client_secret can also be done by specifying [default], client_secret. If the wildcard * is specified, all headers are permitted.

    To prevent any headers from being sent, add a single header name to the field, and do not include any default headers. For example, specify No_Headers to prevent all headers from being sent. Note The Set-Cookie header is handled separately using the Cookies field, and should not be specified in the Headers field.
    Cookies Cookies are informational elements that transfer data between client and server. Gadget requests may contain cookie values that they desire to set. The Cookies field defines the set of cookies allowed to be passed through the server.

    Use commas to separate multiple cookie names.

    Specify the full cookie name.

    No wildcard characters are permitted.
    MIME Types Set limitations on the request/response style specified with this field. Use commas to separate multiple values.

    The wildcard character (*) is permitted in the MIME types.

    An empty value, or a value of * permits all MIME types to be used.
  9. (Optional) Under IP filter, specify values in the Allow list and Deny list fields as needed. Represent filter values as IPv4 addresses:
    • Fully qualified domain name, no wildcards.
    • IP address and subnet mask, 9.6.1.0/255.255.0.0, no wildcards are permitted. Both sides of the subnet must be valid ip(v4) addresses.
    • IP address with wildcards for specific address components only, for example, 9.6.*.*, but * by itself is not permitted.
  10. When you have specified all initial proxy settings, click Save in the Configure Proxy dialog box. Click OK.
    Note: You can modify those setting later, if needed.
  11. If the OpenSocial gadget uses OAuth, a version of the Configure OAuth Consumer Information dialog box specific to the gadget's release of OAuth opens. Complete these fields:
    Note: It is strongly recommended that you use secure https URLs in any fields where you enter URLs.
    Table 2. Fields in the Configure OAuth Consumer Information dialog box (1.0A)
    Field Description
    Application Id URL to the OpenSocial widget's XML file. Domino® supplies this value.
    Service Name Domino® supplies this value.
    OAuth Request Token URI Domino® supplies this value if the value is available in the XML file. The value is specific to the OAuth service in use.

    If the field does not contain a value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    OAuth Access Token URI Domino® supplies the value in this field if the value is available in the XML file. The value is specific to the OAuth service in use.

    If the field does not contain a value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    *Consumer Key** Part of the identification information used for authenticating the server with the resource provider. This value is obtained by means of a registration process with the resource provider.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    *Signature Method The signature style used when generating requests to a specific resource provider.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    *Consumer Secret** Part of the identification information used for authenticating the server with the resource provider. This value is obtained by means of a registration process with the resource provider.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    Table 3. Fields in the Configure OAuth Consumer Information dialog box (2.0)
    Field Description
    Application Id URL to the OpenSocial widget's XML file. Domino® supplies this value.
    Service Name Domino® supplies this value.
    AllowModuleOverrides True (default) or False

    Indicates whether or not URLs specified in the widget XML can be used. A value of true allows widget XML URLs to be used. A value of false will use only the URLs supplied from the database document.
    OAuth Authorization URL Domino® supplies this value if the value is available in the XML file. The value is specific to the OAuth service in use.

    If the field does not contain a value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    OAuth Request Token URI Domino® supplies this value if the value is available in the XML file. The value is specific to the OAuth service in use.

    If the field does not contain a value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    OAuth Access Token URI Domino® supplies this value if the value is available in the XML file. The value is specific to the OAuth service in use.

    If the field does not contain a value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    *Consumer Key** Part of the identification information used for authenticating the server with the resource provider. This value is obtained by means of a registration process with the resource provider.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    *Consumer Secret** Part of the identification information used for authenticating the server with the resource provider. This value is obtained by means of a registration process with the resource provider.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    Client Type To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    Grant Type To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    ClientAuthorization Type To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    UseAuthorizationHeader True (default) or False

    UseAuthorizationHeader is set to True by default. The UseAuthorizationHeader setting indicates whether or not to include OAuth2 protocol content items as headers. At least one of the fields UseAuthorizationHeader or UseUrlParameter should be set to true. Including the OAuth2 protocol content items as headers only is more secure than using url parameters, especially when using HTTPS.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    UseUrlParameter False (default) or True
    Indicates whether or not to include OAuth2 protocol content items as URL parameters. At least one of the fields UseAuthorizationHeader or UseUrlParameter should be set to true.
    Note: Including the OAuth2 protocol content items as headers only is more secure than using url parameters, especially when using HTTPS.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.
    SharedTokens False (default) or True

    Indicates whether or not an access token from a resource provider that matches the service name and consumer key can be used for multiple gadgets.

    To determine this value, check with the original provider of the gadget that was used to create the OpenSocial widget.

    If the widget uses multiple OAuth services, you will be prompted with a dialog box for each service.

  12. When you have specified the necessary OAuth settings, click OK in the Configure OAuth Consumer Information dialog box.
    Note: If necessary, you can modify those settings.
  13. The widget document is automatically signed and saved. The approval status in the widget document becomes Approved.
    Note: If you click Cancel in the Proxy or OAuth dialog boxes, the widget document will not change status to Approved.