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.

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

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.

Note: Security policies are only available if you use Finsemble's default container, Electron. This level of granular permissions is not available through our alternate container, OpenFin.

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",
            }
        }
    }
}

Customized 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": {
                "webPreferences": {
                    "preload": true
                }
            }

    }
}

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. 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.
  • 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": {…
            "permissions": {
                "System": {
                    "clearCache": false,
                    "exit": true,
                    "launchExternalProcess": false,
                    "readRegistryValue": false
                },
                "Window": {
                    "executeJavaScript": false,
                    "webPreferences": {,
                        "preload": true
                    }
                }
            }
        }
    }
}

Trusted preloads

A preload is a JavaScript file that is inserted into 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 name and extension only

Example:

"finsemble": {
    ...
    "trustedPreloads": ["examplePreload1.js", "examplePreload2.js"]
}

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.