Secure third-party content

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.

In Runtime v35, OpenFin added the fin property to the Api interface to let you configure whether web content in a Window or View can access the OpenFin APIs. In v36 or later versions, the Api interface is renamed to ApiSettings.

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.

ApiSettings interface

(Api interface in versions earlier than v36)

The ApSettings 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 ApiSettings 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 set a default value for your application or platform, and then allow or block access to the fin API for domains based on match patterns.
See Domain-based permissions for details.

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.

📘

Note

The ApiSettings 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 other sensitive areas of functionality, such as access to web content, ability to download files, and use of secured APIs.

You can define a default for whether web content is allowed to use OpenFin APIs, through the domainSettings.default property. (See Domain-based permissions for details.)
You can then define patterns for sets of domains that are allowed (or not allowed) to use OpenFin APIs, in contrast to the default setting.
You can define domain settings, including API controls, on the following objects:

• ApplicationCreationOptions
• ApplicationOptions
• PlatformOptions

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.

📘

Note

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 ApiSettings 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": {
      "default": {
        "api": {
          // The following is the OpenFin default, blocking access
          "fin": "none"
        }
      }
      //disallow `fin` API for certain domains
      "rules": [
        {
          "match": [ //Untrusted domains; already blocked by default
              "*://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 viewing context

In version 37 and later, an approach based on domains is preferred, being more consistent with the way security is defined for Web generally.
However, in versions prior to v37, you must define based on the viewing context, such as a window or a view.

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"
      },
    ...
    }
  },
...
}