Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

API security

OpenFin API security enables desktop owners and application providers to determine the API calls that are available for an OpenFin application. Applications must declare in their manifest that they use security-sensitive APIs (secured APIs) for functionality that is outside the security sandbox, such as launching an external application or using fullscreen mode. While these features can be beneficial, OpenFin understands that desktop owners may need to restrict certain APIs from running on a desktop computer, particularly from an unknown or untrusted application. API security enables this by giving the Desktop Owner tools to prevent application developers from implementing features that may be deemed sensitive to an organization.

Note

"API" in this article can refer to individual functions or methods (such as ExternalWindow.wrap()) or to entire Web APIs (such as geolocation).

Historically, desktop owners have been able to block access to such APIs on a per-app basis, if a particular app is not trusted or should not have elevated permissions. However, this arrangement is opt-out: desktop owners must explicitly block particular apps from using particular API functions; all others are allowed.

Starting in v20 of the OpenFin runtime, the enhanced security model prevents apps from accessing secured API functions unless the apps are explicitly granted permission to use them.

Enhanced security model

In order to leverage APIs, application providers must declare the use of specific API functions in their application manifest file, and explicitly declare API functions used in child window options. This assists desktop owners to recognize API intent up-front. If an API function is not permitted by the organization or needs to be enabled for ease of application functionality, the desktop owner may define settings to block or allow use of the API function.

For versions of OpenFin prior to v20, if a desktop owner does not block an application’s use of a secured API, it is permitted. Starting in v20, if the desktop owner (or their delegate) does not explicitly allow a secured API for an application, it is blocked by default.

Development exception

To simplify application development, if the application is running from localhost, API security is the same as in v19 and earlier: Only the app manifest declaration is needed to access the API; no desktop owner setting or other permission is required.

For developers, this exception removes the need to take an extra step to allow APIs to be used. Be sure to test your application on a non-local server, and with both enabling and disabling the secured APIs it uses, to ensure that it behaves correctly under those circumstances.

For desktop owners, if you want to prevent this exception for developers’ desktops, define the following registry key as a DWORD value set to 0 : HKEY_CURRENT_USER\SOFTWARE\OpenFin\RVM\Settings\enableSBDLocalhostTrusted

If this key is not defined or is set to a non-zero value, the exception for localhost is allowed.

Delegating control

A desktop owner has the ultimate control over whether to allow or block a particular API for a particular application. However, there are two ways that a desktop owner might delegate their control.

  • If no desktop owner settings are defined for the application’s use of the API, the OpenFin RVM consults settings maintained by OpenFin for certain partner applications, through a set of global desktop owner settings. This is convenient for customers who have no other need for using desktop owner settings, and simply want to use these applications.
  • If neither the desktop owner nor OpenFin has explicitly set a value for a specific API used by an application, then the end user is prompted to decide whether to allow the application to use the API, once for each application.

The dialog box presented to the user lists the actions represented by the APIs (not the API names themselves), with a link to Review security permissions for detailed information.

  • If the user blocks the use of the APIs, then the application still runs, but it doesn’t have access to the requested APIs and the user will be prompted again on the next launch.
  • If the user allows the use of the APIs, they aren’t prompted again on future launches.
  • If the application is updated and uses new secured APIs that aren't blocked or allowed by the desktop owner or OpenFin, then the user is prompted again, for the new permissions.
Screenshot showing the Review Security Permissions dialog box

Screenshot showing the Review Security Permissions dialog box

Secured APIs

In OpenFin, the following APIs are secured. Therefore, in order for an application to use them, they must be declared in an application’s manifest, and allowed by the desktop owner or their delegate.

API
Type

System.downloadAsset

OpenFin

System.launchExternalProcess

OpenFin

System.readRegistryValue

OpenFin

System.terminateExternalProcess

OpenFin

System.getAllExternalWindows

OpenFin

ExternalWindow.wrap

OpenFin

Application.setFileDownloadLocation

OpenFin

audio

Web

video

Web

geolocation

Web

notifications

Web

midiSysex

Web

pointerLock

Web

fullscreen

Web

openExternal

Web (from Electron)

Declaring APIs in an application manifest file

For complete details on defining an application manifest, refer to Configuring your application.

To declare secured APIs used by the application, list them within a permissions object, categorized by the namespace they belong to (which may be webAPIs), as shown in the following examples. Each API name is a key with a Boolean value, except Web APIs, where listing the API name in an array indicates that it is used.

The location of the permissions object varies, depending on the way the application uses OpenFin APIs.

  • For applications that use the Platform API, you can set permissions inside the following objects:
    • platform: The permissions object declares APIs for the platform only (and not for windows or views). If you specify a providerUrl, then this URL is able to execute the enabled permissions.
    • windowDefaultOptions: The permissions object declares APIs for every window launched.
    • viewDefaultOptions: The permissions object declares APIs for every view launched. Be sure to consider whether you load third-party content into views, which might also use APIs.
  • startup_app: Use this object for applications that do not use the Platform API.
{
    "platform": {
        "uuid": "OpenfinPOC",
        "applicationIcon": "http://localhost:5555/favicon.ico",
        "autoShow": false,
        "permissions": {
            "ExternalWindow": {
              	"wrap": true
            },
            "System": {
                "getAllExternalWindows": true,
                "launchExternalProcess": true,
                "readRegistryValue": false,
                "terminateExternalProcess": true
            },
            "webAPIs": ["notifications", "audio", "video"]
        },
        "defaultWindowOptions": {
            "permissions": {
                "ExternalWindow": {
                    "wrap": true
            		},
                "System": {
                    "getAllExternalWindows": true,
                    "launchExternalProcess": true,
                    "readRegistryValue": false,
                    "terminateExternalProcess": true
                },
                "webAPIs": ["notifications", "audio", "video"]
        		},
        "defaultViewOptions": {
            "permissions": {
                "ExternalWindow": {
                    "wrap": true
                },
                "System": {
                    "getAllExternalWindows": true,
                    "launchExternalProcess": true,
                    "readRegistryValue": false,
                    "terminateExternalProcess": true
                },
                "webAPIs": ["notifications", "audio", "video"]
        		}
    	  }
    }  
}
{
    "startup_app": {
        "name": "OpenfinPOC",
        "url": "http://example.com:5555/index.html",
        "uuid": "OpenfinPOC",
        "applicationIcon": "http://example.com: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": "stable"
    },
    "shortcut": {
        "company": "OpenFin",
        "description": "Openfin POC",
        "icon": "http://example.com:5555/favicon.ico",
        "name": "Openfin POC"
    }
}

Note

Because the desktop owner might block your application from using the secured APIs that you have declared, your code should handle the situation where those APIs are not available, such by using try and catch statements.

Configuring Desktop Owner settings

The primary mechanism for desktop owners to control access to secured APIs is through definitions in a desktop owner settings file. For full information, refer to Desktop owner settings.

Application security settings

To define API security settings for specific applications, there must be an object named applicationSettings at the top level of the JSON file. The members of this object are key strings. A key can be any of the following:

  • A manifest URL
  • An arbitrary label; in this case, its urls member is a list of strings representing a collection of Chrome match patterns for manifest URLs. This enables you to define one set of API security settings for a group of applications that have similar manifest URLs.
  • The string default, which applies to any application whose manifest URL does not match another key.

Within each sub-object of applicationSettings, a permissions object contains the settings for specific APIs, grouped by namespace. Values are Booleans, where true allows the API and false disallows it. If an application declares that it uses an API, and no matching permission definition sets a value for it, then the end-user is prompted to allow or disallow it.

The System.readRegistryValue() method supports more granular control. The enabled member key controls use of the method. In addition, the registryKeys member is an array of registry keys that the application can read when the method is allowed.

For web APIs, similarly to the app manifest, simply listing the name of the API is sufficient to indicate that it is allowed.

Global default permission

In addition to the application-specific settings under applicationSettings, you can set a global default for any application and any API not otherwise specified. This option is defined in the desktopSettings object.

  • secureAPIDefaultPermission: Possible values are ”allow”, ”deny”, or ”prompt”.

Note

Setting this option to "allow" or "deny" ensures that the end-user is never prompted to allow secured APIs.

Example desktop owner settings

Below is an example of a desktop owner settings file configured with secured APIs.


{  
   "desktopSettings": 
      "secureAPIDefaultPermission": "prompt",
   ...
},
{  
   "applicationSettings":{  
      "https://www.examplefinapp.com/manifest1.json":{  
         "permissions":{  
            "System":{  
               "launchExternalProcess":true
            }
         }
      },
      "http://www.examplefinapp.com/AnotherApp.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"
                  ]
               }
            },
            "webAPIs": ["audio", "video"]
         }
      },
      "MyAlias":{  
         "urls":[  
            "https://example.com/*.json",
            "https://*.example.com/*.json"
         ],
         "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
            }
         }
      }
   }
}

Updated 3 days 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.