Page Comparison

This guide is for IT Administrators to setup ADFS for integration with Lucidity Software Products

A Quick Overview of what you get from ADFS

To help understand what benefits are achieved by setting up ADFS, the following summary has been prepared so you can see the difference between an ADFS authenticated system and normal authentication.

Normal Authentication

1. User opens login screen and enters Username and Password.  There is a password reset option.

1. Image Added
    

2. Lucidity authenticates against the Username and Password that has been stored within Lucidity Access.   If this authentication fails the user is unable to log in.

ADFS Authentication

1. User is presented with a login screen for ADFS that allows them to proceed with an ADFS login ('login' button) or switch to non-domain login if they are accessing the system from outside the company network. 
   

1. Image Added

2. Option 1 - User clicks 'Login' button.

   1. Scenario A - User is logged onto the network domain.

      1. Lucidity obtains the current username 'from the browser' that the user used to authenticate against the network domain.

      2. If that username has a corresponding entry in Lucidity Access with appropriate permissions to allow entry into the application, then entry is allowed.

      3. If the username that was used to log onto the network domain does not have a corresponding entry in Lucidity Access, then entry is not allowed.

   2. Scenario B - User is NOT logged onto the network domain, but still wishes to use domain credentials.

      1. An ADFS login dialog is presented, asking for domain login credentials.
         

1. 1. 1. Image Added

      2. User enters Username and Password which are authenticated against the domain.

      3. If the Username and Password match a domain account AND there is an account in Lucidity Access with the same Username and appropriate permissions, entry is allowed.

   2. In the instance where entry is not possible using ADFS, the user can still revert to non-domain credentials (see Option 2).
       

2. Option 2 - User clicks 'Login with non-domain credentials' button.

   1. User is presented with a login screen which requires entry of a Username and Password.  User enters these details.
      

1. 1. Image Added

   2. Lucidity authenticates against the Username and Password that has been created within Lucidity Access.   If this authentication fails the user is unable to log in.

   3. Note that the username and password must be those recorded in Lucidity Access, as this is a non-domain login.

   4. User has the option of reverting the to ADFS login if they separately log onto the network and return to the browser to re-attempt authentication.

ADFS Setup

Term	Description
IdP	Identity Provider, acts as identifying party in federation requests
SP	Service Provider, acts as consumer of relayed information in federation requests
Relying Party	Microsoft's terminology for SP
idp-instance-url	Web-accessible path to ADFS IdP instance. Must be accessible via HTTPS

Instructions for setup of ADFS can be found in the following video and instructions. You can skip some of this if ADFS is already setup.

1. Install AD CS (IdP)

Active Directory Certificate Service is required to sign requests made by IIS when authenticating ADFS.
Following instructions in the below video, install ADCS, and create a Certificate Authority for the machine. This will be used to issue certificates later in the process.

Follow instructions between 0:50 to 5:40

2. Create a certificate used to sign requests (IdP)

Following instructions from 5:40, create a domain name. Enter the idp-instance-url (

e.g. adfs.yourdomain.com) into the 'Common name' and 'Friendly name' field. The certificate must be issued against the URL that will be used to perform the authentication requests.

3. Install AD DS (IdP)

Using the Server Roles, install AD DS. Create a test user that will be used later on to test authentication. Ensure the User has username, password, email address and name specified.

4. Install ADFS (IdP)

Following instructions from 12:00, install ADFS. Install via the AdfsSetup.exe (as shown in the video) which is available for download from http://www.microsoft.com/en-us/download/details.aspx?id=10909. Installing ADFS via the Server Roles screen causes issues where federation metadata not being installed correctly. 

Follow the configuration guide in the video, ensuring to that the idp-instance-url matches the friendly name.

5. Send URL 

Send the url that will be used to authenticate requests to your contact at Lucidity Software. Once setup is complete at our end we will send you a url to be used in the next step

6. Add Relying Party (IdP)

On the ADFS machine, go to the url provided in the previous step in Internet Explorer (url will look like https://simplesamlphp-url/simplesaml/module.php/core/frontpage_federation.php)

7. Copy Metadata

Copy the Entity ID URL under the SAML 2.0 SP Metadata section (that matches the authsource configured in the above step) from the URL https://simplesamlphp-url/simplesaml/module.php/core/frontpage_federation.php.

In the ADFS 2.0 console we need to add a relying party.
AD FS 2.0 -> Trust Relationships -> Relying Party Trusts, right click, 'Add Relying Party Trust'.
Using the URL copied above, paste the URL into 'Federation metadata address' field. Complete the Wizard to create the Relying Party.

Click 'Next' through remaining steps in Relying Party wizard

8. Configure Claims Rules (IdP)

In ADFS console, right-click on the Relying Party created in the above step, and select 'Edit Claim Rules'.

We will add three Claim Rules.

Outbound Claim Rule

1. Configure an LDAP Claim
   Image Modified

2. Code Block

   c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"), query = ";mail,userPrincipalName,displayName;{0}", param = c.Value);

1.  Configure Outbound LDAP attributes to be sent. As a minimum, email, UPN and Given Name

   Image Modified

9. Create Unique Identifier

1. Create a Custom Rule

   Image Modified

2. Create Custom Rule

   Code Block
   language none
   c1:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] && c2:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant"] => add(store = "_OpaqueIdStore", types = ("http://mycompany/internal/sessionid"), query = "{0};{1};{2};{3};{4}", param = "useEntropy", param = c1.Value, param = c1.OriginalIssuer, param = "", param = c2.Value);

1. NB: the URL http://mycompany/internal/sessionid should be written as is, and not substituted. 

1. Image Modified

10. Create Incoming Transform

1. Create an Incoming Mapping

   Image Modified

2. Using the custom rule created above, make an incoming mapping
   NB: the URL http://mycompany/internal/sessionid should be written as is, and not substituted.

1. Code Block
   c:[Type == "http://mycompany/internal/sessionid"] => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient");

1. Image Modified

11 Test Authentication via simplesaml (SP)

Navigate to https://simplesamlphp-url/simplesaml/module.php/core/authenticate.php, and click on the appropriate auth source.

If logging performing the test from a non-IE browser or on machine that is not on the ADFS machine's domain, you will be prompted for user credentials.
Enter the details of the user created in step 7.

Possible Issues:

1. Untrusted certificates / invalid common names in certificates

   ADFS is very particular about certificates it will trust. Ensure that both the SP and IdP certificates match the simplesamlphp-url and idp-instance-url, respectively. If you are testing add the certificate as in the note at Part 12
   

2. Requests coming from invalid URL

   Requests must originate from, and be sent to, the exact address specified in metadata. Ensure the the simplesamlphp-url and idp-instance-url are present in metadata
   

3. Requests coming from non HTTPS url

   ADFS will reject any non HTTPS requests with a particularly unhelpful error message. Ensure that the Federation request originates from HTTPS, and the the IdP address is also HTTPS
   

4. SSO path through not occurring (when logged in to ADFS domain)

   Authentication details won't be passed through in IE unless both the simplesamlphp-url and idp-instance-url are trusted URLs