Cross-Origin Resource Sharing (CORS)
Enabling Cross-Origin Resource Sharing (CORS) is crucial for making requests from one domain or website to a ThingWorx application deployed on a different server.
 |
CORS is directly related to HTTP because it uses HTTP headers to determine whether a cross-origin request is safe and allowed. For more information, see HTTP Developer Guide.
|
1. Update the web.xml file located in <Apache Tomcat Install>\webapps\Thingworx\WEB-INF\ by placing the following CorsFilterand CorsFilter Mapping as the first parameter just after the </session-config> line:
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>[ALLOWED_ORIGINS]</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>OPTIONS,GET,POST,HEAD,PUT,DELETE</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Authorization,appKey,x-thingworx-session,Content-Type,X-Requested-With,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,Accept</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
<init-param>
<param-name>cors.request.decorate</param-name>
<param-value>true</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>[ALLOWED_ORIGINS]</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>OPTIONS,GET,POST,HEAD,PUT,DELETE</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>Authorization,appKey,x-thingworx-session,Content-Type,X-Requested-With,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,Accept</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
<init-param>
<param-name>cors.request.decorate</param-name>
<param-value>true</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
|
|
Note the following:
• Update thecors.allowed.originsparameter with the desired web address(es).
• Multiple allowed origins can be specified by using a comma delimiter. For example, https://origin1.com, https://origin2.com.
• * can be used exclusively to allow requests from all origins. * can only be used on its own to allow all origins. * cannot be used as part of a URI.
• For environments that utilize Single Sign-on (SSO) with PingFederate, ensure that the PingFederate Runtime Server FQDN is added as an allowed origin.
◦ http://<Ping Federate FQDN>:9301 http://<Ping Federate FQDN>:9031
• Add or remove any custom headers from the cors.allowed.headers parameter as necessary.
• Set cors.support.credentials to true to allow for basic authentication.
|
2. Comment out the block below related to OPTIONS in the web.xml file.
<!-- <security-constraint>
<web-resource-collection>
<web-resource-name>Forbidden</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>OPTIONS</http-method>
</web-resource-collection>
<auth-constraint/>
</security-constraint> -->
<web-resource-collection>
<web-resource-name>Forbidden</web-resource-name>
<url-pattern>/*</url-pattern>
<http-method>OPTIONS</http-method>
</web-resource-collection>
<auth-constraint/>
</security-constraint> -->
3. Save the web.xmlfile.
4. Restart Apache Tomcat.
Additional Details
CORS will need to be re-enabled following any ThingWorx upgrades as the <Tomcat Home>\webapps\Thingworx folder is removed during this process. For more information, see the official Apache Tomcat Configuration Reference for your Tomcat version.
CORS can be tested using an online Javascript editor and executing one of the scripts below.
• Application Key Authentication
<script>
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://[THINGWORX_HOST]:[PORT]/Thingworx/Things", true);
xhr.setRequestHeader("appKey", "<APPLICATION_KEY>");
xhr.setRequestHeader("accept", "application/json");
xhr.send();
</script>
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://[THINGWORX_HOST]:[PORT]/Thingworx/Things", true);
xhr.setRequestHeader("appKey", "<APPLICATION_KEY>");
xhr.setRequestHeader("accept", "application/json");
xhr.send();
</script>
|
|
<APPLCATION_KEY> must be replaced with an active non-expired Application Key from the ThingWorx Platform.
|
• Username and Password Authentication
<script>
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://[THINGWORX_HOST]:[PORT]/Thingworx/Things", true);
xhr.setRequestHeader("Authorization", "Basic <USER_PASSWORD>");
xhr.setRequestHeader("accept", "application/json");
xhr.send();
</script>
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://[THINGWORX_HOST]:[PORT]/Thingworx/Things", true);
xhr.setRequestHeader("Authorization", "Basic <USER_PASSWORD>");
xhr.setRequestHeader("accept", "application/json");
xhr.send();
</script>
|
|
<USER_PASSWORD> must be Base64 encoded with a colon separating the username and password. For example, the username Administrator with the password ptc123 would be entered into a Base64 encoder as Administrator:ptc123, resulting in a value of QWRtaW5pc3RyYXRvcjpwdGMxMjM=. This method is used for testing purposes only, as Base64 can be decoded to obtain the username and password value in plain text.
|
It is recommended that the resource sharing occurs between two secure servers. For example, both have HTTPS enabled. Enabling HTTPS on only one end of the connection could lead to a Mixed Content Error.