Skip to main content

Configure Single Sign-On using Active Directory with ADFS and SAML

  • Updated

eRS supports single sign-on (SSO) logins through SAML 2.0. An SAML 2.0 identity provider (IDP) can take many forms, one of which is a self-hosted Active Directory Federation Services (ADFS) server. Active Directory Federation Service (ADFS) is a software component developed by Microsoft to provide Single Sign-On (SSO) authorization service to users on Windows Server Operating Systems. ADFS allows users across organizational boundaries to access applications on Windows Server Operating Systems using a single set of login credentials.

 

Requirements

To use ADFS to log in to your eRS instance, you need the following:

  • An Active Directory instance where all users have an email address attribute.
  • An eRS Cloud instance and you must have subscribed to the 'Authentication Plus' module from billing section. 
  • A server running Microsoft Server 2012 or later. This guide uses screenshots from Server 2109, but similar steps should be possible on other versions.
  • An SSL certificate to sign your ADFS login page and the fingerprint for that certificate.

After you meet these basic requirements, you need to install ADFS on your server. 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/'.

 

Step 1 - Adding a Relying Party Trust

At this point you should be ready to set up the ADFS connection with your eRS account. The connection between ADFS and eRS 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.

 

rtp-add.png

 

  1. In Select Data Source screen, use the last option, Enter data about the relying party manually   

    rtp-datasource.png

  2. On the next screen, enter a Display name that you'll recognise in the future, and any notes you want to make.

    rtp-display-name.png
  3. On the next screen, leave the certificate settings at their defaults.

    rtp-certificate.png
  4. On the next screen, check the box labeled Enable Support for the SAML 2.0 WebSSO protocol. The service URL will be https://app.eresourcescheduler.cloud/login/saml/123456, replacing 123456 with your eRS Account-ID. If you don't know your eRS account ID, visit the Account Details page in eRS.

    rtp-url.png
    Note that there's no trailing slash at the end of the URL.

  5. On the next screen, add a Relying party trust identifier as https://app.eresourcescheduler.cloud/Zit5huIxEPe9bfEk

    rtp-identifier.png

  6. On the next screen, select the Permit Everyone policy to allow all user to login using ADFS. You can also choose a different policy according to your requirements. 

    rtp-access.png

  7. On the next screen, the wizard will display an overview of your settings. Click on 'Next' to continue.

    rtp-review.png

  8. Now the relying party trust has been added successfully, click on 'Close' to exit the wizard.

    rtp-finish.png


Step 2 - Creating claim rules

Once the relying party trust has been created, you can create the claim rules and update the RPT with minor changes that aren't set by the wizard. Select Edit Claim Issuance Policy from the Actions sidebar.

 

edit-claim.png
 
  1. To create a new rule, click on Add Rule.

    Select Send LDAP Attributes as Claims for the Claim rule template and click Next.

    add-claim-rule.png


  2. On the next screen, enter a name for the rule and select Active Directory for the Attribute Store and map the following LDAP attributes to the output claim.

    LDAP Attribute Outgoing Claim Type
    objectSID uid
    E-Mail-Addresses email
    Given-Name firstName
    Surname lastName
    E-Mail-Addresses Name ID


    claim-mapping.png


  3. Click Finish to add the claim rule, and then click OK on the next screen to complete the step.

    claim-added.png


Step 3 - Adjusting the trust settings

You still need to adjust a few settings on your relying party trust. To access these settings, double click on the added RPT or select Properties from the Actions sidebar while you have the RPT selected.

  1.  Select Endpoints tab in Properties window to add a new endpoint.

    rtp-properties.png 
  2. Click Add SAML button to create a new SAML endpoint and fill up the following values in the next screen.

    Endpoint Type: SAML Logout
    Binding: POST
    Trusted URL: https://<ADFS server host>/<Federation URL>/?wa=wsignout1.0  which should look like this: https://fs.yourdomain.tld/adfs/ls/?wa=wsignout1.0 

    add-endpoint.png

  3. Confirm these changes by clicking OK. 
  4. Click on the Advanced tab, make sure SHA-256 is specified as the secure hash algorithm.

    rtp-properties-advanced.png

  5. Finally, click on OK to save the properties. You should now have a working RPT for eRS.

 

Step 4 - Configure eRS 

After setting up ADFS, you need to configure your eRS account to authenticate using SAML. In order to enable ADFS login to eRS, you will require the following information:

  1.  SAML endpoint URL:  This is the url which will be used to send SAML request from eRS to ADFS service, which is generally in format:  https://<ADFS server host>/<Federation URL>/.  This should resolve to something like: https://fs.yourdomain.tld/adfs/ls
  2. Identity Provider Identifier: This is the identifier for the Identity Provider Issuer. In this case it is the identity of ADFS service, which should be like: http://fs.yourdomain.tld/adfs/services/trust.
    You can use Get-AdfsProperties | Select-Object -Property Identifier PowerShell command to know the identifier.
  3. Token Signing Certificate: The SAML signing certificate is used to sign SAML requests, responses, and assertions from the service to relying applications. To obtain your certificate, open AD FS Management, select the Token-signing certificate from Certificates folder under the Service folder.

    view_certificate.png

    Click View Certificate and navigate to Details tab.

    certificate_detail.png

    Now click on Copy to File button to open up certificate export wizard. In the export wizard, select Base-64 encoded X.509 option.

    certificate-export.pngOn the next screen, enter a file location to export the certificate and click on Next and then Finish to complete the export of the certificate. The content of this exported certificate will be used in eRS to configure SAML.

 

Once you have these parameters, login to your eRS account (with Admin privileges) and move to Authentication Settings in Administration section. Click on pencil icon to edit SAML configuration, enable the SSO and fill in the information.

 

ers-sso-config.png

 

Click on Save to confirm the configuration changes. You should now have a working ADFS SSO implementation for eRS.

 

Important: When a user authenticate using SAML/SSO and logs into eRS for the first time, an entry for the user is created (if not already exists) with the default permission set applied. If default permission set has not been configured, then users will not have access to any data, till the time their access rights are configured. You can create and mark a permission set as default here.

 

To check if ADFS login is working as expected, visit the SAML Login Page and enter your eRS Account ID to continue, It should redirect you to the ADFS Sign-In page. You can use your AD credentials to login. After a successful login, ADFS will redirect you back to the eRS.

You can also use the url https://app.eresourcescheduler.cloud/login/saml/123456, replacing 123456 with your eRS Account ID, to directly reach to the ADFS login page after a successful SAML configuration.