Security Policies

If your Finsemble application allows content from outside of your organization, attention must be given to security. To this end, Finsemble provides for a series of permissions and security policies.

Permissions are configs that allow for a granular control over what operations a component can perform. For example, you can prevent an application from being able to clear a user's cache using "clearCache": false.

When a restricted operation is attempted, an AccessDenied error will be returned and the operation will not occur.

You can set permissions at an individual component's config level or at the security policy level. Examples of each are provided below.

Because Finsemble's "container" is powered by Chromium, developers should take care to restrict Chrome's permissions as appropriate. By default, all of Chrome's permissions are true. You can view the full list of Chrome's permissions here.

Security policies are a logical grouping of permissions. Applications or services can be given "trusted," "untrusted," or customized security policies.

Note: Child windows inherit the permissions and security policy of their parent. Child windows default to the most restrictive permissions. For example, if a permission is set to true for the child but false for the parent window's security policy, the child window won't be able to perform that operation.

Trusted security policies

The trusted policy allows access to every API endpoint. Use this security policy for application components created by your organization whose behaviors you understand thoroughly.

By default, all same-domain components are set to trusted.

Untrusted security policies

The untrusted security policy sets certain permissions to false. By default, all cross-domain components are considered untrusted.

Application components with this security policy will not be able to perform the following operations:

{
	"securityPolicies": {
		"untrusted": {
			"System": {
				"clearCache": false, // This restricts the component from clearing the cache
				"exit": false, // This restricts the component from closing Finsemble
				"launchExternalProcess": false // This restricts the component from launching an external application
			},
			"Window": {
				"executeJavaScript": false, // This restricts the component from running JavaScript
				"webPreferences": {
					"preload": false // This restricts the component from loading untrusted preloads (see below)
				}
			}
		}
	}
}

Changing a security policy

You can change the security policy of an application component from its default by modifying its config.

  • Navigate to finsemble-seed/configs/application/components.json.
  • Search for the specific application component config.
  • Add an "options" section under the "window" section.
  • Set the name of the "securityPolicy".

Example:

"components": {
	"Welcome Component": {
		"window": {
			...
			"options" : {
				"securityPolicy": "untrusted",
			}
		}
	}
}

Customizing security policies

You can create new security policies to allow custom groupings of permissions to be set on application components.

To create a security policy:

  • Navigate to finsemble-seed/configs/application/securityPolicies.json.
  • Add a new security policy under the securityPolicies section, giving it a unique name.

Example:

"securityPolicies": {
	"preloadsAllowed": {
		...
	},
	"partiallyRestricted" : {
		"System": {
				"clearCache": false,
				"launchExternalProcess": true
			},
		"Window": {
			"executeJavaScript": false,
			"webPreferences": {
				"preload": false
			},
			// Set chrome permission here
			"chromePermissions": {
				"geolocation": false
			}
		}
	}
},

In this example, a new security policy named "preloadsAllowed" was created. It essentially mirrors the permissions of the default untrusted security policy, but explicitly allows preloads and disallows the Chromium permission "geolocation." This custom security policy can be reused as appropriate to delegate these permissions to multiple application components.


Customizing permissions at the component level

Individual permissions in a security policy can be changed for an individual application component. This will allow you to have more control over how users use your components.

To change a permission for an application component edit its config file.

To change an application component's permissions:

  • Navigate to finsemble-seed/configs/application/components.json
  • Search for the specific application component config.
  • Add an "options" section and "permissions" under the "window" section.
  • Restricting Chrome's permissions is done by adding a "chromePermissions" section.
  • Amend the specific permission you would like to change from its default. Permissions set to true are allowed while those set to false are restricted.

Example:

"components": {
	"Welcome Component": {
		"window": {…
			"options": {
				"permissions": {
						"System": {
							"clearCache": false,
							"exit": true,
							"launchExternalProcess": false,
							"readRegistryValue": false
						},
						"Window": {
							"executeJavaScript": false,
							"webPreferences": {,
								"preload": true
						// Set Chrome permission here
						"chromePermissions": {
							"clipboard": false
						}
					}
				}
			}
		}
	}
}

Trusted preloads

A preload is a JavaScript file that is inserted into a window and runs before any other content. By default, trusted security policies can load preload files whereas untrusted ones cannot.

However, if you wish to always allow specific preloads that you control, you can elect to do so by creating a set of trusted preloads. Trusted preloads are always allowed for all components.

To create a trusted preload:

  • Navigate to finsemble-seed/configs/openfin/manifest-local.json
  • Add "trustedPreloads" under the finsemble
  • Trusted preloads are defined as an array
  • List each preload with it's full path

Note: You must use Finsemble's local host address as part of its full path. Trusted preloads are on the top level of the manifest, and thus passed into the container prior to the Config Service's parsing of macros. Full, absolute URLs are necessary for trusted preloads.

Example:

"finsemble": {
	...
	"trustedPreloads": ["http://localhost:3375/preloads/examplePreload1.js", "http://localhost:3375/preloads/examplePreload2.js"]
}

Restricting URLs

By default, Finsemble will load content from any URL you specify (e.g., via JSON files or ad hoc components). You can restrict where components can navigate to or what URLs can be loaded.

To activate this restriction, add a feaURLWhitelist property to "finsemble" section in /finsemble-seed/configs/openfin/manifest-local.json. Set the value of this config to a regex pattern to explicitly allow the URLs you want your smart desktop to be able to access. Any URL not specified by this config will be restricted.

Note: This setting is applied through the entire Finsemble smart desktop.

The following example restricts any URL that does not start with http(s) localhost, yahoo or www.yahoo:

"finsemble": {
	"feaURLWhitelist": "^https?:\/\/(localhost|(www\\.)?yahoo).+"
}

check   Same-domain components receive the trusted security policy, and thus have access to the underlying APIs. Cross-domain components receive the untrusted security policy, and receive a set of restricted permissions.
 

Further reading

You can read the Config Reference to understand Finsemble's configuration tree.

For a deeper discussion of configuration, check out the Configuration tutorial.