Technical manual

Here you will find instructions on how to integrate SafeTok protection into your website - you will find a copy of this information in the Website Administration Area with your SafeTok ID and Key already substitued into the code.

The integration process is quite straighforward. Should you have any questions please contact us so we can help you.

Access codes

After you have registered your webpage for SafeTok protection, you will be provided with a Website SafeTok ID and SafeTok Key.

You will need to store your SafeTok Privder ID and Provider Key in a variable for use during the authentication process - to do this you will need to add this code to the webpage where you authenticate your users. You will need to make sure that you substitute "Your SafeTok ID" and "your SafeTok Key" with the SafeTok ID and SafeTok key you will be given when registering your webpage.

$SafeTokProviderId = "Your SafeTok ID";
$SafeTokProviderKey= "Your SafeTok Key";

Integration process

In order to add SafeTok protection to your website you need to add two steps to your authentication process.

Step 1: Redirect user to safetok.com to authenticate himself

First, you redirect the user to "http://www.safetok.com/authentication/authenticate.php", where the user will be requested to perform SafeTok authentication. When redirecting, you should provide several parameters which would identify your website and the user who is being authenticated.

It is also advised to pass the return url - page where user will be redirected when the authentication process has been completed.

You must also pass in a challenge value. This value will be used to generate a response (authorization value) only if the user successfully completed the SafeTok authentication process.

Step 2: When the user comes back with an authorization code, check it

When safetok.com redirects the user back to your website, it will pass along the authorization code if the user has passed the SafeTok authentication in the "SafeTokAuthResponse" parameter. You should check if this value is correct before allowing the user in.

The authorization value is based on your secret "Website Key" and the challenge value, which you submitted in step 1. For this reason you should keep the Website Key safe and not expose it under any conditions.

Integration code

Above was an intuitive description of how the authentication process has to be adjusted. Here we will provide an example of how this could be written. The integration code is aimed at a PHP based website, but you may adopt it for any other scripting language used.

Step 1: Redirect user to safetok.com to authenticate himself

// -> Add this code to the place, after the user has completed local authentication -
// 1. Prepare the SafeTok Authentication Parameters
$sWebsiteUsername = ; //TODO: Set here the username of the user
$SafeTokReturnURL = 'http://'.$_SERVER['SERVER_NAME'].$_SERVER['PHP_SELF']; //Current page

// - Do not modify, unless required -
// 2. Generate an authentication challenge and store it
$_SESSION['SafeTokAuthChallenge'] = sha1(mt_rand().mt_rand());

// 3. Send user to SafeTok Authentication Server
$sSafeTokURL = "http://www.safetok.com/authentication/authenticate.php?v=1".
               "&"."providerId"."=".$SafeTokProviderId.
               "&"."authUsername"."=".$sWebsiteUsername.
               "&"."authChallenge"."=".$_SESSION['SafeTokAuthChallenge'].
               "&"."authReturnURL"."=".urlencode($SafeTokReturnURL);
header('Location: '.$sSafeTokURL);

Step 2: When the user comes back with an authorization code, check it

// -> Add this code to the page, specified above as the return URL -
if (isset($_REQUEST['SafeTokAuthResponse']))
{
  // 1. Retrieve challenge and provided response
  $sChallenge = $_SESSION['SafeTokAuthChallenge'];          //provider's challenge
  $sProvidedResponse = $_REQUEST['SafeTokAuthResponse'];    //safetok's response
      
  // 2. Compute correct response
  $sCorrectResponse = sha1($sChallenge.$SafeTokProviderKey);
      
  // 3. Check if provided response is correct
  if ($sCorrectResponse == $sProvidedResponse)
  {
    // -> SafeTok authentication successfully completed, continue...
    // NOTE: check here if password authentication has been passed, if it is used locally
    // TODO: add authentication process continuation
  }
  else
  {
    // -> SafeTok authentication failed
    // TODO: Notify the user that SafeTok authentication failed
  }
}

Step3: Add a link to the SafeTok Area to allow users to adjust their SafeTok protection settings

<!-- Use This code to create a text link to the SafeTok Protection Settings or include
this link in your menu or otherweise -->
<a href="http://www.safetok.com/authentication/userArea.php">SafeTok protection settings
</a>