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:
- Your Customer Secret Key, available in the Customer Portal in the "Iframe Configuration" menu.
- 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.
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) |
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;
}
Updated 12 months ago