CompliSpace Developer Blog

CompliSpace Fundamentals Referred Sign In

Introduction

For better integration into existing client sites, CompliSpace has implemented a simplified method for signing in to Fundamentals sites.

This is accomplished by allowing an organisation’s internal sites to generate signed links that signify to Fundamentals that the user is already trusted by the referring site.

Helper classes/sample code is available on GitHub as GIST 907000. The sample code is available in PHP, C# .NET, Node.js (JavaScript) and Python.

Implementation

The implementation consists of appending several GET request parameters that are signed by a secret key.

ATTENTION:

The secret key MUST NEVER be exposed to the client browser. URL generation MUST be done server side.

Exposing the secret key will compromise the security of your site, and possibly breach the terms of your contract with CompliSpace.

If you would like to use this feature, please contact CompliSpace and request a Referred Sign In Private Key.

To use the referred login mechanism for CompliSpace Fundamentals, simply link to the regular page you want people to view (eg, http://xyz.complispace.com.au/HRAdministrationManagersOnly) and append the following GET parameters:

referredUserLogin=<login username>
referredExpires=<unix epoch timestamp, must be no greater than 6 hours in the 
future>referredAccessKeyId=<your sites key id>referredSignature=<
base 64 encoded calculated signature of the request>

The referredSignature is calculated with the following pseudo-code:

$stringToSign = (sting)$referedUserLogin+":"+(string)$referredExpires+":"+(string)$secretAccessKey;
$referredSignature = base64_encode(hash_hmac("sha256", $stringToSign, $secretAccessKey));

Note that for this implementation the output of the hash_hmac() function is expected to be a lowercase string of hex digits (see the hash_hmac() PHP function).

Example (pseudo code):

referredUserLogin=bob (the user who is accessing the site)
referredExpires=1320969600  (11am, 11th November 2011 - rememberance day)
referredAccessKeyId=mySiteId (the key that identifies the signer)
secretAccessKey=connie (the secret, unshared key used to sign the request)

  1. Calculate the string to sign:
    $stringToSign = "bob:1320969600:mySiteId";
  2. Create the signature:
    $signature = hash_hmac("sha256", "bob:1320969600:mySiteId", "connie");
    The result will be 7435b9129f07a93f790875f061c9396b27cf5d6bb5be8cf7b37afacd11dd00ca
  3. Base64 encode the signature:
    $signature = base64_encode($signature);
    The result will be NzQzNWI5MTI5ZjA3YTkzZjc5MDg3NWYwNjFjOTM5NmIyN2NmNWQ2YmI1YmU4Y2Y3YjM3YWZhY2QxMWRkMDBjYQ==
  4. Build the url:
    $url = sprintf("http://xyz.complispace.com.au/Home?referredUserLogin=%s&referredExpires=%s&referredAccessKeyId=%s&referredSignature=%s", $referredUserLogin, $referredExpires, $referredAccessKeyId, $signature);

This will result in the final URL:

http://xyz.complispace.com.au/Home?referredUserLogin=bob&referredExpires=1320969600&referredAccessKeyId=connie&referredSignature=NzQzNWI5MTI5ZjA3YTkzZjc5MDg3NWYwNjFjOTM5NmIyN2NmNWQ2YmI1YmU4Y2Y3YjM3YWZhY2QxMWRkMDBjYQ==

If you have any questions or feedback, please contact development@complispace.net