Skip to main content

Using Auth0 as an Identity Provider for Essentials

Overview:
A step-by-step guide for configuring Essentials to use Auth0 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 the Auth0 platform.

Note: Configuring an external identity provider requires a solid understanding of authorization and encryption concepts.  If assistance is required configuring Auth0 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. The Site ID and Federation Metadata are obtained from Geocortex Identity Server
  2. An Auth0 Client must be created for Identity Server
  3. Geocortex Identity Server must be registered with Auth0
  4. Auth0 must be registered with Geocortex Identity Server
  5. Geocortex Essentials is configured to use the Auth0 home realm
  6. The Auth0 home realm is enabled, and permissions are applied for Sites

Getting Ready
Assumptions:

  1. You have an administrative login to Auth0, and have determined your Auth0 URL.
  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 as follows:
    • Log in to Essentials Manager
    • Go to the Security & Data tab
    • Click the Users and Roles button for the Geocortex Identity Server provider
    • Create a role called IdentityServerAdministrators
    • 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.

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

Auth0-1.png

Step 1: Obtain the Site ID and Federation Metata from Geocortex Identity Server

In the Identity Server administration interface, navigate to the General Configuration page.  Make a note of the Site ID of your Identity Server.  The default value is the internal URL of your Identity Server:

Auth0-2.png

Navigate to the home page for Identity Server.  From the home page, download and Save the WS-Federation Metadata XML document by right-clicking on the View WS-Federation Metadata link and selecting Save As...  Alternatively, you can have Auth0 connect to the metadata endpoint if your Identity Server is accessible on the Internet.  We'll set that up later, in the Connections settings.

Note: we want the plain Federation Metadata, not Federation Metadata RP.  The RP one is for configuring a Relying Party.

Step 2: Create An Auth0 Client for Identity Server

In a new browser tab, launch the Auth0 management dashboard.

Within the Auth0 management interface, create a new Client that we'll use to handle the authentication with Identity Server.  I used ASP.NET (System.Web) as the type of client.  Do not follow the specific ASP.NET instructions; they are for overriding the base applications' authentication behavior and we don't need to do that.

The Name of this client is what will appear in the Auth0 authentication dialog.

Note the ID of your newly created Client.  We'll use the ID to add an Alias so that when Identity Server starts the sign-in process, Auth0 knows what to do.

Configure an Allowed Callback URL for Identity Server, for example:

https://hostname.com/Geocortex/IdentityServer/issue/hrd

Replace https://hostname.com with the address used for your Identity Server.

Now we will need to add an alias for this Client.  This is required because Identity Server will not submit the Client ID when signing in. This step must be done with the advanced API for Auth0.  To use the advanced API, we will need a Management Token.
To create and authorize a Non Interactive Client for the Management API, go to the API Explorer tab of your Auth0 Management API.

Click the button Create & Authorize a Test Client.

Use this page to update the client aliases:

https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id

Note: You may have to expand Clients and Update a Client after navigating to the above page.

Use the Set API Token in the upper-left to set the value just obtained for your API token, then navigate to the Update page for the Client object.  Set the ID to the Auth0 Client ID noted above.

Add an alias for your Client:  { "client_aliases" : ["https://hostname/geocortex/identityserver"] }

The value used for the client alias is the Site ID for Identity server, determined above.

Save your Auth0 settings.

Return to the Client configuration to get the Issuer Thumbprint, under Advanced Settings:
Auth0-3.png

Make a note of the Issuer Thumbprint, we will need it when completing the configuration of Identity Server.

Step 3: Register Geocortex Identity Server with Auth0

Expand Connections, Enterprise, and add a new ADFS connection.

Don't use any special characters (spaces, dashes, etc) in the Connection Name.

Upload the Federation Metadata document you downloaded earlier from Identity Server.

On the Clients tab, enable the client that was created for Identity Server.

Step 4: Register Auth0 with Geocortex Identity Server

Auth0-4.png

  • 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

Auth0-5.png

  • Choose an identifier. This can be an arbitrary value. We recommend something simple such as your Auth0 host name, or just "auth0".

Make a note of the identifier you choose.

  • Check both the Enabled and Include in Home Realm Discovery options
  • For type, select WS Star
  • For WS-Federation Endpoint, use the following value:
  • For issuer thumbprint, use the Token Signing certificate thumbprint noted in Step 2. Enter it with no spaces, upper case, and no hidden characters.
  • Click on Create.

Auth0-6.png
Step 5: Register the Auth0 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, 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.

Auth0-7.png

  • Replace the <HomeRealms /> tag with the following markup, substituting [identifier] for the Auth0 identifier from Step 2, and save the file:
<HomeRealms>
    <HomeRealm DisplayName=”My Auth0 Provider” RealmName=”[identifier]”>[identifier]</HomeRealm>
</HomeRealms>

 

Auth0-8.png
 

Step 6: Enable the Home Realm

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

Auth0-9.png
Enable the new 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 Auth0 - All Users instance in the dropdown menu

Auth0-10.png
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
Auth0-11.png
Identity Server will redirect to an Auth0 login page where you can enter your credentials.  Depending on the Auth0 configuration, you may also be able to create a new login at this stage.
Auth0-12.png
You should then be redirected back to your Viewer, signed in.
Auth0-13.png

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.

Related articles

Comments

0 comments

Article is closed for comments.