AboutSupport
Docs

Runtime version control

Suggest Edits

A key strength of the OpenFin ecosystem is that you can use automatic updating to ensure that your application is always running on the latest versions of the OpenFin Runtime.
However, some organizations want to control what versions of Runtime are running in their enterprise environment, as well as the timing of when those versions are upgraded.
Historically, they have implemented solutions such as self-hosting OpenFin assets or turning off auto-updating.
This can lead to situations where the organization is using outdated versions or missing out on security updates.

Starting in RVM v11, desktop owners can define control over versions of the OpenFin Runtime, using a desktop owner setting to control what versions are automatically updated on the system.

There can be multiple versions of the Runtime installed on a system, where different versions are used by different applications.
You can use Runtime version controls to determine which versions are allowed to run.

📘

Note

An RVM instance enforces Runtime version control only on Runtime instances that it starts. Runtime instances that are launched externally or those that are already running when an RVM instance starts are not affected.

Why control the Runtime version?

Here are a few use cases for controlling the versions of Runtime in an organization:

  • You want to ensure that external applications deployed on desktops are not using older Runtime versions. For example, you want to ensure that Runtime instances in your environment have security updates or specific major features.

  • You want to ensure that applications do not use newer versions of the Runtime that you have not vetted in your environment.

How do you control the Runtime version?

Starting in RVM 11, there are several properties related to Runtime versions, grouped under a new settings object, runtimeControls.

Version-related properties

You can specify allowed Runtime versions using the desktopSettings.deployment.runtimeControls property in desktop owner settings. Within the runtimeControls object, you can set the following options to control versions:

  • allowedVersionsList: An array of strings that specify allowed versions.

  • blockedVersionsList: An array of strings that specify blocked versions.

  • minimumAllowedVersion: A string specifying the lowest version that can be run.

  • maximumAllowedVersion: A string specifying the highest version that can be run.

The values for these settings use the same pattern rules as RVM versions, as described forRVM versions.

The RVM accepts the union of the values of allowedVersionsList, minimumAllowedVersion, and maximumAllowedVersion, excluding any versions that match values in blockedVersionsList.
Therefore, for example, a value in allowedVersionsList that is lower than the value of minimumAllowedVersion is still accepted; a value in the allowed versions list that is higher than the value of maximumAllowedVersion is also accepted.

📘

Note

Take care to maintain values for allowedVersionsList and maximumAllowedVersion to ensure that they do not become outdated.

If none of the settings is defined, all versions are allowed.

Version strings allow * as a wildcard, which matches any value at the corresponding level of the version hierarchy.
However, specific numbers cannot follow a wildcard. For example, "52.2.*.1" is an invalid version pattern.

Enforcement of restrictions

In addition to allowing or blocking versions, you can use the enforce setting.

  • "enforce" : "warn" — Default: The RVM merely warns about disallowed versions in the RVM log.
  • "enforce" : "strict" — The RVM produces an error and blocks the Runtime from running.

Responsibility

If runtimeControls is configured, you must also configure the top-level contactInfo.email property.
If an email address is not specified, the Runtime version controls are not enforced.

Example

The following example shows how the property appears within a DOS file:


{
"contactInfo": {
  "email": "[email protected]"
},
…
 "desktopSettings": { 
…
   "deployment": {
…
   "runtimeControls": {
      "enforce": "warn",
      "allowedVersionsList": ["31.0.*.*","32.0.0.*"],
      "blockedVersionsList": ["30.*.*.*", "28.106.72.17"],
      "minimumAllowedVersion": "27.*.*.*",
      "maximumAllowedVersion": "29.*.*.*"
      },
…
  },
…
}

}

How does it work?

The following principles and constraints guide the operation of Runtime version controls:

  • Runtime version controls are checked only when the RVM is involved in starting an application, such as from a shortcut (for command-line invocation), a fins custom protocol link, or programmatically from a manifest.

  • Runtime version controls are evaluated after reading an application manifest, before any Runtime version is downloaded or launched.

  • If the Runtime version specified in the application manifest is allowed by controls in desktop owner settings, the RVM proceeds to start the application normally, including downloading a Runtime version if necessary to meet the application's requirement.

  • If the Runtime version specified in the application manifest is not allowed by the desktop owner controls, the RVM produces an error or warning saying that the specific Runtime version is blocked by desktop owner settings. The type of message depends on the value of the enforce property.

  • In cases where a manifest specifies one or more fallback manifests, and the original manifest specifies a preferred Runtime version (runtime.version) that is not allowed or not available, the RVM proceeds to evaluate the fallback manifests to find the first one whose preferred version is allowed and available.

  • If an application is launched programmatically, and its requested Runtime version does not meet the DOS criteria, the RVM returns a failure response to the calling application, along with an error message containing the configured version pattern. The failure also appears in the RVM log. Possible ways to launch an application programmatically include the following:

The log message for a programmatic application launch that fails due to Runtime version controls looks similar to the following (which is wrapped for readability):

23-05-25 14:14:19.087 | 22432:22336 | INFO | VERBOSE | Incoming 
application-topic message from: 0x00030B8A; messageId: \n3a27d053-42c5-440d-b4c4-fc2646c7708c; payload: {"action":
"launch-apps","data":{"configUrlArray":["file://C:\\Users\\Z\\
Desktop\\OpenFin\\json\\manifest\\mWhitelist.json",
"https://workspace.openfin.co/release/system-apps/notification-center/app.json"
"https://cdn.openfin.co/workspace/9.2.5/studio/app.json",
"rvmLaunchOptions":{}},"processId":22208,"runtimeVersion":
"30.110.74.16","securityRealm":"","sourceUrl":
"file:///C:/Users/Desktop/OpenFin/json/manifest/myapp.json","timeToLive":60}

  • In cases where the RVM is not involved in reading the manifest and launching the application, Runtime version controls are not enforced. Such cases can include the following:

  • The RVM writes to the RVM log in the following cases:

    • This setting blocks an update of the Runtime version.

    • The value of the setting is logged whenever an application launches.

Updated 11 months ago