OpenFin

API Security

Overview

OpenFin API security allows Desktop Owners and Application Providers to restrict and/or permit what API calls are available for an OpenFin Application. Applications must specify APIs in their manifest that enable or disable features such as an external application launch or clipboard reading. While these features can be beneficial, OpenFin understands that Desktop Owners may need to restrict certain APIs from running on a desktop computer. API Security allows this by giving the Desktop Owner tools to prevent application developers from implementing features that may be deemed sensitive to an organization.

OpenFin Secure API

Application Providers are required to declare usage of specific APIs in their application manifest file and in child window options explicitly in order to leverage them in their application. This assists Desktop Owners to recognize API intent up-front. If an API is not permissible by the organization or needs to be enabled for ease of application functionality, the Desktop Owner may create a Desktop Owner settings file to enable/disable the API. In order for Desktop Owners to successfully enact API security, the application creator must:

  • Include the applicationSettings object
  • Set the APIs specified in the Desktop Owner settings to “True”

Once the Desktop Owner settings file includes an applicationSettings object, the manifest will match either the specified manifest URL, an alias with chrome-URL patterns, or the default setting with the Desktop Owner settings file. This will enact the specified permissions and ensure that the API call is successful. In a future version of OpenFin, certain OpenFin APIs will be off-by-default and require the Desktop Owner Settings to be enabled for use. In OpenFin, the following APIs are secured and require an Application Owner to declare them in their application manifest:

API
Type
Min Version

System.downloadAsset

OF

12+

System.launchExternalProcess

OF

12+

System.readRegistryValue

OF

12+

System.terminateExternalProcess

OF

12+

System.getAllExternalWindows

OF

12+

audio

Web

16+

video

Web

16+

geolocation

Web

16+

notifications

Web

16+

midiSysex

Web

16+

pointerLock

Web

16+

fullscreen

Web

16+

openExternal

Web

16+

Configuring a manifest file

It is required to match permissions object in the application manifest file for the following secured APIs:

  • System.downloadAsset
  • System.launchExternalProcess
  • System.readRegistryValue
  • System.terminateExternalProcess
  • System.getAllExternalWindows
  • ExternalWindow.wrap

This file is formatted similar to the Desktop Owner settings file. To configure the manifest file, set a permissions object for startup_app and list the APIs under the System object. To enable or disable the API, set it to true or false.

{
    "startup_app": {
        "name": "OpenfinPOC",
        "url": "http://localhost:5555/index.html",
        "uuid": "OpenfinPOC",
        "applicationIcon": "http://localhost:5555/favicon.ico",
        "autoShow": true,
        "saveWindowState": true,
        "permissions": {
            "ExternalWindow": {
              	"wrap": true
            },
            "System": {
                "getAllExternalWindows": true,
                "launchExternalProcess": true,
                "readRegistryValue": false,
                "terminateExternalProcess": true
            "webAPIs": ["notifications", "audio", "video"]
                      }
            }
    },
    "runtime": {
        "arguments": "",
        "version": "12.69.43.21"
    },
    "shortcut": {
        "company": "OpenFin",
        "description": "Openfin POC",
        "icon": "http://localhost:5555/favicon.ico",
        "name": "Openfin POC"
    }
}

Configuring Desktop Owner settings

The Desktop Owner must configure all security settings through the Desktop Owner Settings file. To create a Desktop Owner settings file, create a JSON file that includes the APIs you want to restrict or enable. Use the detailed example file below as a guideline for your file. Once this is created, host the file as an asset on the server of your choosing and use the following registry key to specify the DesktopOwnerSettings file:

Key: HKEY_CURRENT_USER\Software\OpenFin\RVM\Settings\DesktopOwnerSettings
Type: String
Value: http://website.com/company/files/Desktop_Owner_Settings.json

Desktop Owner Settings file details

It is expected that a security object exists at the root-level of this file. For example, applicationSettings, is an object. This object is mapped to a string-key to configure the application security settings.

A key can be any number of the following strings:

  • An OpenFin manifest URL (as pictured below)
  • A label
    • with a sub-contained list of “urls” representing a collection of match patterns

The example below shows applicationSettings as the object and manifest1.json as the string-key.

"applicationSettings": {
    "https://manifest1.json": {
}

The string “default” is used when a string is not found in an application’s manifest URI. All APIs are true/false, with the exception of readRegistry and clipboard which support more granular control. To set an API in the Desktop Owner settings file, set a string to true to enable it or false to disable it.

Below is an example of a DesktopOwnerSettings file configured with secured APIs.


{  
   "applicationSettings":{  
      "https://manifest1.json":{  
         "permissions":{  
            "System":{  
               "launchExternalProcess":true
            }
         }
      },
      "http://localhost:8081/app.json":{  
         "permissions":{  
            "System":{  
               "launchExternalProcess":true,
               "readRegistryValue":{  
                  "enabled":true,
                  "registryKeys":[  
                     "HKEY_CURRENT_USER\\Software\\OpenFin\\RVM",
                     "HKEY_CURRENT_USER\\Software\\OpenFin\\Runtime",
                     "HKEY_CURRENT_USER\\Software\\Oracle"
                  ]
               }
            }
         }
      },
      "MyAlias":{  
         "urls":[  
            "https://example.com",
            "*.example.com"
         ],
         "permissions":{  
            "System":{  
               "launchExternalProcess":true,
               "readRegistryValue":{  
                  "enabled":true,
                  "registryKeys":[  
                     "HKEY_CURRENT_USER\\Software\\OpenFin\\RVM",
                     "HKEY_CURRENT_USER\\Software\\OpenFin\\Runtime\\Path",
                     "HKEY_CURRENT_USER\\Software\\Oracle"
                  ]
               }
            }
         }
      },
      "default":{  
         "permissions":{  
            "System":{  
               "launchExternalProcess":false
            }
         }
      }
   },
   "whitelist":{  

   }
}

Updated about a month ago


API Security


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.