Single Sign On - SAML (ADFS)

Owned by James Leeson (Unlicensed)
Last updated: Jan 21, 2020
3 min read

Overview

This document describes the means by which 3rd party systems can implement SAML (ADFS) Single Sign On, allowing their registered users to access Claritum’s systems without requiring each user to re-authenticate on the Claritum System via the login page.

Process Description

Claritum’s Single Sign On (SSO) process is described as follows:

Stage

Description

3rd party Login

User authenticates on 3rd party system (e.g. by logging into their intranet).

Claritum Link

The 3rd party system presents a ‘Claritum’ link to the User. This link contains a unique ‘session id’ generated by the 3rd party system.

SSO ‘Request’

User clicks the link to access the Claritum system.

SSO ‘Challenge’

Claritum system interrogates the 3rd party system to validate the given session id.

SSO ‘Response’

3rd party system checks the session id to identify the User. If the session id is valid (i.e. the User is currently logged in) then responds with the email address of the user (or an empty response if not a valid session id).

Acceptance

Claritum system identifies the Customer User with that email address and automatically logs them in.

The Claritum system allows one email address to be shared between multiple users. If such email is used in the SAML SSO login the user will see an error.

Rejection

If the 3rd party response is empty (i.e. invalid session id) then the Claritum System displays a ‘Failed Login’ page to the User.

Claritum Session Expiry

If at any time the User’s session expires on the Claritum system, it re-sends the session id to the 3rd party system. If the 3rd party system responds that the session is still active then the User will be transparently logged back in to the Claritum System and continue as normal.

Userlist Synchronisation

In order for the SSO process to work, the list of users must be synchronised between the two systems, i.e. the User must be registered on both the 3rd party system and the Claritum System.

Encryption / Security

All exchanges between the two systems are via HTTPS to ensure that no meaningful information is visible to any other parties.

Technical Details

Configuring Claritum for SSO

To configure SSO click on ‘Configuration’ on the left hand menu then click ‘Integrations’. Then click on the SAML tab. If you cannot see the SAML tab please contact Claritum support.

Configuration Options

Use the check boxes to enable SAML for different types of users. If SAML is enabled for a group of users they will be unable to login by the Claritum login page. Also they will be unable to reset their password. Admin users will be unable to set new passwords for them.

 

SP Metadata - This field will be populated with a URL that can be used to download the required XML file to configure SAML at the identity provider end. The download button will allow you to download the metadata.

IdP Metadata - This field allows you to enter the metadata URL so that Claritum can receive from the Identity Provider.

 

SSO Access Point (for the ‘request’)

This is shown to you on the page where you configure the SSO for the customer.
You should make the 3rd party’s Systems Administrator responsible for enabling single-sign on aware of this information.

SSO ‘response’

The 3rd party system should respond with a simple XML response containing the email address of the validated User and an optional message:

<login result="success"> <email>user@sample.com</email> <message>Please remember to spend wisely!</message> </login>

If the User could not be validated then the 3rd party’s response should be empty or the ‘result’ property should be ‘failed’:

<login result=”failed”> <message>Please contact your Department Manager for help</message> </login>

Timeout

The Claritum system will allow up to 5 seconds for the remote system to respond before giving up and directing the user to the ‘failed’ login page.

 

Troubleshooting

  • Login page, URL shows 'sso_error=3'
    This means information was missing in the initial URL. Check you have at least 'cust' and 'uid' properties on the URL.

  • Login page, URL shows 'sso_error=5'
    The customer organisation could not be found using the 'uid' identifier.
    On the Customer Details page, check the example url shown in the section configuring the SSO.
    Set the 'External ID' field if it's not already set.

  • Login error page, URL shows 'sso_error=7'
    An invalid response was received from the remote system when validating the login.