Converting Essentials and the HTML5 viewer to run on SSL

Overview:
This article will explain how to convert your viewer to run over SSL.  You may want to do this for a number of reasons:

1) You are looking to provide a more secure experience to your users by offering end to end encryption
2) You may need to enable SSL to meet a corporate security policy
3) You may be looking to use the Geolocation functionality of the viewer, which requires SSL in Chrome or Safari

Solution:
1. Get a valid certificate from a recognized certification authority.

The first step will be to get a valid certificate from a recognized certification authority. Although IIS Manager can create test certificates, these will not work in the same way as a properly recognized and authenticated certificate, and your sites will likely have errors during testing that will not appear when using a valid certificate. For this reason it is recommended to use a properly credentialed certificate even during development if you will eventually require your sites to run over SSL.

2. Install the certificate in IIS and set up the SSL binding.

Once you have a certificate it needs to be installed in IIS, and an SSL binding needs to be created for the website which is running the Essentials software. Please note that if your ArcGIS Server instance is not also running in this website, the website where it is running also needs to have an SSL binding.
 

Open IIS manager, and click on your server name on the left hand side. Double click on 'Server Certificates' in the middle pane to open this configuration panel. Then click on 'Import...' at the top on the right hand pane to import your certificate file. Then double clicking on the certificate you added should present something like this. This is a 'wildcard' certificate, which will be valid for any servers on the listed domain:

After the certificate has been successfully imported, then click the web site where Essentials is running in the left hand pane. Under 'Actions' in the right hand pane click on 'Bindings...' and click on 'Add...' to add a new binding. Choose 'https' for Type, the IP address can usually be left as 'All Unassigned', and Port is by default '443' for SSL communication, although other ports can be used if need be. Host name can usually be left blank, although your IT department may have different requirements. From the SSL certificate drop down choose the certificate that you just installed. It should look something like this:


 

3. Change the Essentials default URL to use SSL
 

1. Open the web.config file for the REST Manager application. In a default installation of Essentials this will be found here: 'C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Manager\web.config'
2. Look for a line in the <appSettings> section at the top of the page that reads something like: <add key="EssentialsUrl" value="http://myserver.com/Geocortex/Essentials/REST/sites" />
3. Change the EssentialsURL entry to match your sites REST endpoint, typically  <add key="EssentialsUrl" value="https://myserver.com/Geocortex/Essentials/REST/sites" />
4. This configuration will now be picked up by your sites and viewers automatically.

4. Change the default viewer launch URL to use SSL

1. Open the REST manager settings file.  In a default installation of Essentials this will be found here:  'C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Manager\App_Data\RestManagerSettings.xml'
2. Change the URL parameter in the ViewerFramework elements to use https.  The lines you are looking for should look something like the following:

<ViewerFramework ProductID="dac7855a-88fc-4e88-afdc-0502804595e9" TemplateID="Html5Viewer_2_7" Url="http://dbriggs-ess15/GVH270/" />

3. You will also need to change the URLs in the templates file to use https from http.  The default location is here: C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\Templates\Templates.xml

<ViewerFramework ProductID="DAC7855A-88FC-4E88-AFDC-0502804595E9" TemplateID="Html5Viewer_2_7" Url="http://dbriggs-ess15/GVH270" PhysicalLocation="C:\inetpub\wwwroot\GVH270" RequiresUpgrade="false" />

5. Change your ArcGIS Server map service connections to use SSL.

If you have previously set up your sites with ArcGIS Server connection strings that use http:// you will need to change them now:

1. Open up each site that you need to change in REST Manager and navigate to the 'Map' configuration screen.
2. Click on the edit button beside each ArcGIS Server map service.
3. Click on the 'Edit Connection Settings' button in the mapservice configuration screen and alter the URL to use https://
4. If you're using an overview map, make sure to change those map services as well.

6. Change the default Geometry Service to one that will respond over SSL.

If you are using the default ESRI Geometry Service in your sites you will now have to create your own, as this service will not respond over SSL:

1. Open ArcGIS Server Manager. Click on 'Services', and then go into the 'Utilities' folder (in the sidebar). 
2. Start the Geometry service
3. If you're having trouble with this step, refer to the ArcGIS server documentation for your version of ArcGIS server.  

Now you can edit your viewers to use the new Geometry Service:

1. Open your site in REST manager, and go to the GIS Services section
2. Click on the Geometry tab
3. Enter the URL to your Geometry service
4. If necessary, configure your credentials
5. Click Apply changes, and then click Save site

7. Run the Post Installer and update the URLs on the "Configure Geocortex Essentials REST API" page by clicking the "Hosts" button.

8.  Run the Post Installer and check the "Require SSL" checkbox on the "Configure Geocortex Identity Server" page.

9. Troubleshooting

• I'm getting an SSL error when I load my viewer!
  • You should be able to see details about why the connection is failing by clicking the warning in your browser's address bar.  You can use the information provided to do further troubleshooting.
• When I load my viewer, SSL looks to be working (there's no SSL errors), but I still get a mixed content warning
  • You can try running Fiddler or your browser's developer tools (F12) to look at the traffic as it's being passed to the server.  Look for any requests that are still using http instead of https. Update your site configuration to use the SSL URL.
• When updating my connection to my map services, I get an error saying 'Connection failed.' I can get to the service in a web browser. What am I missing?
  • ArcGIS 10.6.1+ & ArcGIS Online require the use of TLS 1.2 for HTTPS connections.  You will need to make sure Essentials can connect to those services using TLS 1.2.  See this article for details: Connecting to External Services with TLS 1.2.