Configuring Access Rules
It's not uncommon to see content from a website originating from multiple domains. When hosting web applications, the W3C manifest defines a scope member that restricts the URLs the application can navigate to.
Additionally, ManifoldJS extends the manifest's schema with a proprietary member named mjs_access_whitelist that defines an array of access rules. A rule consists of a url attribute whose value identifies the target of the rule and indicates whether URLs matching the rule should be allowed. It applies both to navigation as well as network requests that retrieve content on behalf of the application (for example, when loading scripts, images, and style sheets, or when making XHR requests).
When a request to a non-matching URL is the result of navigation, it will be launched externally (in the browser), while other network requests for content are blocked unless permitted by an access rule.
Note: The behavior in Windows is an exception where the whitelist applies only to navigation; network requests are always allowed.
Neither scope nor mjs_access_whitelist are mandatory members in a W3C manifest. In the absence of a scope member, ManifoldJS creates an access rule that allows access to the path component–as well as its children–of the URL specified in the start_url member of the W3C manifest (or the site's URL, if start_url is also omitted).
The following examples illustrate how ManifoldJS interprets various manifest configurations.
| W3C manifest | Allowed URLs |
|---|---|
| { ... } |
http://xyz.com/abc/* |
* the site URL is http://xyz.com/abc/
| W3C manifest | Allowed URLs |
|---|---|
| { ... "start_url": "http://xyz.com/abc/def/index.html" ... } |
http://xyz.com/abc/def/* |
| W3C manifest | Allowed URLs |
|---|---|
| { ... "start_url": "http://xyz.com/abc/def/index.html" "scope": "/abc" ... } |
http://xyz.com/abc/* |
| W3C manifest | Allowed URLs |
|---|---|
| { ... "start_url": "http://xyz.com/abc/def/index.html" "scope": "/abc" "mjs_access_whitelist": [ { "url": "http://assets.xyz.com/default.js" } { "url": "http://assets.xyz.com/styles.css" } { "url": "http://cdn.com/css/bootstrap.css" } ] ... } |
http://www.xyz.com/abc/* http://assets.xyz.com/default.js http://assets.xyz.com/styles.css http://cdn.com/css/bootstrap.css |
| W3C manifest | Allowed URLs |
|---|---|
| { ... "start_url": "http://xyz.com/abc/def/index.html" "scope": "/abc" "mjs_access_whitelist": [ { "url": "http://assets.xyz.com/scripts/*" } { "url": "http://assets.xyz.com/styles/*" } ] ... } |
http://www.xyz.com/abc/* http://assets.xyz.com/scripts/* http://assets.xyz.com/styles/* |
Under the cover, ManifoldJS uses Apache Cordova to implement hosted application projects for some of the platforms it supports. In Cordova, applications rely on a whitelist to define a security policy that determines which external URLs can be accessed. Any content that hasn’t been included in this list is blocked. To configure the security policy, ManifoldJS maps the manifest's scope and URL access rules to suitable access elements in the Cordova configuration file (config.xml).
Note that, in addition to the access rules described above, a hosted web app may specify a Content Security Policy (CSP) that imposes additional restrictions on the network requests that it allows.
An incorrect configuration of the whitelist may result in symptoms ranging from navigation failures, rendering problems such as missing images, to unexpected behavior caused by the inability to load script files.
Configuring the access rules for a hosted web app is not always easy. Determining which URLs need to be whitelisted requires some familiarity with the app’s implementation. In its absence, you may need to analyze the requests that the app makes during its lifetime to extract this knowledge.
There are a number of techniques that you can use to capture this information, and they vary among target platforms. The following articles provide some guidance and suggest how you might diagnose whitelist-related issues on various platforms.