Example: Serverless Search Portal with Globus Embeds

This repository is an example of the @globus/template-search-portal

You can create your own portal with similar functionality by following the Creating Your Own Research Search Portal section in the template repository and then referencing the sections below.

Background

Metadata in a Globus Search often includes references to assets hosted on a Globus Connect Server. When the Globus Connect Server (and Collection) is configured to support HTTPS Access these assets can be configured to be embedded in search results (e.g. "preview").

Pre-Requisites

• A Globus Search Index you administer.
• A Globus Collection that hosts data relevant to the documents in your Globus Search Index.
• A Search Portal, created following: Creating Your Own Research Search Portal in our template repository, with Authentication enabled.

Globus Embeds

A Globus Embed is an asset that is rendered to your portal from a configured Globus Connect Server via HTTPS. When rendering these assets, there are performance and security. In both cases, we have made a best effort in embedding assets in a performant and secure way, but be sure to review and understand these considerations before enabling this functionality.

When providing a FieldDefinition to a component (e.g. Result), the referenced property can be processed as an embed by:

• Setting the property to a JSON pointer to the location of the asset (the GCS HTTPS URL and path).
• Setting "type" to "globus.embed"
• Providing the UUID of the collection the asset is hosted on via options¹

example-search-portal-with-embeds/static.json

Lines 31 to 38 in 1a4fae3

	{
	"label": "Sample",
	"property": "entries[0].content.sample",
	"type": "globus.embed",
	"options": {
	"collection": "a6f165fa-aee2-4fe5-95f3-97429c28bf82"
	}
	},

GMetaResult Reference

{
  "@datatype": "GMetaResult",
  "@version": "2019-08-27",
  "subject": "5352507d-1293-4827-8ba9-c2d4a0eb78d1",
  "entries": [
    {
      "content": {
        "path": "/portal/catalog/dataset_atl",
        "name": "Atlanta International Airport Climate Data (ATL)",
        "id": "5352507d-1293-4827-8ba9-c2d4a0eb78d1",
        "region": "south",
        "sample": "https://g-fe1c1.fd635.8443.data.globus.org/portal/catalog/dataset_atl/1951.csv",
        "tags": [
          "airport"
        ],
        "globus": {
          "transfer": {
            "type": "directory",
            "path": "/portal/catalog/dataset_atl",
            "collection": "a6f165fa-aee2-4fe5-95f3-97429c28bf82"
          }
        }
      },
      "entry_id": null,
      "matched_principal_sets": []
    }
  ]
}

Using this configuration, the portal code will introspect the Content-Type returned by the asset and attempt to render the asset for the end user.

In this particular case, because we are referencing a valid CSV, the portal will render the data as a table.

For all other Content-Type values the portal will attempt to render the asset as an <object> tag with the returned Content-Type as the type attribute. By using an HTML standard as the default rendering method, the resource will be rendered to the screen based on the end-user's browser environment.

The type attribute of the rendered tag can be override by providing an explicit mime type in your FieldDefinition.options.

Example with options.mime

  {
    "label": "Sample",
    "property": "entries[0].content.sample",
    "type": "globus.embed",
    "options": {
      "collection": "a6f165fa-aee2-4fe5-95f3-97429c28bf82",
      "mime": "application/pdf"
    }
  }

Renderers

In addition to the default rendering behaviors of a Globus Embed Field, you can opt-in to specific renderer built to process and render referenced assets.

Plotly

The Plotly renderer uses the Plotly JavaScript Open Source Graphing Library to render the referenced asset.

To use this functionality options.renderer should be set to plotly and the sourced asset should be a JSON object that is compatible with Plotly.newPlot single configuration object parameter.

example-search-portal-with-embeds/static.json

Lines 39 to 47 in 1a4fae3

	{
	"label": "Sample : 1951 Scatter Plot using Plotly",
	"value": "https://g-fe1c1.fd635.8443.data.globus.org/portal/plotly/1951_atl_plotly_scatter.json",
	"type": "globus.embed",
	"options": {
	"collection": "a6f165fa-aee2-4fe5-95f3-97429c28bf82",
	"renderer": "plotly"
	}
	}

Performance Considerations

Assets that are referenced using the globus.embed configuration will be requested using HTTPS to the configured Collection. Factors such as, the total size of individual embedded assets and the number of embedded assets rendered on a single page will result in HTTPS requests made to in

Security Considerations

We have put forth a best effort in supporting embedding assets in your search portal in a secure way, but it is important to note that embedding, untrusted, user-provided content can be dangerous for your end-users.

Our default protections are based on best practices related to avoiding Cross Site Scripting (XSS) – please be sure to consider these when enabling embedding and making adjustments to the defaults.

Default Protections

• A default Content Security Policy (CSP) is set using a <meta> tag.
  • You can provide your own value for this tag using data.attributes.contentSecurityPolicy in your static.json, or setting the value to false to remove the <meta> tag.
• The default <object> based embed is rendered as a child of a <iframe> where the sandbox, allow, and additional attributes are used to create as much as an isolated runtime environment as possible.

Optimizaitons

Requesting HTTPS Scope on Sign In

Globus Connect Server requires tokens to include specific scopes when requesting assets over HTTPS. By default, when you use the globus.embed type the underlying component will attempt to parse authorization errors from the request and prompt the user to address them (where possible). This default implementation often means the first render of an asset will be a consent error the user needs to address (pictured below).

One way to avoid this initial error is to prompt for the GCS-required scopes at Sign In if the are known – the below example adds a known scope to the configured client.

{
  "data": {
    "globus": {
      "application": {
        "client_id": "7442cbd9-2766-42b9-9512-9195b12ed167",
        "scopes": [
          // The UUID here would reference the Collection where your assets are served from.
          "https://auth.globus.org/scopes/a6f165fa-aee2-4fe5-95f3-97429c28bf82/https" 
        ]
      }
    }
  }
}

You very likely want to include this optimization when using globus.embed². The only time you might not want to use this configuration is if your embedded assets are being loaded from many (dynamic) collections. In these cases, you might not be able to enumerate the scopes as a configuration option, or degrade user experience by asking for unnecessary consent at Sign In.

Footnotes

1. The options.collection configuration is required in order to ensure the proper authorization token is sent along with the HTTPS request for the asset; At this time, the collection cannot be derived from the asset HTTPS URL alone. ↩

2. This portal does not use this configuration as a way to demonstrate the default behaviors. ↩