Using ADFS as an Identity Provider for Essentials – VertiGIS

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.

Note: See this article for instructions on how to ensure the ADFS service is running

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:

i. Log in to Essentials Manager
ii. Go to the Security tab
iii. Click the Users and Roles button for the Geocortex Identity Server provider
iv. Create a role called IdentityServerAdministrators
v. Create a new user and add them to the IdentityServerAdministrators role

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

Note: This step is done by the Essentials installer at 4.1 and higher so is only required if using (or upgrading from) Essentials 4.0.x.

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.

i. Log in to the Identity Server web application (http://server/Geocortex/IdentityServer) as a user belonging to the IdentityServerAdministrators role. (See step 3 above).
ii. Click on the [administration] link
iii. Go to Protocols > WS-Federation
iv. Check the boxes to Enable Federation and Enable Home Realm Discovery

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

Note: Identity Server currently does not support token decryption. Configuring an encryption certificate will result in errors during the authentication process.

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:

i. Navigate to the Identity Server web application (http://server/Geocortex/IdentityServer).
ii. Click on Application Integration, and locate the WS Federation HRD endpoint

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

Note: This value will be used to uniquely identify the instance of Geocortex Identity Server that is being integrated with ADFS. The identifier must match the Site ID of Identity Server exactly.

i. Navigate to the Identity Server web application (http://server/Geocortex/IdentityServer)
ii. Sign in as a user belonging to the IdentityServerAdministrators role
iii. Click on the [administration] link
iv. Under General Configuration, locate the Site ID

v. Use this value for the Relying Party Trust Identifier in ADFS Manager

Note: There will likely be an existing Identifier for the WS-Federation HRD Endpoint. This, and any other identifiers can be removed.

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)

Note: Other rules are not necessary, but can be added at the clients' discretion.

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

NOTE: Copying/pasting the value can result in the insertion of an invisible character which will cause problems with this value. We recommend manually transcribing this value to ensure that no problems occur due to invisible characters (http://support.microsoft.com/kb/2023835)

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".

Note this value (the identifier) for Step 3

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.

Note: This URL lists numerous ADFS Endpoints, one of which is the WS-Federation Endpoint. Identity Server will be able to get the correct values from this base URL

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>

Note: some ADFS providers may set the OriginalIssuer value to the Site ID of the Identity Server. When this happens, sign-in will be successful but the user will not have any permissions to the site. We have observed this behavior when the name claim is missing from the claims issued by ADFS. To work around this issue, you can either reconfigure the claims issued by ADFS to include at least one name claim, or set the home realm using the Site ID:

For example:

<HomeRealm DisplayName=”ADFS Instance” RealmName=”ADFS">https://server/geocortex/identityserver</HomeRealm>

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.

Note: All security providers that you have enabled on the Security tab will be displayed on this menu

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" />

<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.