Generating the Authentication Key

📘

NOTE:

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.

🚧

NOTE:

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

📘

NOTE:

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

FieldTypeDescriptionExample
tokenExIDstringYour TokenEx ID123456789
originstringcomma separated list of fully qualified Origin in the ancestor chainhttps://mysite.com
https://mysite.com:8080
timestampstringThe timestamp (UTC) when the hash is generated, in yyyyMMddHHmmss format20180109161437 (January 9th, 2018 4:14:37 PM UTC, formatted in yyyyMMddHHmmss format)
tokenSchemestringEither 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.

ParameterTypeDescription
authenticationKeystringConcatenated String for generating HMAC: tokenExID|origin|timestamp|tokenScheme

e.g.
HmacSHA256('123456789|https://mysite.com|20180109161437|sixANTOKENfour', customerSecretKey)

🚧

NOTE:

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.

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

$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;
}
?>
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)
/* 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;
}