Using ADFS as an Identity Provider for Essentials

Overview:
A step-by-step guide for configuring Essentials to use ADFS for user sign-in and permissions.

Installing Geocortex Essentials will also install Geocortex Identity Server, which is used to set permissions on Essentials Sites.  Identity Server supports Federation using the WS-Federation protocol, and can be configured to relay a user to an external Identity Provider to determine user identity.

This article describes how to integrate Identity Server with a Windows ADFS (Active Directory Federated Services) server.

Note: Configuring an external identity provider requires a solid understanding of authorization and encryption concepts.  If assistance is required configuring ADFS in your environment, ensure that you have implementation support time available since third-party security configuration is not included in basic support.

Solution:
In order for ADFS to be used with Essentials:
1.  Geocortex Identity Server must be registered with ADFS
2.  ADFS must be registered with Geocortex Identity Server
3.  Geocortex Essentials must be configured to use the ADFS home realm

Getting Ready

Assumptions:
1.  ADFS is installed and functional.

2.  Essentials 4.0.2 or higher is installed  
3.  You have an administrative login to Geocortex Identity Server.  For Identity Server, an administrative user belongs to the role IdentityServerAdministrators. You can create this user and role using Essentials Manager:

4.  Federation and Home Realm Discovery (HRD) have been enabled in Identity Server

Enabling Federation allows Identity Server to pass you to the external provider to authenticate. Enabling HRD allows you to choose which authentication provider to log in with when you launch the Viewer if you have multiple providers enabled.

Step 1: Register Identity Server with ADFS

Register a Relying Party Trust

Registering Geocortex Identity Server as a Relying Party Trust allows ADFS to both accept requests coming from Identity Server, and allow redirects back to it  

• In AD FS Manager, right-click Relying Party Trusts and select Add Relying Party Trust.  

• Select Enter the data about the relying party manually  

• Click Next, enter a Display Name, and click Next again  
• Select AD FS Profile, and click Next    
• Do not configure a Token Encryption Certificate

• Check the option to Enable support for WS Federation Passive protocol  
• Enter the URL to Identity Server's WS-Federation HRD Endpoint in the Relying party WS-Federation Passive protocol URL field. The WS-Federation HRD Endpoint URL can be found in the Geocortex Identity Server web application:

• Click Next in the Add Relying Party Trust wizard on the ADFS server
• Add another Relying Party Trust Identifier:

• Click Next
• The option on the remaining pages of the wizard (Configure Multi-factor Authentication Now?, Choose Issuance Authorization Rules, Ready to Add Trust) can be left as default.
• Once the Relying Party Trust wizard has finished, the Edit Claim Rules dialog should open automatically. If it does not, right-click the added Relying Party, and select Edit Claim Rules:

Add a rule to Send LDAP Attributes as Claims:

• Display Name => Name (mandatory)
• E-Mail Addresses => E-Mail Address (optional)

Token Groups as SIDs => Group SID (recommended)

• Add a second rule to Send LDAP Attributes as Claims:
  • Token Groups qualified by long domain names => Group (recommended)

• Add a rule to Transform an Incoming Claim:
  • Primary SID => Name ID (mandatory)

Once finished, you will need to note the Token Signing certificate thumbprint

Step 2: Register ADFS with Identity Server

• Navigate to the Geocortex Identity Server web application (on the Geocortex Essentials server) and sign-in as an administrative user
• Click on [administration], navigate to Identity Providers, and create a new one by clicking the New button

• Choose an identifier. This can be an arbitrary value. We recommend something simple such as the host name of the ADFS instance, or just "ADFS".

• Check both the "Enabled" and "Include in Home Realm Discovery" options
• For type, select WS Star
• For WS-Federation Endpoint, use the following value:
  • https://sts.local/adfs/ls/
  • Replace sts.local with the actual host name to your ADFS server.

• For issuer thumbprint, use the Token Signing certificate thumbprint noted in Step 1. Enter it with no spaces, upper case, and no hidden characters (do not copy/paste).
• Click on Create.

Step 3: Register the Home Realm with Essentials

• Open the Security Store for your Essentials instance.
• For Essentials 4.5 and up, the Security store is accessed from the Post installer (click the menu button in the top left part of the title bar, and select "Edit Security Store" )
• For Essentials 4.3 to 4.5, the Security Store is accessed with an editor program.
• For Essentials 4.3 to 4.5, this program is located in C:\Program Files\Latitude Geographics\Geocortex Core\NSRoot\Geocortex\Core\Roles\SecurityStore\2.X.X\Editor\Geocortex.Platform.Roles.SecurityStore.Editor.exe
• For Essentials 4.2 and earlier, locate the Security.xml file in the Sites folder. In a default installation of Geocortex Essentials this will be "C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sites\Security.xml"
• Edit this file, and locate the <HomeRealms /> element.   If there is no <HomeRealms /> element, add one as a child of the ServiceDetails tag for Identity Server:

• Replace the <HomeRealms /> tag with the following markup, substituting [identifier] for the identifier chosen for the ADFS Identity Provider (noted in Step 2) and save the file:

<HomeRealms>
    <HomeRealm DisplayName=”My ADFS Instance” RealmName=”[identifier]”>[identifier]</HomeRealm>
</HomeRealms>

Step 4: Enable the Home Realm

• In Geocortex Essentials Manager, go to the Security tab, then to Providers.

Enable the provider seen with the display name specified in the HomeRealm element in Step 3.

• Go to the Sites tab, and edit the site you would like to secure
• Go to the Permissions page, and select the ADFS - All Users provider in the dropdown menu

Allow access to at least the top most Site element

• Launch the Viewer, and select your ADFS instance on the Sign In page.

Identity Server will either redirect to an ADFS login page where you can enter your credentials, or if Windows Authentication with Single Sign on is enabled on your ADFS instance, you will be logged in automatically.

You should then be redirected back to your Viewer.


Manually Configure Permissions

When we sign in with ADFS, claims are assigned to the user principal.  From Essentials Manager, we may assign permissions on the global claim that is assigned - the one that we get when using ADFS.  To assign permissions to more specific claims, you must edit the Site.xml and modify the <Permissions> tag(s) for the elements you wish to secure.

The easiest way to determine which claims are assigned to a user principal is to sign in to the REST Endpoint (rather than launching a viewer) and the clicking on the user name in the upper-right corner to see the list of claims.

http://servername/Geocortex/Essentials/Rest/security/userInfo

Find a claim that you want to use (domain\group or domain\user) and copy it into a text editor to construct permission block for the Essentials site.

To convert a claim into a Permissions tag, use the attributes for:

• Claim Type
• Value
• Value Type
• Issuer
• OriginalIssuer

Example:

<Deny Type="http://schemas.xmlsoap.org/claims/Group" Value="DOMAIN\GIS_basic" ValueType="http://www.geocortex.com/security/claims/weak-identifier" Issuer="urn:gcx:idp:f2038f9f-deef-4555-ad8d-599fccf0ebd7:ADFS" OriginalIssuer="ADFS" />

Now you can copy your claim into the Essentials site.xml and it can be placed anywhere a normal permission is set (site, service, layer, or workflow). 

For the site permission it will need to be adding to this block:

<Permissions Inherit="True">
    <Allow Type="http://www.geocortex.net/security/claims/category/user" Issuer="urn:gcx:ags:7EF014CA-C8D9-4BD8-814D-DB6B8EC5EE56" />
    <Deny Type="http://www.geocortex.net/security/claims/category/guest" Issuer="urn:gcx:guest" />
</Permissions>

Note: Any claim that denies access will take precedence over any claim that allows it, unless the attribute "AllowBeforeDeny" is set on the Permissions tag.
 

Troubleshooting

If you receive a server error from Identity Server error at any point during testing, edit the Identity Server web.config, located at "C:\inetpub\wwwroot\Geocortex\IdentityServer\Web.config" and locate the section. Turn custom errors off by changing the following element from:

<customErrors mode="RemoteOnly" />

To

<customErrors mode="Off" />

This will cause your browser to display the underlying error message from the server, which will help locate the problem.

• If you get the following error after entering your ADFS credentials: "There was a problem accessing the site. Try to browse the site again", check that the Identifier for the Relying Party Trust configured in ADFS Manager matches the Identity Server Site ID exactly, including case. (See Step 1, Configure Identifiers)
• If you get the following error: 405 - HTTP verb used to access this page is not allowed, ensure the Relying Party Endpoint is set to the HRD URL from Step 1. This will be similar to https://server/Geocortes/IdentityServer/issue/hrd.
• If you get an error similar to: Error ID 5004: Unrecognized namespace: "https://docs.oasis-open.org/ws-sx/ws-trust/200512", check if there is a firewall or reverse proxy in place that is rewriting URLs from HTTP to HTTPS. The value in the error above is used as a unique identifier, not a URL, and so will not match if it has been tampered with.
• If you get an error similar to: [EncryptedTokenDecryptionFailedException: ID4036: The key needed to decrypt the encrypted security token could not be resolved from the following security key identifier, you must disable token encryption for the relying party added in ADFS Manager. Token decryption is not currently supported by Identity Server.
• If you see the Identity Server login prompt instead of the expected result, ensure that the ADFS configuration is correct. We saw this with a customer that had set up two relying parties - with individual entry point and exit point URLs (Identifiers and HRDs). The Identifier must match the Site ID from Essentials, and the HRD must match the one within Identity Server.
• If sign-in is successful, but you cannot access the Site, ensure that the claims issued from ADFS match with the Permissions tag in your Site.xml.  If they do not, ensure that the ADFS is issuing both a name and nameid claim.  If either claim is missing, then the OriginalIssuer may get set to the Site ID for Identity Server.