AboutSupport

Secure third-party content

Suggest Edits

As a platform provider, you might want to give end-users the ability to browse web-based content, while not allowing that content to access OpenFin APIs when running inside your platform.
Further, you might want to give access to OpenFin APIs to known, trusted applications, but not to other applications.

Starting in Runtime v35, OpenFin provides a way to configure whether a window or view provides access to OpenFin APIs, via access to the fin entry point.
You can use the Api interface to configure whether web content can access the OpenFin APIs.

You can define rules based on domain match patterns to control whether third-party content has access to OpenFin APIs.
These rules can be defined at the application or platform level.
You can use this feature to allow OpenFin API access to certain domains but not others.

Api interface

The Api interface has an optional property, fin, which controls injection of the OpenFin APIs in the current context. It can take one of two values:

  • "none": The fin API is not available.
  • "global": The entire fin API is available.

You can define a property based on the Api interface as part of the options for Application objects, View objects, and Window objects.
This wide range of contexts provides considerable flexibility in where the use of the OpenFin APIs can be restricted or allowed.

You can also update these options programmatically, in a context that already has access to the fin API.
Be aware, therefore, that an application, window, or view that was created without access to the fin API might be granted access at a later time.

📘

The Api interface also contains an optional iframe property, which is relevant only for contexts with child iframe elements.

Domain settings rules

One way that you, as a platform provider, can control access to OpenFin APIs is by using domain-based rules.
These are the same type of rules that can control the ability to download files, another sensitive area of functionality.

You can define patterns for sets of domains that are allowed to use OpenFin APIs or sets that are not allowed to use them.
You can define domain settings, including API controls, on the following objects:

You can define multiple match pattern rules, but when the Runtime looks up patterns to match a domain, it applies only the first one that matches (in lexical order); any other patterns that also match are ignored.

📘

In Runtime v34 and earlier, the DomainSettings interface was called DefaultDomainSettings, and corresponding properties that used it were called defaultDomainSettings.

Examples

The following examples illustrate the use of the Api interface, with or without domain-based restrictions.

Prevent fin API injection in application manifest

// set "fin": 'none' to prevent API injection, but preload scripts are still injected
"startup_app": {
   "name": "EXAMPLE APP",
   "url": "http://localhost:5555/EXAMPLE_APP.html",
   "uuid": "EXAMPLE_APP",
   "autoShow": true,
   "contextMenu": true,
   "preloadScripts": [
     {"url": "http://localhost:5555/js/PRELOADSCRIPT.js"}
   ],
   "api": {
     "fin": "none"
   },
   ...
}

Allow fin for trusted domains in application manifest

In the following example, untrusted domains are blocked from using the fin API, but a trusted domain is allowed to use it.

"platform" : {
  ...
  {
    "domainSettings": {
    //disallow `fin` API for certain domains
      "rules": [
        {
          "match": [ //Untrusted domains
              "*://EXAMPLE_DOMAIN.com/*",
              "*://FILES_DOMAIN.com/*",
              "*://VIDEO_DOMAIN.com/*"
          ],
          "options": {
              "api": {
                "fin": "none"
              }
          }
        },
        {
          "match": [ //Trusted domains
            "*://TRUSTED_APPLICATION_DOMAIN.com/*"
          ],
          "options": {
            "api": {
              "fin": "global"
            }
          }
        },
        ...
      ]
    }
  }
}

API controls based on views

In the following example, views are blocked from using the fin API, except for one view defined in a snapshot, where the fin API is allowed.

{
  "platform": {
    "name": "PLATFORM",
    "uuid": "PLATFORM_UUID",
    "autoShow": true,
    "providerUrl": "http://localhost:5555/PLATFORM_PROVIDER.html",
    "defaultWindowOptions": {
        ...
    },
    "defaultViewOptions": { //Prevent `fin` use in views by default
      "name": "VIEW_NAME",
      "api": {
        "fin": "none"
      },
...
    }
  }
},
"snapshot": {
  "windows": [
    {
      "name": "EXAMPLE_WINDOW",
      "layout": {
        "content": [
          {
            "type": "row",
            "content": [
              {
                "type": "component",
                "componentName": "view",
                "componentState": {
                  //This domain is trusted to access the `fin` API
                  "url": "http://TRUSTED_DOMAIN.com",
                  "api": {
                    "fin": "global"
                  }
                }        
              },
              { //This view does not have access to the `fin` API
                "type": "component",
                "componentName": "view",
                "componentState": {
                  "url":"http://UNTRUSTED_DOMAIN.com"
                }        
              }
            ]
          }
        ]
      }
    }
  ]
},
...

For simplicity, the example shows the snapshot as part of the application manifest, but the snapshot could also be loaded programmatically, leading to a situation where a view that allows use of the fin API is added to a platform that by default does not allow it.

Superseding FDC3-related options

In the following example, the fdc3InteropApi property sets the version level for the FDC3 API implementation to use. However, setting {"api" {"fin" : "none"}} has the effect of blocking access to the OpenFIn implementation of the FDC3 API, making the value of fdc3InteropApi irrelevant.

{
  "platform": {
    "name": "PLATFORM_NAME",
    "uuid": "PLATFORM_UUI",
    "autoShow": true,
    "providerUrl": "http://localhost:5555/PLATFORM_PROVIDER.html",
    "defaultWindowOptions": {
      "fdc3InteropApi": "2.0",
      "api": {
        "fin": "none"
      }
    },
    "defaultViewOptions": {
      "name": "intent-view",
      "fdc3InteropApi": "2.0",
      "api": {
        "fin": "none"
      },
    ...
    }
  },
...
}

Updated 2 months ago