Apidapter Authenticated Messaging Protocol

This article provides details on Apidapter's authenticated messaging protocol. This general-purpose protocol was designed by Apidapter to provide powerful, flexible, and secure integration end-points. It is often utilized to support single sign-on (SSO), in-house web apps, commercial solutions, and other custom integrations. 

Request Construction

A specially crafted GET or POST request contains information that Apidapter uses to determine if the request is genuine and valid. A secret string must be shared between the third-party system and Apidapter. The following parameters are required: 

• timestamp: The current UNIX timestamp in seconds.
• hmac: HMAC-256 digest of concatenation of all parameters in alphabetized parameter name order, using the shared secret as the key.

Any number of other parameters can be specified. Adapters may make use of any additional parameters as necessary. In practice, additional parameters such as a user identifier and a context identifier must be included for the adapter result to have meaning in an endpoint system.

HMAC Calculation

The 'hmac' parameter is calculated by:

1. Alphabetizing parameter names (including custom parameters).
2. Concatenating parameters in order of alphabetized names.
3. Calculating the HMAC-256 digest of the resulting string using the shared secret as the key.

For example, with a shared secret of "purple_bananas" and the following parameters:

• user_id = [e-mail]
• timestamp = 1306956316
• random = K8hd38
• custom_param1 = 78

The alphabetized parameter names are:

custom_param1, random, timestamp, user_id

The concatenated parameters:

[e-mail]

HMAC-256 digest:

fc0f080db8e836e36929d51f691972975569d3f938a8c107ed106014ee0b9163

Best Practice

• Include variable-length URL-safe strings of random characters as in the above example

Sample Code

In the following pseudocode, the italicized portions are customer-dependent. For example, user_id may come from a GET or POST request while internal_authentication_successful() may query an LDAP or Active Directory server.

  string user_id = user_id;
  string timestamp = (string) time();
  string random = get_random_string();
  string secret = shared_secret;

  if (internal_authentication_successful()) {
      string url = "https://<adapter_url>?" +
         "random=" + random +
         "&timestamp=" + timestamp +
         "&user_id=" + user_id +
         "&hmac=" + hmac_256(random + timestamp + user_id, secret));
 
      redirect_to(url);
  }