Integrate iShare GIS with ADFS
Document history
Date | Feb 26, 2020 |
|---|---|
Author | Dan Ormsby |
Comments | This document supersedes the following documents:
|
Contents
- 1 Contents
- 2 Introduction
- 3 How iShare GIS authenticates against ADFS
- 4 Overview of integration process
- 5 Stage 1 - Pre-requisites (Customer and Astun)
- 6 Stage 2 - Configure ADFS so that iShare GIS is a Trusted Endpoint (Customer)
- 7 Stage 3 - Set up the ADFS Claims (Customer)
- 8 Stage 4 - Set up roles on iShare GIS server (Astun)
- 9 Stage 5 - Configure iShare GIS web application to use ADFS authentication
- 10 Stage 6 - Testing by Astun
- 11 Stage 7 - Testing by Customer
- 12 Appendix A - Frequently Asked Questions
- 13 Appendix B - Obtaining Root Certificates from ADCS
Introduction
This document provides details of how iShare GIS integrates with Active Directory Federated Services (ADFS). This integration allows customers using iShare GIS in the Cloud to authenticate their users against an on-premise Active Directory Service, and to provide single sign-on integration for iShare GIS users. The subsequent use of iShare GIS is then tailored according to the user permissions determined by that user's role.
How iShare GIS authenticates against ADFS
The diagram below shows the principle of how a user accessing iShare GIS is authenticated once the ADFS and iShare integration has been completed.
In the above diagram, "Service" would refer to iShare GIS. Therefore:
The user visits the iShare GIS website to request access.
iShare GIS returns a token to the users web browser.
The users web browser sends the token to ADFS.
ADFS makes an authentication request against the AD server.
The AD server confirms that the user is authenticated.
A token is issued by ADFS back to the user's web browser, which includes information that iShare GIS needs to understand about the user - for example what groups it is a member of.
The user's web browser sends the token back to iShare GIS with details of the user's group membership.
Access is granted. The specific details of the user's group membership determines the user's permissions in iShare GIS.
Overview of integration process
Integrating iShare GIS with ADFS requires 7 separate stages. It is important that they are all completed carefully as ADFS integration can be a challenge to troubleshoot!
Stage | Stage name | Description | Responsibility |
|---|---|---|---|
STAGE 1 | Pre-requisites | Before iShare GIS and ADFS are ready to be integrated with each other, the basic installation and configuration of both applications should be complete, and the networking infrastructure configured such that they are visible to one another. We would not recommend leaving any of these tasks in Stage 1 to be done in parallel with any of the tasks after Stage 1. Stage 1 is therefore to confirm that:
| Astun Customer |
STAGE 2 | Configure ADFS so that iShare GIS is a Trusted Endpoint | This is the process the customer needs to go through to configure ADFS to confirm that the iShare GIS application is ‘trustworthy’. This process involves notifying ADFS of the URL where iShare GIS is hosted and running a tool to generate a metadata document (FederationMetadata.XML) which is subsequently used for configuration on the iShare server. | Customer |
STAGE 3 | Set up ADFS Claims | The ‘claim’ in ADFS terminology, is the information that is sent to iShare GIS when the user is authenticated. The ‘claim’ therefore needs to be configured in ADFS to include the appropriate attributes that iShare needs, namely the user’s name and the user’s roles. The process of setting up the claims typically maps the user groups as they are defined in Active Directory with group roles on the iShare server. In this document we run through two examples for a typical iShare set up. Additional claims may need to be configured according to how AD groups are organised within your environment. | Customer |
STAGE 4 | Set up Roles on iShare GIS server | This step involves setting up the appropriate roles and Windows User Groups on the iShare GIS server. These roles will map on to the ADFS claims that were set up in Stage 3, so that for each Outbound Role specified in ADFS, there is an equivalent role in iShare. | Astun |
STAGE 5 | Configure iShare GIS to use ADFS authentication | This is the task undertaken on the iShare GIS server by the Astun consultant. In this stage, we are changing the authentication model so that authentication is made via the ADFS service and single sign-on, rather than by using local windows credentials with explicit user names and passwords. To do this the consultant will Run the Federation Utility which will acccess the FederationMetadata.XML document produced by the customer in Stage 3. | Astun |
STAGE 6 | Astun Testing | Astun logs on to the customers Studio ETL server, to test the ADFS integration using the Astun user account within the customer AD domain. | Astun |
STAGE 7 | Customer testing | Customer to test ADFS integration with variety of roles. This may be undertaken as part of UAT. | Customer |
Stage 1 - Pre-requisites (Customer and Astun)
Recap
Before iShare GIS and ADFS are ready to be integrated with each other, the basic installation and configuration of both applications should be complete and the networking infrastructure configured such that they are visible to one another. We would not recommend leaving any of these tasks in Stage 1 to be done in parallel with any of the tasks after Stage 1. Stage 1 is therefore to confirm that:
iShare GIS has been set up and configured and is ready for integration
ADFS has been set up and configured and is ready for integration
Application pre-requisites | |
|---|---|
iShare in the Cloud | iShare GIS has been installed in the cloud Map Sources have been built iShare GIS is accessible to the customer network, either via VPN, or by IP white listing iShare GIS is running under https, i.e. A web browser on the Studio ETL server is able to access iShare GIS server via https Astun have been set up with a test account within the customer's AD domain |
Active Directory Federation Services | ADFS (version 2 or 3) has been installed ADFS has been integrated with Active Directory ADFS has been configured so that it is visible to iShare End Users ADFS has been configured so that the iShare GIS server can access the FederationMetadata.XML URL |
Please note, it the above pre-requisites have not been met, then you should not proceed to the next stages.
Stage 2 - Configure ADFS so that iShare GIS is a Trusted Endpoint (Customer)
Recap
Stage 2 is the process the customer needs to go through to configure ADFS to confirm that the iShare GIS application is ‘trustworthy’.
The output of this process is the generation of an XML document called FederationMetadata.XML the URL of which should be supplied to the Astun consultant. Embedded within this is the Token Signing Certificate.
If the customer also requires the tokens to be encrypted then a Token Encryption Certificate will also need to be supplied.
2.1 ADFS Relying Party Trust
See: https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust for details of how to setup a Relying Party Trust in the current version on ADFS on Windows 2016, which is how iShare GIS will operate in an ADFS environment. The method will be similar but not identical in Windows 2012 and Windows 2008.
While configuring ADFS itself is outside of the scope of iShare documentation or consultancy, the following are what we understand are the necessary steps to enable iShare GIS to be a Relying Party Trust:
Enter data about the replying party manually
Specify a display name e.g. "Astun iShare GIS".
If an option, choose "ADFS profile" & not "ADFS 1.0 / 1.1 profile".
If specifying an optional Token Encryption Certificate the private key will need to be passed to Astun.
Enable support for the WS-Federation Passive protocol. SAML 2.0 WebSSO protocol can be ignored.
Add the iShare GIS application URL as the Replying party trust identifier (see 2.2).
Permit everyone to access this relying party (but do not configure multi-factor authentication settings).
Once the trust has been configured, pass the Federation Metadata document URL - or file, if the iShare GIS server cannot access your ADFS service or ADFS proxy directly - to the consultant setting up iShare GIS (see 2.4).
2.2 Relying Party Identifier
The Relying Party Identifier in ADFS for iShare GIS is just the web application's path, e.g.: https://gis.domain.name/. Unless the iShare web application is always going to be served via the same IP address, this should be configured after the server has been given a permanent DNS name that clients will use.
Note: The iShareGIS URL must end with a forward slash in both the 'Endpoints' tab and the 'Identifiers' tab. If it does not, then login attempts will fail with a 405 error: "HTTP verb used to access this page is not allowed".
2.3 Recommended Token Lifetime
By default ADFS will expire users' ADFS sessions after an hour. This will cause issues in iShareGIS as it intercepts responses to the browser to try and redirect the application to the ADFS service. While the issue can then be resolved by refreshing the page in the browser, we recommend increasing this value to eight hours, which should cover a day's worth of activity. Unfortunately this setting is not currently configurable through the ADFS administrative applications, but has to be set through Powershell on the server that runs the ADFS service, e.g.:
Set-ADFSRelyingPartyTrust -Targetname "https://server.domain.name/ishare.web/" -TokenLifetime 480See: https://docs.microsoft.com/en-us/powershell/module/adfs/set-adfsrelyingpartytrust?view=win10-ps
2.4 Supply FederationMetadata.XML URL or file and certificates to Astun
Finally
In either case the Token Signing Certificate thumbprint is contained within the FederationMetadata.xml document)
Then:
If option for token encryption was selected you should also:
Stage 3 - Set up the ADFS Claims (Customer)
Recap
The ‘claim’ in ADFS terminology, is the information that is sent to iShare GIS when the user is authenticated. The ‘claim’ therefore needs to be configured in ADFS to include the appropriate attributes that iShare needs, namely the user’s name and the user’s role. The process of setting up the claims also maps the user groups as they are defined in Active Directory with group roles on the iShare server (the latter being set up in Stage 4). In this document we run through two examples for a typical iShare set up. Additional claims may be need to be configured according to how AD groups are organised within your environment.
Naming convention
Note: The inclusion of an ampersand (&) in any group names, whether or not they are being used in iShare, will cause an error in iShare as the ampersand will be taken as a parameter separator, so these groups should be renamed or excluded by using custom rules to filter the groups. Use option 3.2 below if any group names in your directory contain an ampersand (&).
Option 3.1 Example claim rules ("issuance transform rules") for iShare GIS
The example described in the table below are the steps that would be required to set up an ADFS / iShare GIS integration in which:
User’s names would be passed from ADFS to iShare (e.g. for use in annotation)
User’s roles would be passed from ADFS to iShare (e.g. for permissions)
An AD group called “GIS Users”, would map on to an iShare role called “iShareUsers”
An AD group called “GIS Editors”, would map on to an iShare role called “iShareEditors”
An AD group called “GIS Administrators”, would map on to an iShare role called “iShareAdmin”
The iShare roles would then be used to define the specific permissions within the iShare environment of members of each of those roles.
The following are simply examples and you may have different Group Names so "PLEASE ASK YOUR CONSULTANT FOR THE ACTUAL NAMES OF THE GROUPS".
Step | Instructions | Complete |
|---|---|---|
Step 1 - Set up AD groups | For example, you could set up AD groups called:
Then assign your team members to those AD groups. Note The above example is a typical set up which would allow us to test the iShare GIS / ADFS integration. If you already have existing AD groups that are similar to GIS Users / GIS Editors / GIS Administrators, but are named differently, then these can be mapped accordingly. The groups above are referenced throughout this document, so remember to substitute these with your existing AD group names if going down this route as per step 8. More information on this is contained below this table. | |
Step 2 - Add Astun test user to the above groups | You should have already set up an Astun user on your domain for testing purposes. Please add the Astun user to the above groups so that we can test the integration whilst we complete our steps. | |
Step 3 - Pass through Name claims | Follow the guidance document at: Set up as follows:
| |
Step 4 - Pass through Role claims | Follow the guidance document at: Set up as follows:
| |
Step 5 - Send GIS Users Group as iShareUsers Role | Follow the guidance document at: Set up as follows
| |
Step 6 - Send GIS Editors Group as iShareEditors Role | Follow the guidance document at: Set up as follows:
| |
Step 7 - Send GIS Administrators Group as iShareAdmin Role | Follow the guidance document at: Set up as follows
| |
Step 8 - Other roles |
|
End result
At the end of this process ADFS will be configured to map the following AD groups to the following Windows Groups on the iShare GIS server.
AD group | Windows Group |
|---|---|
GIS users | iShareUsers |
GIS editors | iShareEditors |
GIS administrators | iShareAdmin |
NOTE: The above example is a typical set up which would allow us to test the iShare GIS / ADFS integration. If you already have existing AD groups that are similar to GIS Users / GIS Editors / GIS Administrators, but are named differently, then these can be mapped accordingly. If so you need to:
Fill out a table as above, with details of the AD group and iShare roles, and share with the Astun consultant
Add the Astun test user into the groups (as per Step 2)
Adapt Steps 5, 6 and 7, with appropriate changes to the User's group and Outgoing claim value
Additional groups can also be defined in a similar way - e.g. if you wish to organise roles around business areas / departments (e.g. “Planning”, “Social Services”, “Education” etc.).
Option 3.2 Example custom claim rules ("issuance transform rules") for iShare GIS
The example described in the table below are the steps that would be required to set up an ADFS / iShare GIS integration in which:
User’s names would be passed from ADFS to iShare (e.g. for use in annotation)
User’s roles would be passed from ADFS to iShare (e.g. for permissions)
Only AD group prefixed with a common prefix are mapped to iShare roles.
AD groups and roles will have the same name.
The iShare roles would then be used to define the specific permissions within the iShare environment of members of each of those roles. The advantage of this custom claim rule setup is that there is no further ADFS configuration to occur in the event of additional AD groups to be passed to iShare. Any AD group with a matching prefix will be included as a role.
Step | Instructions | Complete |
|---|---|---|
Step 1 - Set up AD groups | Set up AD groups called:
Assign your team members to those AD groups. | |
Step 2 - Add Astun test user to the above groups | You should already have set up an Astun user on your domain for testing purposes. Please add the Astun user to the above groups so that we can test the integration whilst we complete our steps. | |
Step 3 - Pass through Name claims | Follow the guidance document at: Set up as follows:
| |
Step 4 - Create Custom Rule to get all groups | Set up as follows:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/role"), query = ";tokenGroups;{0}", param = c.Value); | |
Step 5 - Create Custom Rule to filter groups | Set up as follows:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/role", Value =~ "(?i)^iShareGIS_.*"] => issue(claim = c); |
End result
At the end of this process ADFS will be configured to map the following AD groups to the following Windows Groups on the iShare GIS server.
AD group | Windows Group |
|---|---|
iShareGIS_Users | iShareGIS_Users |
iShareGIS_Editors | iShareGIS_Editors |