Legacy version 6 documentation. View current documentation.Legacy version 6 documentation. View current documentation.
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.
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.
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": {
"trusted": {},
"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": { }
}
}
}
}
Note: Only windows on the same domain as the Service Manager can make changes to Finsemble's configuration. This
prevents cross-domain/untrusted components from making changes to Finsemble's config, spawning trusted components, etc.
You can change the security policy of an application component from its default by modifying its config.
"options" section under the "window" section."securityPolicy".Example:
"components": {
"Welcome Component": {
"window": {
...
"options" : {
"securityPolicy": "untrusted",
}
}
}
}
Using Finsemble Connect, you can create new security policies to allow custom groupings of permissions to be set on application components.
To create a custom security policy:
securityPolicies section, giving it a unique name.Example:
"securityPolicies": {
"trusted": {},
"untrusted": { ... }
"partiallyRestricted" : {
"System": {
"clearCache": false,
"exit": false,
"launchExternalProcess": false
},
"Window": {
"executeJavaScript": false,
"webPreferences": {
"devTools": false
},
// Set chrome permission here
"chromePermissions": {
"geolocation": false
}
}
}
},
In this example, a new security policy named "partiallyRestricted" was created. It essentially mirrors the permissions of the default untrusted security policy, but explicitly disallows opening devTools and the Chromium permission "geolocation." This custom security policy can be reused as appropriate to delegate these permissions to multiple application components.
Individual permissions in a security policy can be changed for an individual application component. Permissions customized at the component level overwrite permissions defined at a higher level. 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:
"options" section and "permissions" under the "window" section."chromePermissions" section.true are allowed while
those set to false are restricted.Example:
"components": {
"Welcome Component": {
"window": {…
"options": {
"permissions": {
"System": {
"clearCache": false,
"exit": true,
"launchExternalProcess": false,
},
"Window": {
"executeJavaScript": false,
"webPreferences": { },
// Set Chrome permission here
"chromePermissions": {
"clipboard": false
}
}
}
}
}
}
}
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
../configs/application/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).+"
}
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. You can read the Config Reference to understand Finsemble's configuration tree.
For a deeper discussion of configuration, check out the Configuration tutorial.