ThingWorx Model Definition in Composer > Security > Content Security Policy > Troubleshooting Content Security Policy Errors
Troubleshooting Content Security Policy Errors
Enabling Content Security Policy (CSP) on a ThingWorx server can significantly impact the behavior of mashups and extensions that load content from external sources. The default CSP directives applied in ThingWorx block any content from external sources. As a ThingWorx administrator, you should define a content policy that aligns with the security and functional requirements of your mashups. This topic outlines common use cases that may be affected by the default CSP directives and provides guidance on identifying and resolving CSP errors.
Identifying Affected Widgets, Functions, and Layouts in a Mashup
The following table lists different types of mashup content that may be blocked when CSP is enabled.
Mashup Content
CSP Directive
Resolution
Widgets that embed content using direct links, such as the Web Frame widget. This widget supports embedding content in a mashup by specifying links from external sources using a URL property.
frame-src
Test all web frame widgets and make sure that frame-src directive does not block the URL property value. Add any required URLs to the values for the CSP frame-src directive.
Mashup items, such as widgets, functions, or containers with one or more properties that support loading images from a URL. For example, when the ImageSRC property of an Image widget is set to load an image from a URL. This option is available in the media entity picker in Mashup Builder.
A Media entity picker with the New Image URL button highlighted.
The following items in a mashup contain one or more properties that support loading images from a URL:
• Functions: Confirmation Function.
• Container: Flexbox Container
img-src
Review image URL values for these items and add any URLs to the img-src directive.
Widgets that use State Definition, Style Definition, or Menu Definition entities can link to an image on an external URL.
img-src
Review Media entities used in widget style or state definitions and add any external; URLs to the img-src CSP directive.
Widgets that display data like Grid and Value Display may contain HTML or execute JavaScript code. Loading this type of content in a mashup requires multiple types of CSP directives. For example, when a widget displays HTML that embeds images or references objects.
• Functions: Expression, Validator
All
Review any HTML code that is displayed and make sure any references align with the CSP policy. Update directives that are required to display the HTML data.
Mashups using custom CSS may be affected when external images, fonts, or styles are referenced. By default, using the @import statement to import files that are not placed in /Thingworx/FileRepositories is blocked.
style-src, image-src, font-src
Review the Custom CSS tab of any affected mashups or style themes and update the relevant CSP directives.
Imported extensions, such as custom widgets that contain external references to frames, images, fonts, or styles, or URLs.
All
Review the external references required to load and use the extension, then update the CSP directive values to allow any required references.
Viewing the CSP Directives that are Applied to a Mashup at Runtime
You can view the current CSP directives that are applied to a mashup using the developer tools in your browser.
1. In Composer, open the mashup you want to check, then click View Mashup.
2. In your browser, open the developer tools and reload the page to capture network traffic.
3. On the Network tab, select a service or the index.html file that is loaded from the ThingWorx server.
4. Under Response Headers, inspect the Content-Security-Policy header.
Shows the content of the response headers using the developer tools of the browser.
The applied CSP directives are listed. Each directive is separated by a semi colon.
* 
Changes to the CSP directives on the Content Security Policy Rules tab of the PlatformSystem may take up to a minute to update.
Resolving Errors Messages for CSP Directives in a Mashup
1. In Composer, open the mashup you want to check, then click View Mashup.
2. Open the developer tools of your browser, then view the Console log.
A CSP error message is displayed when mashup content violates a CSP directive. Each message contains the resource value that violates a directive and the name of the CSP directive that prevents the resource from loading.
3. Work with your ThingWorx administrator to update the CSP directives that are defined in the PlatformSubsystem.
For more information about updating CSP directives, see Content Security Policy (CSP) in ThingWorx.
The following image shows a mashup example that fails to load content because of CSP directives:
Each one of the following widgets is configured with the following values:
• Label—Custom CSS that loads a custom font from an external source: https://fonts.google.com/
• Image—The ImageURL property is set to load an image from an external site: wikimedia.org
• Web Frame—The URL property is set to load an external web page: https://www.ptc.com
In addition, the custom CSS rules are also applied to the mashup:
@import url("/Thingworx/FileRepositories/Systemrepository/alerts.css");
@font-face {
font-family: "Open Sans";
src: url('https://fonts.google.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,700;1,300;1,400;1,700&display=swap');
}
At run time, the console log shows the following CSP errors.
Browser console errors for content security content directives.
The following default directives prevent content from loading in this mashup:
• img-src 'self' data:—Prevents loading images from external sources.
• font-src 'self'—Prevents fonts that are imported using a @font-face statement.
• frame-src 'self' tw-ra-client:—Prevents frames from loading web pages that are not hosted on the same domain name as the ThingWorx server.
To fix these errors, you must update the relevant CSP directives that are preventing this content from loading. You can selectively add URLs for trusted sites that are required to load the content. To load the content in this example, you can add following values to each directive:
• img-src: *wikimedia.org—Allows loading images from wikimedia.org and any of its subdomains.
• frame-src: ptc.com — Allows loading frames from ptc.com.
• font-src: https://fonts.google.com — Allows loading fonts from fonts.google.com over HTTPS only.
For more information about CSP directives and their supported values, refer to the following resources:
• Content-Security-Policy (CSP) Header Quick Reference
• Content Security Policy (CSP) on the Mozilla Developer Network
Was this helpful?