Enable AD FS v2 for iShare GIS

Overview

If you want to use Windows Active Directory Federation Services (AD FS) version 2.x Web Single Sign-On (AD FS WebSSO) for authenticating users in iShare GIS then the following configuration needs to be performed on the server hosting iShare's Web application. This is typically done if the iShare web server is external to Active Directory network against which users are to be authenticated.

The iShare GIS URL must have been specified as a trusting party in the AD FS configuration (this will be done by the domain system administrator/team).

The iShare web server must be setup to use HTTPS, certificates should be supplied by the network/web/domain team. If running in an on-premises server, Internet Information Services (IIS) should have been configured by them too.

iShare GIS requires that AD FS has been configured to use Group Membership populate a Role Claim:

• Claim Type: Role.

• Template: Send Group Membership as a Claim

• Claim value: corresponds to Group on iShare GIS Web Service server backing an iShare Role, e.g. “StandardUsers” or “ExpertUsers”

Step-by-step guide

What to do on the server running the iShare Web application for iShare GIS

• Ensure that the Application Pool used by iShare Web is loading its User Profile (IIS Manager > Application Pools > [app pool name] > Advanced Settings > Process Model > Load User Profile = True)
• Set the Default Document for the iShare GIS web application to iShareGIS.aspx (or the name of the page used for iShare GIS)
• Install Windows Identity Foundation

• Run the Windows Identity Foundation Federation Utility, point it at the iShare Web web.config file and the iShare Web application URL and then at the AD FS federating server's federation metadata URL under "Use an existing STS" (this alters the web.config file, so back it up first).

• Add the Certificates snap-in to an Microsoft Management Console (MMC) instance (select Computer Account and Local Computer) and save it somewhere memorable e.g.:
  

• Copy the Root Certification Authority (CA) certificate for the authorizing domain and the certificate to authenticate AD FS request to the server (these will probably have been supplied by a system administrator from the authenticating domain. 

• In the Certificates MMC window, expand Certificates (Local Computer) then Trusted Root Certification Authorities and right-click on Certificates and select All Tasks -> Import... 
  

• Go through the wizard and pick the Root CA certificate file you have been provided with 

• Finish the wizard leaving all other options on the default setting
• In the Certificates MMC window, expand Certificates (Local Computer) then Personal and right-click on Certificates and select All Tasks -> Import... 
• Go through the wizard and pick the server certificate file you have been provided with

• Finish the wizard leaving all other options on the default setting

Obtaining the Root CA Certificate via AD CS web page

Browse to the /certserv URL on the issuing server, e.g.:

https://url.of.certificate.server/certserv

1. Click Download a CA certificate, certificate chain, or CRL 
2. Accept any digital certificate operation dialogs and if there's more than one certificate listed, you should have been told which one to pick
3. Click Download CA certificate and save the resulting certnew.cer to somewhere sensible

Obtaining a Certification via AD CS web page

Once you have imported the Root CA certificate, browse to the /certserv URL on the issuing server, e.g.:

https://url.of.certificate.server/certserv

1. Click Request a certificate, advanced certificate request and then Create and submit a request to this CA. 
2. Accept any prompts to allow the digital certificate operation
3. You should have been told which Certificate Template to select at this point (e.g. "iShare Webapp")
4. Under Identifying Information enter the domain name of the local web application server into the Name field. The other fields in this section can be left blank.
5. Enter something useful into Friendly Name under Additional Options.
6. Click Submit
7. On the following page click Install this certificate

At this point the certificate will have been installed under your user account from which it will need to be exported before continuing with the setup process.

1. If not already running, load the Certificates MMC console
2. If not already present, add the Current User certificates snap-in (File->Add/Remove Snap-in...->Certificates->Add > and then select My user account)
3. Expand Certificates - Current User then Personal and select Certificates
4. Right-click the certificate with Issued To equal to the value of the Name field in step 4 of the certificate download process above
5. Select Export...
6. Go through the wizard: select Yes, export the private key, leave the defaults on Export File Format, enter and confirm a password and then save the file to a sensible local location