Self-host the Browser component

By default, the Browser component code is served to desktops from an OpenFin server, which ensures that users always run the most current stable version.
Starting in version 20.1, you can host the Browser component code within your own secure environment, eliminating dependencies on external CDNs and giving you control over component versions.

The Browser component code for self-hosting is provided in a zipped ASAR (Atom Shell Archive) file.
This file is digitally signed by OpenFin, to ensure that its integrity can be verified.

Note: The self-hosted Browser component runs without other Workspace components.
It is not supported to work with components hosted by OpenFin, and other Workspace components do not currently support self-hosting.

Prerequisites

OpenFin Workspace SDK version 20.1 or greater
A web server for hosting the Browser file

How it works

Your organization downloads the zipped ASAR file for a specific release of Workspace.
You place the file on a server accessible to your users.
You configure the application manifest for Workspace to reference the ASAR file, including the server location and an alias value.
You add a declaration for the secured API serveAsset to the manifest file.
Because this solution uses a secured API (serveAsset), the permission to use the API must be granted by the desktop owner, by the end-user, or by OpenFin.
If your organization controls the systems where the software runs, then it can allow the secured API through desktop-owner-settings.
Otherwise, end-users might be prompted to approve the use of this method, which is often undesirable.
Alternatively, if your organization does not control the desktop systems, you can set up your Workspace platform with a trusted application configuration.
In your code to initialize the Workspace platform, you specify the same alias value as in the application manifest.
When the user launches the Workspace platform, the platform accesses the ASAR file, verifies the file signature, and downloads the assets needed to launch the Browser component.

How to do it

Set up the ASAR file

The zipped ASAR file is named workspace-platform.zip, and is located in the root directory of the web page for the Workspace Platform npm package.
You can download it from there.

Place the zipped ASAR file on a web server that you control, so that the URL of the file is accessible to users in your organization.

Configure the app manifest

Add the Browser ASAR file as an app asset in the manifest file for the Workspace platform.
For details about the appAssets object, refer to Manifest settings.

Add serveAsset to the list of secured APIs used by the application.
Refer to API security for details about secured APIs.

{ 
…
    "appAssets": [{
        "src": "https://INTERNAL_SERVER.com/workspace_platform.zip",
        "alias": "ALIAS",
        "version": "VERSION_OF_THE_WORKSPACE_PLATFORM_PACKAGE",
        "target": "workspace.asar"
    }], 
    "permissions": {
      "System": {
        "serveAsset": true
      },
…
}

src: The host name in the src value is used for cache migration, and must be unique across all appAssets definitions used by a Runtime on the desktop system.
alias: The value defaults to "workspace"; it is recommended to use a custom, unique alias.
version: As a best practice, match the Workspace Platform package version; this is not strictly required, but reduces confusion.
The value must be updated when the version of the workspace-platform package is updated.
target: Required to enable retrieving the correct file from inside the zipped file. The value must be "workspace.asar".

Obtain permission to use the secured API

By default, if nothing else is done, the end-user will be prompted to grant permission to use the secured API, the serveAsset method.
Often, this is an undesirable user experience.
To avoid prompting the end-user, you can do one of the following:

If your organization controls the systems where the Workspace platform runs, you can grant permission in desktop owner settings.
Refer to API security for desktop owners for details.
If your organization does not control the systems, you can request OpenFin to authorize your Workspace platform as a trusted application configuration.
In this case, OpenFin provides you with a signed, encrypted configuration to add to your application manifest.

Initialize the Workspace platform with the hosted file

When you initialize the Workspace platform, include the alias value that is defined in the manifest file.

import * as WorkspacePlatform from '@openfin/workspace-platform';

await WorkspacePlatform.init(
  {
    browser: { // Define Browser configuration here
    },
    workspaceAsar: {
      alias: "ALIAS"
    }, //…
  }
)

Limitations

An instance of the ASAR file can be used for only one Workspace platform provider.
If your environment includes multiple Workspace platform providers, they must each have their own copy of the ASAR file.