QLM strict authentication for HTTP Methods

Overview

QLM HTTP methods typically use basic authentication (user/password) to validate the authenticity of a request. You can enhance the security of these methods by enabling strict authentication for some methods. Strict authentication requires that a client computes a hash of a given payload (including a secret key) and sends the hash value in the HTTP headers. When the server receives the request, it verifies that the hash is valid before authorizing it.

By default, the RetrieveActivationKeyHttp method requires strict authentication. You can configure which HTTP method requires strict authentication by setting the server properly "security/strictAuthenticationHttpMethods".

The following sections detail how to invoke HTTP methods that require strict authentication.

Configure Authentication Settings

There are 2 levels of authentication required to support QLM strict authentication:

• You must configure a user/pwd

• You must configure an API key used to compute a hash that will be verified on the server

To configure these settings:

• Launch the QLM Management Console

• Go to the Manage Keys tab

• Click 3rd party extensions

• Select a 3rd party extension

  • Set a user and password

  • Set an API Key (like a password, specify a string of characters)

  • Click Ok

In your application, you must dynamically computer the hash and add it to the header of the request as per the instructions below:

• Compute a SHA256 hash of the URL you are invoking, including all arguments, the timestamp value., and the authentication version. Example: http://localhost:55555/qlmservice.asmx/RetrieveActivationKeyHttp?is_orderid=1234&is_userdata1=99999&is_user=ralph&is_pwd=123456&is_format=json&X-Qlm-Timestamp:2023-10-30 23:59:00&X-Qlm-Authentication-Version=2

• Add the value of the hash in a custom header called X-Qlm-Authentication

• Add another custom header, X-Qlm-Timestamp, that contains the current UTC date/time in the following format: yyyy-MM-dd HH:mm:ss. The request will only be honored if it reaches the destination within a specified timeframe from the provided time stamp. The value of the allowed time difference (in seconds) can be configured via the server property security/strictAuthenticationTimestampTolerance.

• Add another custom header, X-Qlm-Authentication-Version, to specify the version of the authentication algorithm. The latest version is 2. You can specify the minimum version allowed by setting the server property security/strictAuthenticationMinimumVersion.

• You can optionally add additional headers that can be used in the evaluation of the hash. The additional headers must start with the "X-Qlm" prefix. These headers are appended to the URL and separated with colons. For example, if you create a header called X-QlmData with the value "my_data", the hash is computed based on the value of: URL (including arguments) + "&X-QlmData:my_data"

C# Example of computing the hash in your application

string url = "";

string apiKey = "123456";
int authenticationVersion = 2;

string timestamp = DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss");
string data = url;
data += "&X-Qlm-Timestamp:" + timestamp;
data += "&X-Qlm-Authentication-Version:" + authenticationVersion;
string hashValue = CalcHMACSHA256Hash(data, apiKey);

HttpWebRequest webReq = (HttpWebRequest)WebRequest.Create(url);
IWebProxy iwp = WebRequest.DefaultWebProxy;
webReq.Credentials = CredentialCache.DefaultCredentials;
webReq.Headers.Add("X-Qlm-Authentication-Token", hashValue);
webReq.Headers.Add("X-Qlm-Timestamp", timestamp);
webReq.Headers.Add("X-Qlm-Authentication-Version", "2");

HttpWebResponse webResponse = (HttpWebResponse)webReq.GetResponse();
if (webResponse != null)
{
    StreamReader sr = new StreamReader(webResponse.GetResponseStream(), Encoding.UTF8);
    //Convert the stream to a string
    response = sr.ReadToEnd();
    sr.Close();
}

// Helper Functions
public static string CalcHMACSHA256Hash(string message, string sharedKey)
{
 var hmac = new HMACSHA256(Encoding.ASCII.GetBytes(sharedKey));
 byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
 return string.Join("", hash.ToList().Select(b => b.ToString("x2")).ToArray());
 }

Example using Curl to invoke an HTTP method

You can use curl to test the authentication of the HTTP method. In the example below, we will use curl to invoke the RetrieveActivationKeyHttp method.

Curl -H"Qlm-Authentication-Token:1c72d8e817623b87d9f804b0d6c28ee4e26d1a55fed564a9fa5c8099c40fbeb2" -H"Qlm-Timestamp:2020-07-16 13:15:00" "
http://localhost:55555/qlmservice.asmx/RetrieveActivationKeyHttp?is_orderid=1234&is_userdata1=99999&is_user=ralph&is_pwd=123456&is_format=json
"

Testing your hash value

There are many online tools that you can use an online tool to test your hash value.

For example, you can use this tool as shown below:

• Copy/paste your URL in the tool: http://localhost:55555/qlmservice.asmx/RetrieveActivationKeyHttp?is_orderid=1234&is_userdata1=99999&is_user=ralph&is_pwd=123456&is_format=json

• Enter the API key (from Manage Keys / 3rd party extensions) in the Secret Key field

• Select SHA 256

• Click Computer HMAC

mceclip0.png