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
applicationSettingsobject - 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:
System.downloadAsset
OF
12+
System.launchExternalProcess
OF
12+
System.readRegistryValue
OF
12+
System.terminateExternalProcess
OF
12+
System.getAllExternalWindows
OF
12+
ExternalWindow.wrap
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.downloadAssetSystem.launchExternalProcessSystem.readRegistryValueSystem.terminateExternalProcessSystem.getAllExternalWindowsExternalWindow.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.jsonDesktop 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 11 days ago