RefTracker can act as a SAML 2.0 Service Provider (SP), enabling Single Sign-On (SSO) either by initiating a SP login or initiated by a SAML Identity Provider (IdP) of your choice.

To take advantage of SAML SSO, you will first create a trust relationship between RefTracker and your Identity Provider (ADFS, AzureAD, Okta, OneLogin, PingOne, Google, etc). To do this, you must be a RefTracker System administrator.

This section provides the essential settings that you need to configure an IdP-SP trust relationship and gives details of the procedure.

Why use SSO?

Single sign-on (SSO) is a session and user authentication service that permits a user to use one set of login credentials (e.g., name and password) to access multiple applications.

SSO shares centralized authentication servers that all other applications and systems use for authentication purposes and combines this with techniques to ensure that users do not have to actively enter their credentials more than once.

For staff this means a more user friendly experience by making logins quick and simple.

Helpdesk costs can be reduced by minimising the need for resets of multiple passwords per user.

IT departments will also benefit from having a centralized authentication server and the vastly reduced number of user credentials to be monitored and maintained.

SSO implementation guide

1. SSO requires that your RefTracker web site is SSL enabled.  i.e. uses the https://.... URL prefix.  It is also necessary that the web server is running Microsoft .NET Framework version 4.6.2 or later - preferably the most recent version.

2. To configure the IdP for your application there are certain settings that are required. These can vary depending on which IdP product your organization is using. The minimum settings required are shown in the SAML 2.0 IdP Settings section below, along with other settings that may or may not be required.

3. A saml.config file is required in your RefTracker root directory. This file contains details of both IdP and SP. An example file is given in the SAML Configuration File section below. The ServiceProvider element in the file should only require the RefTracker URL changed. However the PartnerIdentityProvider element may vary depending on the information required by your IdP.

4. Two certificate files are required to be stored in the RefTracker root\Certificates directory. The first is the default RefTracker certificate (sp.pfx) which is supplied with your RefTracker installation. The second will be supplied by your IdP.

5. During the login authentication process, matching SSO users with RefTracker staff is done by comparing the RefTracker "Staff Number" field to the User ID supplied by your IdP, so it is important to check these are identical when setting up users in RefTracker.

6. Check RefTracker application parameters in System -> Parameters -> 5) Server are correctly set for your SAML implementation. Details are given in RefTracker Application Configuration section below.

7. Have all users test login.

Using the staff login with SSO

When RefTracker SSO is enabled and configured for a given user, and that user is logged into the IdP network, and the user's browser is not already logged into a RefTracker session, the user will be taken directly to the RefTracker page they are trying to access, without the RefTracker login screen displaying.

SSO provides a corporate wide control of which staff can access your RefTracker application's staff functions, and removes the extra step of having to separately log into RefTracker.

For more details about how your staff will access RefTracker when SSO is enabled see the "Logging in when SSO is enabled" section of the Staff logon screen help page.

 

The following sections are intended for IT and SSO administration.

 

SAML 2.0 IdP settings

Your IdP will require the minimum settings below to describe RefTracker's SP:

(N.B. replace "exampleserviceproviderhttps" with your RefTracker site name)

 

Some IdPs, especially web-based SaaS products, have additional compatibility settings which are less critical but sometimes cause problems if not configured correctly:

Setting

Value

Default Relay State

optional

Signature / Digest Algorithm

RSA_SHA256 / SHA256

Request Compression

Yes or No

Signed Requests

Yes

Encrypted Requests

No

Signed Assertions

Yes

Encrypted Assertions

Yes or No

 

RefTracker SP configuration

SAML Configuration File

The SSO component incorporated in RefTracker is configured using an xml file: saml.config

A sample of this file can be found in your web site's root folder.

N.B. after modification it must be saved to the same directory.

 

Example saml.config file

 

<?xml version="1.0"?>

<SAMLConfiguration xmlns="urn:componentspace:SAML:2.0:configuration">

 

  <!-- This is RefTracker which is the service provider -->

 

  <ServiceProvider

       Name="https://exampleserviceproviderhttps.altarama.com/reft998.aspx"

       Description="Test Service Provider"                                         AssertionConsumerServiceUrl="https://exampleserviceproviderhttps.altarama.com/reft998.          aspx?ssologin=1"

       LocalCertificateFile="Certificates\sp.pfx"

       LocalCertificatePassword="password"/>

 

  <PartnerIdentityProviders>

    <!-- Web forms example -->

    <PartnerIdentityProvider

       Name="https://fedlogin.idp.com"

       Description="Test Identity Provider HTTPS"

       SignAuthnRequest="true"                                                                           SingleSignOnServiceUrl="https://sso.connect.pingidentity.com/sso/idp/SSO.saml2?idpid=b          860f9c0-ded6-400c-b744-253253f38562"

       SingleLogoutServiceUrl="https://                                       exampleserviceproviderhttps.altarama.com/SAML/SLOService.aspx"

       PartnerCertificateFile="Certificates\pingone-fedlogin.idp.com.2017.BASE64.crt.txt"/>

 

  </PartnerIdentityProviders>

 

</SAMLConfiguration>

 

The file contains two main elements:

                ServiceProvider - contains details of the RefTracker Service provider such as Name, URL and local certificate.

                PartnerIdentityProvider - contains details of your IdP's URLs and certificate. These values will be provided by your IdP.

 

Certificate Files

An SSO security certificate file must be provided by both IdP and SP.

Your IdP will supply a certificate file which must be stored in your RefTracker Root\Certificates directory. Update the PartnerCertificateFile entry in the configuration file with the name of the certificate file.

The default RefTracker certificate is sp.pfx and is located in your RefTracker Root\Certificates directory. A copy of this file will be required by your IdP.

RefTracker Application configuration

Create SSO user in RefTracker:

The procedure is exactly the same as for adding any other user, but making sure that the RefTracker "Staff number" field is the same as the User ID supplied by your IdP.

This page requires the Password fields to be complete, so just enter a dummy password. This will not be used when signing on via SSO.

N.B. it is most important that the Staff ID matches that provided by the IdP exactly. As responses from the IdP are encrypted it is not possible to automatically gather these, so they must be obtained from your IdP provider directly.

Click Update and complete any other required fields Required by the RefTracker staff details screen e.g.Email

Click Update again and the new user will be created in RefTracker.

 

Database Parameter Configuration:

Select the RefTracker menu option System -> Parameters -> 5) Server and set the following parameters:

 

5.7  Single-Sign-On logout page - Redirect  redirects the user to the address specified, instead of the reft998.aspx Login page after the user has been logged out. The logout page for a SSO system can be specified, such that users, after terminating their RefTracker session, are prompted to terminate any SSO session they used to login to RefTracker.

5.8  Use SSO - Yes/No option to switch SSO functionality on/off. If No is selected the user will be taken to the RefTracker reft998.aspx login page rather than using SSO login.

5.9  SSO Identity provider - Contains the URL of your chosen IdP. Initially this should be the same as the PartnerIdentityProvider Name value in your saml.config file.

5.12 Change user - Set this to “Yes” for users logged in under SSO to be offered the option to log on as a different users after they log out of RefTracker.

Set it to “No” if, for security reasons, users should not be offered the option to log on as a different user when SSO is in place.