Generating the Authentication Key

info

For generating the Authentication Key for CVV Only Mode, see Generating the Authentication Key

The first step in utilizing the iFrame is establishing an authentication key. This is done by generating a Base64-encoded Hash-based Message Authentication Code HMAC based on two things:

1. Your Customer Secret Key, available in the Customer Portal in the "Iframe Configuration" menu.
2. A pipe-delimited concatenation of the fields below. The values for these fields will need to also match the values within the iFrame config object.

For security purposes, the generation of the HMAC will need to be done server side so the Customer Secret Key won't be exposed.

warning

The Authentication Key is only valid with a timestamp less than 20 minutes old.

info

In the TokenEx Production environment, the origin must use HTTPS.

Field	Type	Description	Example
tokenExID	string	Your TokenEx ID	123456789
origin	string	comma separated list of fully qualified Origin in the ancestor chain	https://mysite.com https://mysite.com:8080
timestamp	string	The timestamp (UTC) when the hash is generated, in yyyyMMddHHmmss format	20180109161437 (January 9th, 2018 4:14:37 PM UTC, formatted in yyyyMMddHHmmss format)
tokenScheme	string	Either the name (case insensitive) or the JSON value of the Token Scheme to be used (see Standard Token Schemes)	PCI

Having established the information above, you can then generate the HMAC using HMAC-SHA256. Here is an example of a C# method that generates the HMAC based on the concatenated information and your API Key. The hash generated by this method is then used in the authenticationKey parameter within the iFrame Configuration Object. The Authentication Key must be Base64 encoded.

Parameter	Type	Description
authenticationKey	string	Concatenated String for generating HMAC: tokenExID|origin|timestamp|tokenScheme e.g. HmacSHA256('123456789|https://mysite.com|20180109161437|sixANTOKENfour', customerSecretKey)

warning

The tokenScheme value used in the config object must match the tokenScheme value used in the concatenated string used to generate the authentication key. For example, if the config object uses "PCI", you must use "PCI" to generate a valid authentication key. You cannot use "26". Likewise, if you use "26" in the config object, you must use "26" to generate a valid authentication key. The values must match.

C#

public static void Main()
{
  var time = DateTime.UtcNow.ToString("yyyyMMddHHmmss");
  var tokenexid = "123456789"; //From client portal
  var clientSecretKey = "A1b2C3D4e5F6h7I8j9K0l1M2n3O4p"; // From client portal
  var tokenScheme = "PCI";
  var origin = "https://www.example.com";
  var concatenatedString = tokenexid+"|"+origin+"|"+time+"|"+tokenScheme;
  var AuthenticationKey = GenerateHMAC(concatenatedString, clientSecretKey);
}

private string GenerateHMAC(string concatenatedInfo, string HMACkey)
{
  var result = string.Empty;
  var hmac = new System.Security.Cryptography.HMACSHA256();
  hmac.Key = System.Text.Encoding.UTF8.GetBytes(HMACkey);
  var hash = hmac.ComputeHash(System.Text.Encoding.UTF8.GetBytes(concatenatedInfo));
  result = Convert.ToBase64String(hash); // Ensure the string returned is Base64 Encoded
  return result;
}

PHP

<?php

$timestamp = gmdate("YmdHis");
$tokenexId = "123456789"; //From client portal
$clientSecretKey = "A1b2C3D4e5F6h7I8j9K0l1M2n3O4p"; // From client portal
$tokenScheme = "PCI";
$origin = "https://www.example.com";
$concatenatedString = $tokenexId . '|' . $origin . '|' . $timestamp . '|' . $tokenScheme;
$authenticationKey = GenerateHMAC($concatenatedString, $clientSecretKey);

function GenerateHMAC($concatenatedInfo, $HMACkey) {
  $hmac = hash_hmac('sha256', $concatenatedInfo, $HMACkey, true); //Output needs to be in raw binary data format
  $result = base64_encode($hmac);
  return $result;
}
?>

Python

import hmac
import hashlib
import base64
from datetime import datetime

def generateHMAC(payload, HMACKey):
payload = payload.encode()
HMACKey = bytes(HMACKey, 'UTF-8')
my_hmac = hmac.new(HMACKey,payload,hashlib.sha256)
return base64.b64encode(my_hmac.digest()).decode()

time = datetime.utcnow().strftime("%Y%m%d%H%M%S")
tokenexid = "123456789" # From client portal
clientSecretKey = "A1b2C3D4e5F6h7I8j9K0l1M2n3O4p" # From client portal
origin = "https://www.example.com"
token_scheme = "PCI"
concatenated = tokenexid + "|" + origin + "|" + time + "|" + token_scheme
AuthenticationKey = generateHMAC(concatenated, clientSecretKey)

JavaScript

/* This example is for Javascript backends, such as Node.js.
 TokenEx strongly recommends generating the authentication key in the backend
and not exposing your TokenEx credentials within the frontend Javascript. */

var tokenExId = "123456789";
var clientSecretKey = "A1b2C3D4e5F6h7I8j9K0l1M2n3O4p"; // From client portal
var tokenScheme = "PCI";
var timeStamp = new Date()
  .toISOString()
  .replace(/[^0-9]/g, "")
  .slice(0, -3); // outputs UTC date in yyyyMMddHHmmss

function generateHmac() {
  let concatenatedData = tokenExId + "|" + origin + "|" + timeStamp + "|" + tokenScheme;
  let hmac = CryptoJS.HmacSHA256(concatenatedData, clientSecretKey);
  let hmacAsBase64 = CryptoJS.enc.Base64.stringify(hmac);
  return hmacAsBase64;
}