AboutSupport

Domain-based permissions

Suggest Edits

The OpenFin Runtime implements a model for securing sensitive functionality where permissions are based on the domain of the content that requires the secured functionality.
You work with the domainSettings object in the application manifest to define rules that apply to domains based on match patterns.
This object lets you control the following based on the domain of the content:

  • Download of files
  • Use of the fin API
  • Use of secured APIs
  • Access to web content

Starting in v37, the domainSettings object contains a default property, which you can use to define default settings.
You can then override these defaults with domain-specific rules in the rules property of the domainSettings object.
If you do not define a default property, then the same behavior occurs as in versions prior to v37, which varies depending on the feature.

The domainSettings property contains two members:

  • default: Default settings for (v37+) use of secured APIs, access to web content, (v38+) download settings, and access to the fin API.

  • rules: Rules consisting of domain match patterns and definitions of behavior for URLs that match the pattern.

Default properties

The default member of domainSettings can contain the same properties as the rules.options object.
Both domainSettings.default and domainSettings.rules.options are of type PerDomainSettings; their structure is the same.

Thepermissions property controls access to (v37+) secured APIs and (v38+) the fin API.
If it is not defined on the default object, any domain-specific rules apply without a default setting; such domain-specific rules must be applied not only at the application level, but also at the window and view level.
Specifying default permissions avoids the requirement to specify rules at all levels.

If the content property is not defined on the default object, thencontentNavigation and contentRedirect properties apply, at the application, window, or view level.

Domain-based rules

The rules property of the domainSettings object contains an array of rules, each of which consists of a match pattern, a set of options that define behavior for domains that match the pattern, and options for how to perform the match.
(See DomainSettingsRule for details.)

When a domain is matched at runtime, the options for the matched rule are deep-merged with the options for the default member to create a complete set of options for the domain; the options on the matched rule take precedence over the options in the default member.

Match patterns

Any domain is evaluated against the rules in lexical order.
For the first rule where the domain matches the match pattern, the rule is applied to that domain.
Only the first matching rule is applied, even if other rules would match if tested.

Rules

Rules are of type PerDomainSettings.
A rule can contain any of the following properties:

  • api: Can have the following members:

    • fin: none or global: whether the domain is allowed to use the fin API. See Secure third-party content for details.

    • permissions: one or more definitions for secured API access. This object must declare all secured APIs used at any level of the application.

  • content: allow or block: whether the user can access the matching domain. To use this property in a restrictive way, define it as block on the default object, and as allowfor specific domains; in a more permissive approach, do the opposite.

  • downloadSettings: an array of rules, which define files or file types that the user can download, as well as whether the user is prompted for a download location. See Manifest properties for file download for details.

Example of domain-based settings

In the following example:

  • The permissions object defines the secured APIs declared by the application.

  • The domainSettings.default object defines default permissions for content access and secured APIs. These default settings apply to any content loaded by windows or views of the application.

  • The domainSettings.rules object defines a rule for domains that match "*./*.example.com;
    the rule incudes the following settings:

    • Under "api", "fin": "global": Use of the fin API is allowed.

    • Under "api", "permissions" allows the use of the System functions launchExternalProcess and readRegistryValue as well as the Web APIs "notifications", "audio", and "video".

    • "content": "allow" allows access to the domain.

    • "downloadSettings" allows downloads of PNG and JPG files without prompting the user for where to put them.

// in the context of either "platform" or "startup_app"
"permissions": {
  "System": {
    "launchExternalProcess": {
      "enabled": true,
        "assets": {
          "enabled": true
        },
        "downloads": {
          "enabled": true
        },
          "executables": {
            "enabled": true
          }
    },
  }
},
"domainSettings": {
  "default": {
    "content": "block",
    "permissions": {
      "System": {
        "launchExternalProcess": false,
        "terminateExternalProcess": false
      },
      "webAPIs": ["audio", "video", "geolocation"]
    },
  }
  "rules": [
    {
      "match": [
        "*/*.example.com"
      ],
      "options": {
        "api": {
          "fin": "global",
          "permissions": {
              "System": {
                  "launchExternalProcess": true,
                  "readRegistryValue": true
              },
              "webAPIs": ["notifications", "audio", "video"]
        }
        "content": "allow",
        "downloadSettings": {
          "rules": [
            {
              "match": [
                "*://*/*.png", "*://*/*.jpg"
              ],
              "behavior": "no-prompt"
            }
          ]
        }
      }
    }
  ]
}

Updated 24 days ago