Use Cross-Origin Resource Sharing (CORS) with the HTML5 Viewer

Overview:
This article is intended for people who want to use, or are already using, CORS with Geocortex Essentials and the Geocortex Viewer for HTML5. This article assumes a knowledge of CORS and how it works.  This applies to Geocortex Viewer for HTML5 v 2.4 and newer, and any older version that has had Geocortex Viewer for HTML5 Security Update 2015-03-26 applied.

Solution:

The Security Update is available on the Geocortex Support Center's Downloads page. Click the Geocortex Viewer for HTML5 link in the Geocortex Essentials section.

Audience: This article is intended for people who want to use, or are already using, CORS with Geocortex Essentials and the Geocortex Viewer for HTML5. This article assumes a knowledge of CORS and how it works.

Related Article: CORS Security Update Overview

Problem

You want to host the Geocortex Viewer for HTML5 on a different domain than Essentials. By default, the HTML5 Viewer will not load configuration from a different domain and Essentials will not allow cross-domain requests.

Solution

Configure Essentials and HTML5 viewers to share resources across domains using CORS.

Step 1

1. If you are using a version of the HTML5 Viewer that is older than 2.4 and you have not yet applied Security Update 2015-03-26, apply it now.

   Follow the instructions in the Instructions.txt file that is included with the Update.

   Alternatively, upgrade your viewers to version 2.4.

Step 2

Configure CORS in Essentials. To do this, you specify the CORS headers that Essentials will attach to responses. The following headers and values are sufficient for most installations:

• Access-Control-Allow-Origin: Origin where the HTML5 Viewer is hosted

• Access-Control-Allow-Methods: POST, GET, OPTIONS

• Access-Control-Allow-Headers: X-Requested-With

The headers are configured in the Essentials REST application's Web.config file. You can either edit the Web.config file directly (instructions below), or you can use IIS Manager's HTTP Response Headers option to add the headers.

1. Run an XML editor or text editor as an administrator.

2. Open the REST application's Web.config file in the editor.

   By default, the Web.config file is located here:

      C:\inetpub\wwwroot\Geocortex\Essentials\REST\Web.config

3. Configure the headers in the system.webServer element's httpProtocol element.

   For example, if the HTML5 Viewer is hosted at http://myviewers.mydomain.com:
    

   <system.webServer>
         ...
         <httpProtocol>
            <customHeaders>
               <add name="Access-Control-Allow-Origin" value="http://myviewers.mydomain.com" />
               <add name="Access-Control-Allow-Methods" value="POST,GET,OPTIONS" />
               <add name="Access-Control-Allow-Headers" value="X-Requested-With" />
            </customHeaders>
         </httpProtocol>
         ...
   </system.webServer>

4. Save the file.

Step 3

Enable your HTML5 viewers to send load requests that load configuration files from a different domain.

1. Run an HTML editor or text editor as an administrator.

2. Open one of the viewer's host files in the editor.

   The default host pages for HTML5 viewers are Index.html (for online use) and Offline.aspx (for offline use). By default, the host files are located here:

      C:\inetpub\wwwroot\Html5Viewer

3. Find where the viewerConfig variable is defined:

      var viewerConfig = {...

4. Immediately before the section where the viewerConfig variable is defined, configure the Essentials origin to be a trusted origin.

   Use the geocortex._configDomains object to configure trusted origins.

   For example, if Essentials is hosted at http://myserver.mydomain.com:
    

   geocortex._configDomains = {
         "http://myserver.mydomain.com": true
      };

5. Save the file.

6. Repeat these steps for each host file and each HTML5 viewer that will load configuration across domains.