Configure single sign-on with Essentials Manager and viewers

Overview:
How to configure Single Sign On (SSO) for Manager and the Geocortex viewer for HTML5

Solution:

Configure the Application Pools

In order to be able to perform Single Sign On (SSO) the web application needs to have access to the Windows users from your Active Directory. In order for that to happen, the Application Pool running both REST and Manager applications need to be running under an account that has sufficient permissions to do so. Follow the steps below to configure these accounts:

1. Open IIS Manager
2. Expand your website (the one that's hosting Essentials) and browse to Geocortex -> Essentials (if you are using a named instance, expand the named instance name as well)
3. Select the REST application and click on "Advanced Settings". Take note of the Application Pool that it's using:

4. Click on "Authentication"

5. Make sure both Windows Authentication and Anonymous Authentication are set to Enabled and all other authentication methods are set to Disabled

6. Repeat the steps for Rest Manager.
7. Change the Application Pool Identity for REST and RestManager applications:

• Go to the Application Pools entry in IIS
• Select the application pool for REST or RestManager, from above.
• Check what identity is set in the Identity column. If it's set to either ApplicationPoolIdentity, Network Service or a domain service account, please skip the rest of this section and go to step 2).
• If the identity is set to a local server user (Essentials or EssentialsAdmin are the default ones), click on Advanced Settings
• On the Advanced Settings window, click on Identity.  Choose the built-in account of ApplicationPoolIdentity. 

8. On the server, Run the Geocortex Essentials Post Installation Configuration utility and when it opens, click on Finish (this process will grant the appropriate file-system permissions to the new identities of the application pools)

Configure the HOSTS for Essentials (only for Geocortex Essentials 4.2 or newer)

1. Run the Essentials Post Installation Configuration
2. Go to Configure Geocortex Essentials REST API section
3. Click on the Hosts... on the top right
4. Add all of the URL's used to access Essentials with the appropriate protocol (HTTP/HTTPS) making sure the top item in the list is the most commonly used, it takes precedence.

Verify that the Essentials URLs are in the browser's "Intranet Zone"

By default, web browsers on the client computer will only perform SSO on what is considered to be an application running on the "Intranet Zone" (safe) only. If the browser considers an application to be on the "Internet Zone" (unsafe) it won't do SSO. This restriction is a security measure to prevent the browser from sending credentials to any web page on the internet that requests them.

Generally, a URL which hostname is just the server name (i.e.: https://mygeocortexserver/Geocortex/Essentials/REST) will be considered to be in the "Intranet Zone", while fully qualified domain names will be on the "Internet Zone" (i.e.: https://mygeocortexserver.mydomain.com/Geocortex/Essentials/REST)

To add your URL to your browser's "Intranet" zone:

1. In the client's computer that will access the viewer  or Manager, open the Internet Options in your Windows Control Panel
2. Select Security > Local Intranet > Sites > Advanced > Add your URL's to the list:

3. Click Close and OK
4. In Internet Options / Security / Local Intranet, click on Custom level on the bottom of the page
5. Scroll to the bottom to the User Authentication section
6. Make sure that Automatic logon only in Intranet Zone is enabled

Sometimes IT and network administrators will block the ability to change these settings by end users, you might need to contact them in order to make the changes

Enable Permissions on your Sites

By default, Essentials Sites do not have any permissions enabled. This means that any user can access the entire Site and they will not need to sign in. To enable automatic sign-in, configure the Site Permissions as follows:

1. Open Essentials Manager, then open the Site that you want SSO-enabled. 
2. Open Permissions, then select Windows Integrated - All Users from the drop-down. 
3. Grant access to the Site for All Users by clicking the grey circle beside "Site" in the permissions list twice. It will go red on the first click (deny), then green on the second click (allow). 
4. Save your changes by clicking Apply Changes > Save Site.

Enable SSO on FireFox

If you are using FireFox, SSO needs to be enabled for specific URLs. In order to configure this capability:

1. Launch Firefox
2. On the address bar type: about:config
3. On the search bar search for network.negotiate-auth.trusted-uris
4. Double-click on the option and add a comma separated list of hostnames for SSO to be configured

Troubleshooting SSO problems

1. Make sure steps 1 to 4 of the previous section are properly configured
2. Make sure that the server running Essentials is a member of the Active Directory domain where your users are stored, or that a domain trust exists that would let the server "see" your users.
3. Make sure that the end users computer is a member of the same domain, and that they are signed on to that computer with a domain account.
4. In some cases, you can get SSO working by changing your App pools to run as the NetworkService account instead of the ApplicationPoolIdentity (Per step 7)
5. If you are accessing the viewer/Manager using an external domain name (i.e. https://www.mymap.com/Geocortex/Essentials/RestManager) try accessing it using only the server name (i.e. https://essentialsserver/Geocortex/Essentials/RestManager). If it works after that there might be a forward proxy that's stripping out the credentials, or a reverse proxy that's not properly forwarding them. Please check with your IT team about these potential issues.
6. If you are accessing the viewer/Manager using just the server name domain name (i.e. https://essentialsserver/Geocortex/Essentials/RestManager) and that doesn't work, try accessing it using "localhost" from a browser running on the server itself (i.e. https://localhost/Geocortex/Essentials/RestManager).  If it works after that there might be a forward proxy that's stripping out the credentials, or a reverse proxy that's not properly forwarding them. Please check with your IT team about these potential issues.
7. If step 6 above doesn't work, try to enable SSO for a single folder in IIS outside the Essentials Application:

• Go to C:\inetpub\wwwroot and create a test folder
• Place a test.txt file with some text in it on that folder
• Make sure you can access the file from a browser running on the server: https://localhost/test/test.txt
• Open the IIS console and browse to the test folder within your website
• Open the Authentication options for that folder and disable Anonymous Authentication and leave only Windows Authentication enabled
• Close the browser, re-open it again and try to access https://localhost/test/test.txt. Verify that the server has identified your user credentials by consulting the IIS access logs.  If you see your username, then SSO is working for that particular folder. If it doesn't, please contact your IT team since the server is not able to authenticate domain users. If SSO works fine in this scenario, please contact VertiGIS Support: vertigisstudio-support@vertigis.com for further help resolving your SSO issues.