Single Sign On Documentation

Last Updated: March 2024, Documentation Revision: 1.0

Note: This file may not contain the latest information. The latest version of this documentation will always be available from: https://developer.holidaytaxis.com/

Contents

  1. Introduction
  2. Migration from Previous System
  3. Integration Instructions
  4. Code Sample

Introduction

To allow users to log in to the Holiday Taxis Agents system smoothly when using another application, the Single Sign On (SSO) system allows you to create a link which the user can click on and be immediately logged in.

This URL is time-limited, and must be accompanied by a simple signature which you create using a secret token Holiday Taxis will share with you.

For support enquiries, and information on how to set up a test account, please email us on salessupport@holidaytaxis.com.

Migration from Previous System

If you had previously integrated the old system, you will already have been assigned a single SSO client, and an SSO identifier for each of your users. You will need to arrange with Holiday Taxis to securely receive a secret token, and implement the new signature algorithm and URL format described below.

Example of change

The new link for the same user might look like this: https://www.holidaytaxisagents.com/de/login/?sso_client=omnicorp&sso_id=ed-209&sso_ts=2043-11-04T21:12:36&sso_hash=b509884bda0698913e528a561306e626cab5294c79562948361b9b5edf25517

This example is explained in more detail below.

Integration Instructions

Configuration

To create an SSO link, you will need three pieces of information:

  1. A fixed SSO client string which identifies you in our system.
  2. A secret token, which you must store securely and never transmit as part of a URL. This will be a 36-character string starting with “htsso_”. This fixed prefix allows you to scan source code and logs for accidental disclosure of the secret; if it is exposed, immediately contact Holiday Taxis to generate a new secret.
  3. A per-user SSO identifier.

There can be any number of SSO identifiers attached to the same client, which will all share the same secret token.

Creating a link

To log in, the user will need to navigate to a link starting https://www.holidaytaxisagents.com/en/login/? with at least the following query string parameters:

Notes:

Timestamps

The timestamp (sso_ts parameter) should be the current time in UTC when the link is generated.

The generated link will be valid for 5 minutes from this time.

If the user visits a link with a timestamp more than 5 minutes in the past, or which is in the future, they will be shown a username and password login form.

Calculating the hash

To calculate the hash, you will need to:

  1. Combine the SSO client, SSO identifier, timestamp, and secret token values into one string, separated by the pipe character |
    • Note that this must not include the parameter names such as sso_client= or sso_id=
    • The values must be in this exact order
  2. Calculate a SHA-256 hash of this combined value
  3. Use the hexadecimal representation of the hash as the sso_hash in the parameter

Reminder: you must not include the secret token in the login URL, or anywhere visible to the user, as this would allow them to create login links for other users.

The Holiday Taxis system will calculate the same hash with its stored copy of the secret token. If it does not match the value in the sso_hash parameter, the user will be shown a username and password login form.

The timestamp (sso_ts parameter) should be the current time in UTC when the link is generated.

Example

Given the following scenario:

You will construct the link as follows:

The final link will look like this:

https://www.holidaytaxisagents.com/de/login/?sso_client=omnicorp&sso_id=ed-209&sso_ts=2043-11-04T21:12:36&sso_hash=9b509884bda0698913e528a561306e626cab5294c79562948361b9b5edf25517

Any user visiting this link before 4th November 2043 16:17:36 America/Detroit (i.e. within 5 minutes after it was generated) will automatically be logged in as the user assigned to SSO identifier ed-209.

Sample Code

PHP Example Code

       // replace with the SSO Identifier of the user who wants to log in
        $ssoId = 'ed-209';

         // replace with your SSO Client, which will be the same for all users
        $ssoClient = 'omnicorp';

        // Create a DateTime object representing the current time in UTC
        $dateTime = new DateTime('now', new DateTimeZone('UTC'));

        // Format the DateTime object to the desired format
        $timestamp = $dateTime->format('Y-m-d\TH:i:s');

        // replace with your Secret Token; remember never to share this or allow the user to see it
        $secretToken = 'htsso_xvuw8mvjj8y3eshfz6pncy5qcw8ydk';
        $hashToken =  hash('sha256',"{$ssoClient}|{$ssoId}|{$timestamp}|{$secretToken}");
        $url =  "https://www.holidaytaxisagents.com/de/login/?sso_client=omnicorp&sso_id=ed-209
                &sso_ts=2043-11-04T21:12:36&sso_hash=".$hashToken;


        header("Location: $url");
        die();

Browser Js Example Code

Note: Kindly note that Secret Token should not be share on the browser as this may lead to security breach


        // replace with the SSO Identifier of the user who wants to log in
        const ssoId = 'ed-209';

        // replace with your SSO Client, which will be the same for all users
        const ssoClient = 'omnicorp';

        // replace with your Secret Token; remember never to share this or allow the user to see it
        const secretToken = 'htsso_xvuw8mvjj8y3eshfz6pncy5qcw8ydk';

        // Construct Timestamp in the format below
        let dateTime = new Date();
        dateTime = dateTime.toISOString().slice(0, 19);

        const text = `${ssoClient}|${ssoId}|${dateTime}|${secretToken}`;

        digestMessage(text).then((digestHex) => console.log(`https://www.holidaytaxisagents.com/de/login/
                ?sso_client=${ssoClient}&sso_id=${ssoId}&sso_ts=${dateTime}&sso_hash=${digestHex}`));


        async function digestMessage(message) {
            const msgUint8 = new TextEncoder().encode(message); // encode as (utf-8) Uint8Array
            const hashBuffer = await crypto.subtle.digest("SHA-256", msgUint8); // hash the message
            const hashArray = Array.from(new Uint8Array(hashBuffer)); // convert buffer to byte array
            const hashHex = hashArray
                .map((b) => b.toString(16).padStart(2, "0"))
                .join(""); // convert bytes to hex string
            return hashHex;
        }