Overview

This document describes the means by which 3^rd-party systems can implement 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
3^rd-party Login	User authenticates on 3^rd-party system (e.g. by logging into their intranet).
Claritum Link	The 3^rd-party system presents a ‘Claritum’ link to the User. This link contains a unique ‘session id’ generated by the 3^rd-party system.
SSO ‘Request’	User clicks the link to access the Claritum system.
SSO ‘Challenge’	Claritum system interrogates the 3^rd-party system to validate the given session id.
SSO ‘Response’	3^rd-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 Claritum User with that email address and automatically logs them in.
Rejection	If the 3^rd-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 3^rd-party system. If the 3^rd-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 3^rd-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.

In addition to this, the Claritum System can be configured to only accept SSO attempts from the specific IP address of the 3^rd-party system.

Technical Details

Configuring Claritum for SSO

On the ‘Customer Details’ page a section is available for configuring the SSO details for the customer.

The Customer SSO Login URL is where the browser will take the user if they attempt to access any page on the Customer Catalogue without being logged in. This would typically be something like the main login page on the Customer's intranet.

The Challenge Request URL is where the Claritum System will ask the Customer's system for the logged-in status of a given user.

Note that the 3^rd-party ‘challenge’ url is split into two parts. This allows you to configure additional information to be sent to the 3^rd-party system during the ‘challenge’. Note that the ‘challenge’ URL must be SSL (i.e. via https).

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 3^rd-party’s Systems Administrator responsible for enabling single-sign on aware of this information.

SSO ‘response’

The 3^rd-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 3^rd-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.

Example

The following sections give a detailed example of the SSO transactions:

<login result=”success”>

  <email>joe.bloggs@thirdpartysystem.org</email>

</login>

Stage	Example
3^rd-party Login	n/a
Claritum Link / SSO ‘Request’	https://3rdparty.claritum.com/login/sso.php?cust=abcd&uid=c6b38...
SSO ‘Challenge’	https://www.thirdpartysystem.org/sso/challenge.asp?id=c6b3885ac
SSO ‘Response’	<login result=”success”> <email>joe.bloggs@thirdpartysystem.org</email> </login>
Acceptance	Claritum’s ‘Welcome’ page.
Rejection	Claritum’s ‘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.

For further assistance, please contact your Super User.

Browser not supported