Customer Key Authentication

To enable identification and personalisation across devices the class CustomerKeyAuthentication must be implemented. Implementation examples are in NodeJS, C#, Java, and PHP. This class requires Message Authentication to be implemented.

The following three cookies must be available once done.

  • apptus.sessionKey - A unique id. UUID / GUID.
  • apptus.customerKey - A SHA256 hash of the id of a signed in visitor.
  • apptus.token - The customerKey signed with the private key, privateKey (received from Apptus during the cloud configuration). This cookie should only be set for signed in visitors.

The reason both customerKey and token exist is that if the private key leaks or becomes public, it can be changed without losing behaviour and notifications for the sites visitors.

Property Value Description
Name apptus.customerKey, or apptus.sessionKey, or apptus.token See the section above for more information about each cookie.
Path / The path is defined as the root of the Domain.
Domain Site host name The Domain must match the host name of the site, for example www.esalesdrivensite.com.
Expires Expiration date The expiration date must be one year into the future.
HttpOnly N/A The HttpOnly must not be specified as the Javascript Library interacts with the cookie.

Usage

When a visitor signs in a customer key and an authorization token is to be generated server side. The authorization token is used to validate the customer key in the eSales Web API service.

It is recommended to use the visitor specific value and the private key during the customer key and token generation.

  • The customer key is to be set in the apptus.customerKey cookie.
  • The authorization token is to be set in the apptus.token cookie.

These cookies should live as long as the visitor is signed in, and by binding the sign out button/link to the endSession()-function in the JavaScript library they will be reset automatically.

Example

//Example in C#.
var auth = new CustomerKeyAuthentication("private-key", "user-name");

var customerKeyCookie = new HttpCookie("apptus.customerKey", auth.CustomerKey);
customerKeyCookie.Expires = DateTime.Now.AddYears(1);

var tokenCookie = new HttpCookie("apptus.token", auth.Token);
tokenCookie.Expires = DateTime.Now.AddYears(1);

Response.Cookies.Add(customerKeyCookie);
Response.Cookies.Add(tokenCookie);

Implementation

const crypto = require('crypto');
const ma = require('./messageAuthentication');

module.exports = (privateKey, user) => {
    const customerKey = crypto.createHash('sha256').update(user).digest('hex');
    const token = ma(privateKey).sign(customerKey);

    return {
        getCustomerKey() {
            return customerKey;
        },
        getToken() {
            return token;
        }
    }
};
using System;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

namespace Apptus.ESales.Connector
{
    public class CustomerKeyAuthentication
    {
        /// <summary>
        /// Creates a new instance that contains a personal customer key and a token, that can be used for
        /// cross-device client-side notifications in eSales Web API. This object should be created
        /// when the user has successfully logged in, and the respective values should be set in cookies.
        /// </summary>
        /// <param name="privateKey">A private key that is unique for this site. This key is provided by Apptus.</param>
        /// <param name="user">The user name, or other user-unique value, of the customer that logged in.</param>
        /// <exception cref="ArgumentException">If privateKey or user is null or empty.</exception>
        public CustomerKeyAuthentication(string privateKey, string user)
        {
            CustomerKey = Hash(user);
            Token = new MessageAuthentication(privateKey).Sign(CustomerKey);
        }

        /// <summary>
        /// A hash based on a user specific value, such as user name.
        /// This value should be stored in a cookie named "apptus.customerKey".
        /// </summary>
        public string CustomerKey { get; private set; }

        /// <summary>
        /// The signature of this customerKey.
        /// This value should be stored in a cookie named "apptus.token".
        /// </summary>
        public string Token { get; private set; }

        private static string Hash(string input)
        {
            return new SHA256Managed()
                .ComputeHash(Encoding.UTF8.GetBytes(input))
                .Aggregate(new StringBuilder(), (sb, b) => sb.AppendFormat("{0:x2}", b))
                .ToString();
        }
    }
}
package com.apptus.esales.connector;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

/**
 * A class that should be used for creating personal customer keys when using eSales Web API.
 */
public class CustomerKeyAuthentication {

    private final String customerKey;
    private final String token;

    /**
     * Creates a new instance that contains a personal customer key and a token, that can be used for
     * cross-device client-side notifications in eSales Web API. This object should be created
     * when the user has successfully logged in, and the respective values should be set in cookies.
     * See {@link #getCustomerKey()} and {@link #getToken()}.
     * @param privateKey A private key that is unique for this site. This key is provided by Apptus.
     * @param user The user name, or other user-unique value, of the customer that logged in.
     * @throws IllegalArgumentException If privateKey or user is null or empty.
     **/
    public CustomerKeyAuthentication(String privateKey, String user) {
        customerKey = hash(user);
        token = new MessageAuthentication(privateKey).sign(customerKey);
    }

    /*
     * @return A hash based on a user specific value, such as user name.
     * This value should be stored in a cookie named "apptus.customerKey".
     */
    public String getCustomerKey() {
        return customerKey;
    }

    /**
     * @return The signature of this customerKey.
     * This value should be stored in a cookie named "apptus.token".
     */
    public String getToken() {
        return token;
    }

    private static String hash(String input) {
        MessageDigest md;
        try {
            md = MessageDigest.getInstance("SHA-256");
        } catch (NoSuchAlgorithmException e) {
            //it should not happen
            throw new RuntimeException(e);
        }
        md.reset();
        md.update(input.getBytes(StandardCharsets.UTF_8));
        return MessageAuthentication.toHexString(md.digest());
    }
}
<?php

namespace Apptus\ESales\Connector;

/**
 * A class that should be used for creating personal customer keys when using eSales Web API.
 */
class CustomerKeyAuthentication
{
    private $customerKey;
    private $token;

    /**
     * Creates a new instance that contains a personal customer key and a token, that can be used for
     * cross-device client-side notifications in eSales Web API. This object should be created
     * when the user has successfully logged in, and the respective values should be set in cookies.
     * See {@link getCustomerKey()} and {@link getToken()}.
     * @param $privateKey string A private key that is unique for this site. This key is provided by Apptus.
     * @param $user string The user name, or other user-unique value, of the customer that logged in.
     * @throws \InvalidArgumentException If privateKey or user is null or empty.
     */
    public function __construct($privateKey, $user)
    {
        $this->customerKey = hash('sha256', $user);
        $messageAuthentication = new MessageAuthentication($privateKey);
        $this->token = $messageAuthentication->sign($this->customerKey);
    }

    /**
     * @return string A hash based on a user specific value, such as user name.
     * This value should be stored in a cookie named "apptus.customerKey".
     */
    public function getCustomerKey()
    {
        return $this->customerKey;
    }

    /**
     * @return string The signature of this customerKey.
     * This value should be stored in a cookie named "apptus.token".
     */
    public function getToken()
    {
        return $this->token;
    }
}
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE