Skip to main content

SSO - Set up enableHR as a service provider on ADFS 2.0

This guide covers SAML 2.0 SSO setup using Windows Server 2012R2 Standard with AD FS 2.0 serving as Identity Provider.

Configuring and installing ADFS is beyond the scope of this guide, but is detailed in a Microsoft KB article.

When you have a fully installed ADFS installation, note down the value for the 'SAML 2.0/W-Federation' URL in the ADFS Endpoints section. If you chose the defaults for the installation, this will be '/adfs/ls/'.

Prerequisites

  • WIndows Server 2012 R2 standard 
  • Active directory domain service installed
  • DNS
  • Certificate (or self signed certificate for testing purposes) 
  • AD FS - Active Directory Federation Service role installed

Note: Windows Server 2008 R2 supports AD FS 2.0, Windows Server 2012 supports AD FS 2.1, Windows Server 2012 R2 supports AD FS 3.0. enableHR SSO setup with AD FS 2.0 covered in this guide.

 

Windows server configuration for enableHR SSO

1. The connection between ADFS and enableHR is defined using a Relying Party Trust (RPT). Select the "Relying Party Trusts" folder from AD FS Management and add a new standard Relying Party Trust from the Actions sidebar. This starts the configuration wizard for a new trust.

sso_adfs1.png

 

2. Select "Enter data about the relying party manually".

sso_adfs2.png

 

3. Enter Name, e.g. “enableHR”.

2019-08-16_17_07_41-image__725_587_.png

 

4. Select “AD FS Profile”.

sso_adfs4.png

 

5. Skip token encryption certificate step, it’s not supported by enableHR SSO.

sso_adfs5.png

 

6. Your “Single sign on URL” for AD FS is https://login.enablehr.com/app/saml

Copy it and paste https://login.enablehr.com/app/saml in AD FS wizard as “Relying party SAML 2.0 SSO service URL”

mceclip0.png

 

7. Enter your enableHR URL as “Relying party trust identifier”, e.g. “https://login.enablehr.com/app/saml

Note: Do NOT add slash "/" at the end of identifier, otherwise integration won't work.

mceclip1.png

 

8. Select “Permit all users..” if you want to allow all Active Directory users to login to enableHR or “Deny all..” if you want to allow specific users later.

sso_adfs77.png

 

9. Don’t change anything on the next step.

sso_adfs8.png

 

10. Select “Open the Edit Claim rules..

sso_adfs9.png

 

11. Click ‘Add’ on Claim rules wizard and keep “Select LDAP Attributes as Claims” on first step.

2019-08-16_17_22_27-How_to_set_up_Single_Sign-On_for_enableHR_with_ADFS_2.0_-_enableHR_Application_D.png

 

12. Add “Email” rule with E-Mail Address claim and Active Directory as attribute store. 

Note: "Email / User ID" as outgoing claim type.  You must type it exactly as 'Email / User ID' in the field.

2019-08-16_17_24_09-How_to_set_up_Single_Sign-On_for_enableHR_with_ADFS_2.0_-_enableHR_Application_D.png

 

13. Add “Email Name ID” rule with Email Name ID claim, Active Directory as attribute store and 'E-Mail-Addresses ' as LDAP attribute.  Note "Name ID" as outgoing claim type.  You must select or type it exactly as 'Name ID' in the field.

14. Add “First Name” rule with First Name claim, Active Directory as attribute store and 'Given-Name' as LDAP attribute.  Note "First Name" as outgoing claim type.  You must type it exactly as 'First Name' in the field.

15. Add “Last Name” rule with Last Name claim, Active Directory as attribute store and 'Surname' as LDAP attribute.  Note "Last Name" as outgoing claim type.  You must type it exactly as 'Last Name' in the field.

 

Summary of all rules needed

Claim Rule Name Attribute Store LDAP Attribute Outgoing Claim Type
Email Active Directory E-Mail-Addresses Email / User ID
Email Name ID Active Directory E-Mail-Addresses Name ID
First Name Active Directory Given-Name First Name
Last Name Active Directory Surname Last Name

 

 

Mapping attributes from Active Directory with ADFS and SAML 

When using SAML login with ADFS, you can pass other values in addition to the authentication values. This article describes how to pass user's custom roles.

These values are defined as Claim Rules in the Relying Party Trust. To edit the Claim Rules, select the Relying Party Trusts folder from AD FS Management, and choose Edit Claim Rules from the Actions sidebar. New rules are added by clicking Add Rule and then selecting a template from the window that pops up. 

 

Roles

Setting the role of a user based on their membership in a group is a two-step process. First, you create a new rule using the Send Group Membership as a Claim template. Second, you modify the definition generated by that rule slightly to create a custom rule that correctly passes the information to Zendesk.

Example

Add “HR User (Branch A)” rule with HR User claim, User's group of "HR User" Outgoing Claim type "Roles" and Outgoing claim value as "HR User (Branch A)".

 

To create the group membership rule:

Add a new rule and Select Send Group Membership as a Claim for the template.

mceclip0.png 

 

Locate the group that you wish to map to the role by using the Browse button.

mceclip1.png

 

For Outgoing claim type, type Roles(*Please note - you need to type 'Roles', you can't choose 'Role' from the dropdown)

mceclip2.png

 

For Outgoing claim value, use the same value as the SAML Role name configured in enableHR

Click Finish

 

enableHR SSO configuration

SSO configuration is currently completed by enableHR staff.  Please send the XML file FederationMetadata.xml to enableHR

You can find out your XML metadata file from your AD FS server via https://yourserver.yourdomain/FederationMetadata/2007-06/FederationMetadata.xml 

Example: https://adtest.enablehr.com.au/FederationMetadata/2007-06/FederationMetadata.xml

Please send the XML file FederationMetadata.xml to your enableHR Project Manager

 

 

Additional information

The Federation Server is usually not directly accessible from the Internet, so you need to set up a proxy. Here’s additional information about proxy setup:
https://technet.microsoft.com/en-us/library/dd807055(WS.10).aspx

One thing to ensure is that your ADFS users that will be using SSO with enableHR have an email address populated in Active Directory.  If the user already exists in enableHR (they were manually created)  and you want that user to use SSO, you should first manually change their username to be their email address otherwise a duplicate user will be created when that user first usees SSO.  An example is an employee “Peter Smith” who has an enableHr username (smith2468)  You should first manually change his enableHR username from smith2468 to peter.smith@example.com



If using these instructions for Server 2016

https://blogs.technet.microsoft.com/rmilne/2017/06/20/how-to-enable-idpinitiatedsignon-page-in-ad-fs-2016/