Geocortex Identity Server

Geocortex Identity Server uses dedicated security software that is installed with Essentials. To authenticate with Identity Server, users must enter their credentials.

About the Membership and Role Providers

Identity Server is based on membership and role providers that are defined in the following two files:

C:\Program Files (x86)\VertiGIS\Geocortex Identity Server\Web\Configuration\membership.config

C:\Program Files (x86)\VertiGIS\Geocortex Identity Server\Web\Configuration\roleManager.config

Essentials ships with membership and role providers that you can use to perform authentication and authorization. See MSDN's DefaultMembershipProvider Class documentation for more information about the configuration properties of this provider.

Configure an Alternative ASP.NET Membership and Role Provider

Identity Server can use any ASP.NET-compatible membership and role providers that point to an existing database. Depending on the membership provider that you use, you may be able to configure password strength restrictions, the maximum number of sign-in attempts a user can have, lock-out procedures, and so on.

You can also adapt Identity Server to use legacy (Essentials 3.x) XML providers. See Configure Identity Server to Use Legacy XML Providers.

Geocortex Identity Server requires SSL. By default, Identity Server's Require SSL setting in the Post Installer is enabled.

Default Membership and Role Providers

In the default setup, authentication and authorization are performed against the membership and role providers that ship with Essentials. The default setup is appropriate when you do not have an existing database of users, or you want an easy way to create accounts for temporary users and you do not want to add them to your corporate database.

The default Identity Server membership and role providers must be used together. You cannot use the default membership provider with a custom role provider. Likewise, you cannot use the default role provider with a custom membership provider.

Custom Membership and Role Providers

You can configure Geocortex Identity Server to use any ASP.NET-compatible membership and role providers that point to an existing database, such as SQL Server or Active Directory (when Active Directory is not being used with Integrated Windows Authentication). Using Identity Server with an existing database is appropriate when you already have a database of users who will be accessing Essentials.

Geocortex Identity Server can work with security providers like Google, Yahoo, or Facebook. Setting this up is an advanced scenario. Contact Geocortex Support for help.

Geocortex Identity Server Users and Roles

The Geocortex Identity Server security provider allows you to apply permissions to the following types of users and roles:

Geocortex Identity Server - All Users: Permissions that you set for All Users apply to all users who authenticate using credentials that are defined in the membership provider.
Geocortex Identity Server - Role: Permissions that you set for a particular role apply to all the users with that role. The role is defined in the role provider that you are using.
Geocortex Identity Server - User: Permissions that you set for a particular user only apply to that user. The user account is defined in the membership provider that you are using.

Configure the Geocortex Identity Server Security Provider

To configure the Geocortex Identity Server security provider:

Enable the Geocortex Identity Server security provider.

The Identity ServerIdentity Server security provider is disabled by default.
If you want, edit the security provider to change the name to something that is more meaningful to end users.
Configure permissions using the Identity Server users and roles in each site that you want to secure using the Geocortex Identity Server security provider.
If you want to use Geocortex Identity Server with the default membership and role providers, create the users and roles. See Configure Users and Roles for the Default Setup.
If you want to change the membership and role providers that Identity Server uses, you must configure Identity Server to point to the providers. Follow the instructions that apply to you:

Configure Users and Roles for the Default Setup

When you use Geocortex Identity Server with the default membership and role providers, users and roles are created and managed in Manager.

You can create users and roles in any order. If you create the roles first, you can assign roles to users at the same time you create the users. On the other hand, if you create the users first, you can assign users to the roles at the same time that you create the roles. Adding a role to a user is equivalent to adding a user to a role—you only need to define the relationship in one direction. Similarly, removing a user from a role is equivalent to removing a role from a user.

To configure users and roles to use with Geocortex Identity Server's default setup:

In Manager, click the Security & Data tab, expand the Security area in the side panel, and then click Providers.
Click the Users and Roles icon beside the Geocortex Identity Server security provider.

The Users and Roles dialog box opens.

If Identity Server's SSL setting is enabled in the Post Installer and you do not have a valid SSL certificate installed, Essentials will not be able to connect to Identity Server and you will get an error message. SSL is enabled by default. You must correct this before you can add users and roles.
Create users and roles, and add users to roles.
- Add a User: On the Users tab, click New User, and enter the user name and password.
- Add a Role: On the Roles tab, click New Role, and enter the name for the role.
- Add a User to a Role: On the Roles tab, click the Edit icon beside the role, click Add User, and then enter the user name.
- Add a Role to a User: On the Users tab, click the Edit icon beside the user, click Add Role, and then enter the role name.
- Filter Users: Filtering users is useful if the list of users is long. On the Users tab, enter the text that you want to match, and then click Filter. For example, "col" matches "coldenburg" and "jcollins". To return to the full list of users, click Clear.
- Filter Roles: Filtering roles is useful if the list of roles is long. On the Roles tab, enter the string that you want to match and click Filter. For example, "con" matches "Contractors" and "Quality Control". To return to the full list of roles, click Clear.
- Remove a User from a Role: On the Roles tab, click the Edit icon beside the role that you want to remove the user from. Click the Remove User icon beside the user that you want to remove.
- Remove a Role from a User: On the Users tab, click the Edit icon beside the user that you want to remove the role from. Click the Remove Role icon beside the role that you want to remove.
- Delete a User: On the Users tab, click the Delete User icon beside the user that you want to delete.
- Delete a Role: On the Roles tab, click the Delete Role icon beside the role that you want to delete.
When you have finished configuring users and roles, click Close.
Click Apply Details.

Change the Membership and Role Providers

Configure Identity Server to Use SQL Server

This section assumes that you already have a working SQL Server database that you want to use. For information, refer to Creating the Membership Schema in SQL Server (http://www.asp.net/web-forms/tutorials/security/membership/creating-the-membership-schema-in-sql-server-cs).

When you use SQL Server with Geocortex Identity Server, you can create, modify and delete SQL Server users and roles in Manager. Alternatively, you can use the utilities provided by SQL Server to manage users and roles.

To use SQL Server membership and role providers with Identity Server, you must add the providers to the Identity Server configuration files and point Identity Server at the SQL Server providers. Follow the instructions below to configure Identity Server to use SQL Server providers.

To set up Identity Server to work with SQL Server:

There are three files you must modify:

connectionStrings.config
membership.config
roleManager.config

By default, these files are in the following folder:

C:\Program Files (x86)\VertiGIS\Geocortex Identity Server\Web\Configuration

Configure connectionStrings.config

Open connectionStrings.config in a text editor.
In the connectionStrings element, add the following markup as a sub element:
```
  <add name="SqlConnString" connectionString="MY_CONNECTION_STRING">
```
Replace MY_CONNECTION_STRING with the connection string for your SQL Server.
Save connectionStrings.config.
Close the file.

Configure membership.config

Open membership.config in a text editor.
In the membership element, set defaultProvider to SqlMembershipProvider.

The first line of the file should look like this:
```
  <membership defaultProvider="SqlMembershipProvider"> 
```

In the providers element, add the following markup as a sub element:

  <add name="SqlMembershipProvider"
       type="System.Web.Security.SqlMembershipProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
       connectionStringName="SqlConnString"
       enablePasswordRetrieval="false"
       enablePasswordReset="true"
       requiresQuestionAndAnswer="true"
       applicationName="/"
       requiresUniqueEmail="false"
       passwordFormat="Hashed"
       maxInvalidPasswordAttempts="5"
       minRequiredPasswordLength="7"
       minRequiredNonalphanumericCharacters="1"
       passwordAttemptWindow="10"
       passwordStrengthRegularExpression=""/>

Save membership.config.
Close the file.

Configure roleManager.config

Open roleManager.config in a text editor.
In the roleManager element, set defaultProvider to SqlRoleProvider.

The first line of the file should look like this:
```
  <roleManager enabled="true" defaultProvider="SqlRoleProvider"> 
```

In the providers element, add the following markup as a sub element:

  <add name="SqlRoleProvider"
       connectionStringName="SqlConnString"
       applicationName="/"
       type="System.Web.Security.SqlRoleProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"/>

Save roleManager.config.
Close the file.

Configure Identity Server to Use Active Directory

If your organization uses Active Directory to store its domain users, normally you would use Integrated Windows Authentication to secure Essentials. When you secure Essentials using Windows Authentication, Essentials automatically uses your Active Directory users and groups for authentication.

If Windows Authentication will not work for you, you can set up Geocortex Identity Server to connect to Active Directory. This creates an LDAP connection to Active Directory that you can customize to your needs.

This method does not support single sign-on. For single sign-on to work, you must use Integrated Windows Authentication.

This section shows how to set up Geocortex Identity Server to connect to Active Directory. It assumes that you already have a working Active Directory database that you want to use.

To set up Identity Server to work with Active Directory:

There are three files you must modify:

connectionStrings.config
membership.config
roleManager.config

By default, these files are in the following folder:

C:\Program Files (x86)\VertiGIS\Geocortex Identity Server\Web\Configuration

Configure connectionStrings.config

Open connectionStrings.config in a text editor.

In the connectionStrings element, remove  surrounding each of the following sub elements:

  <!--
    <add name="ADConnString" connectionString="LDAP://server.domain.com/cn=Users,dc=domain,dc=com"/>
  -->
  <!--
    <add name="ADRolesConnString" connectionString="LDAP://server.domain.com/cn=Users,dc=domain,dc=com"/>
  -->

In the ADConnString sub element, replace the value of the connectionString attribute with the connection string for your Active Directory membership provider.
In the ADRolesConnString sub element, replace the value of the connectionString attribute with the connection string for your Active Directory role provider.
Save connectionStrings.config.
Close the file.

Configure membership.config

Open membership.config in a text editor.
In the membership element, set defaultProvider to ActiveDirectoryMembershipProvider.

The first line of the file should look like this:
```
  <membership defaultProvider="ActiveDirectoryMembershipProvider"> 
```

In the providers element, remove  surrounding the following sub element:

  <!--		  
  <add name="ActiveDirectory"
       type="System.Web.Security.ActiveDirectoryMembershipProvider"
       connectionStringName="ADConnString"
       connectionUsername="username"
       connectionPassword="********"
       attributeMapUsername="sAMAccountName"
       enableSearchMethods="true" />
  -->

Configure the connectionUsername and connectionPassword, and other attributes as required for your Active Directory.
Save membership.config.
Close the file.

Configure roleManager.config

Open roleManager.config in a text editor.
In the roleManager element, set defaultProvider to ActiveDirectoryRoleProvider.

The first line of the file should look like this:
```
  <roleManager enabled="true" defaultProvider="ActiveDirectoryRoleProvider"> 
```

In the providers element, remove  surrounding the following sub element.

  <!--
  <add name="ActiveDirectoryRoleProvider"
       type="Geocortex.IdentityServer.Integration.Membership.ActiveDirectoryRoleProvider, Geocortex.IdentityServer.Integration"
       activeDirectoryUsersConnectionString="ADConnString"
       activeDirectoryGroupsConnectionString="ADRolesConnString"
       securityGroupsOnly="false"
       groupsToUse="*team;Ad*"/>          
  -->

Replace the default groupsToUse value with a semicolon-delimited list of the Active Directory groups that you want Identity Server to use.

You can use the * wildcard in group names. The * wildcard matches any string.

If you want Identity Server to use all your Active Directory groups, either remove groupsToUse="*team;Ad*", or make it empty (groupsToUse=""), or set it to the * wildcard (groupsToUse="*").
If the application pool identity does not have sufficient permissions to query Active Directory, configure connectionUsername and connectionPassword attributes for the add name="ActiveDirectoryRoleProvider" element.

Usually, you do not have to configure connectionUsername and connectionPassword. Do not configure them unless you have to.
Save roleManager.config.
Close the file.

Configure Identity Server to Use Active Directory Federation Services

Geocortex Identity Server supports Active Directory Federation Services (ADFS). Configuring Identity Server to use ADFS is an advanced scenario. Contact your Geocortex Account Manager to discuss Professional Service options.

Configure Identity Server to Use Legacy XML Providers

This section describes how to configure Identity Server to use the XML-based membership and role providers that were available in Geocortex Essentials 3.x.

You should only use the legacy XML providers if you are upgrading from a 3.x version of Essentials and you have an existing Security Provider XML file that you wish to continue using.

When you use legacy XML providers with Geocortex Identity Server, you can create, modify and delete users and roles in Manager. Legacy users and roles are managed the same way as users and roles in the default Identity Server setup. See Configure Users and Roles for the Default Setup for instructions.

To use legacy XML membership and role providers with Identity Server, you must enable the providers in the Identity Server configuration files. Follow the instructions below to configure Identity Server to use legacy XML providers.

To set up Identity Server to work with the legacy XML providers:

There are three files that you must modify:

App_Data\GlobalSecurityProvider.xml
Configuration\membership.config
Configuration\roleManager.config

By default, these files are in the following folder:

C:\Program Files (x86)\VertiGIS\Geocortex Identity Server\Web

Configure GlobalSecurityProvider.xml

Open GlobalSecurityProvider.xml in a text editor.
Replace the content of GlobalSecurityProvider.xml with the content of your existing Security Provider XML file:
- Global Provider: If you were using the global Geocortex security providers in Essentials 3.x, the default location of the legacy Security Provider XML file is:
  
  C:\Program Files (x86)\Latitude Geographics\Geocortex Application Services\App_Data
- Site-Specific Provider: If you were using site-specific Geocortex security providers in Essentials 3.x, the default location of the legacy Security Provider XML file is:
  
  C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Sites
Save GlobalSecurityProvider.xml.
Close the file.

Configure membership.config

Open membership.config in a text editor.
In the membership element, set defaultProvider to XmlMembershipProvider.

The first line of the file should look like this:
```
  <membership defaultProvider="XmlMembershipProvider"> 
```
Save membership.config.
Close the file.

Configure roleManager.config

Open roleManager.config in a text editor.
In the roleManager element, set defaultProvider to XmlRoleProvider.

The first line of the file should look like this:
```
  <roleManager enabled="true" defaultProvider="XmlRoleProvider"> 
```
Save roleManager.config.
Close the file.

Change Identity Server's URL

There are circumstances when you may need to change Identity Server's URL, for example, to update the host name when you change to a production server.

To change Identity Server's URL:

In Manager, click the Security & Data tab, expand the Security area in the side panel, and then click Providers.
Click the Edit icon beside the security provider that you want to configure.
Type or paste Identity Server's URL in the URL box.
Click OK.
If Manager displays a message that you need to enter Identity Server's secret:
1. In the file system where Identity Server is installed, navigate to Identity Server's setup application.
  
  In the default installation, the setup application is here:
  
  C:\Program Files (x86)\Latitude Geographics\Geocortex Identity Server\Web\bin\Geocortex.IdentityServer.Setup.exe
2. Run the Identity Server setup application as an administrator.
  
  The results display in a Windows command window.
3. Find ServiceSecret and copy the value.
  
  The value of ServiceSecret is Identity Server's secret.
4. Close the command window.

In Manager, paste the secret into the Secret box.
Click OK.

Click Apply Details.

Add an Identity Server Security Provider

Essentials ships with one Geocortex Identity Server security provider already configured. You can add Identity Server security providers in Manager. This is useful if you deleted the security provider and you want to add it back.

To add a Geocortex Identity Server security provider:

In Manager, click the Security & Data tab, expand the Security area in the side panel, and then click Providers.
Click Add Identity Server.
In the Display Name box, type a name for the security provider.

The display name appears in the list of security providers that the end user selects from, if you configure multiple security providers.
In the URL box, type or paste Identity Server's URL.
Get Identity Server's secret:
1. In the file system where Identity Server is installed, navigate to Identity Server's setup application.
  
  In the default installation, the setup application is here:
  
  C:\Program Files (x86)\Latitude Geographics\Geocortex Identity Server\Web\bin\Geocortex.IdentityServer.Setup.exe
2. Run the Identity Server setup application as an administrator.
  
  The results display in a Windows command window.
3. Find ServiceSecret and copy the value.
  
  The value of ServiceSecret is Identity Server's secret.
4. Close the command window.
In Manager, paste the secret into the Secret box.
If you want, enter an issuer seed in the Issuer Seed box.

If you do not enter an issuer seed, Manager will create a seed for you.

Unless you have a specific reason to enter a seed, such as re-accessing a previously configured Identity Server that you deleted, we recommend that you let Manager create the seed.
Click OK.

Find Identity Server's Secret

In Manager, you may need to enter the unique secret for your instance of Geocortex Identity Server, for example, some changes to Identity Server's URL may require the secret. Follow the instructions below to get Identity Server's secret.

To find Identity Server's secret:

In the file system where Identity Server is installed, navigate to Identity Server's setup application.

In the default installation, the setup application is here:

C:\Program Files (x86)\Latitude Geographics\Geocortex Identity Server\Web\bin\Geocortex.IdentityServer.Setup.exe
Run the Identity Server setup application as an administrator.

The results display in a Windows command window.
Find ServiceSecret and copy the value.

The value of ServiceSecret is Identity Server's secret.
Close the command window.