Partner – Aprimo DM SSO Technical Detail

There are two methods for invoking the Aprimo DM SSO Endpoint – GET and POST. Use the HTTP GET endpoint if you do not need to pre-fill out the registration form. POST will allow you to perform the same request but pre-fill out the registration form (and bypassing it entirely if necessary).

In order to implement Aprimo DM SSO, query string parameters must be passed to an endpoint via HTTP GET.
A sample URL may look like:

https://subdomain.aprimodm.com/SSO/RevenewSSO.aspx?email=tchawla@aprimo.com&nonce=13&source=MyCompanyName&code=b0d45be0d6b46295708f0c046f02e45f1078e0fbcd36018fa3a0f8d1f5b8624d&language=en-us

Email,the email address of the user who is attempting the login when using email as the unique identifier for Aprimo DM.

Id,an external unique identifier of the user who is attempting the login when using an external unique identifier.
Note that only one of the two (email or id) should be passed in the query string.

Source, a unique identifier for your brand provided by Aprimo DM.

Nonce, a number used only once that must be a positive integer that increments each time a call is made for a particular user. The nonce is tracked per user, so the same number may be used for different users, but only once per user. Note the below examples of when a nonce is valid or invalid. The nonce prevents HTTP replay attacks.

Table 1: Table with examples of valid and invalid nonce values.

Code, a calculated HMAC using the SHA256 algorithm using a key that Aprimo DM provides. This serves to validate that the request is coming from the source that it claims to be as well as prevents query string tampering. While the parameters which calculate the HMAC are case sensitive, the resulting value (a string of hex values) is not.

If email is used as the unique identifier, the code may be formed by concatenating the email, source, and nonce parameter values with no spaces or characters between and running the resulting value through a SHA256 hash code function.

If id is used as the unique identifier, the code may be formed by concatenating the id, source and nonce parameter values with no spaces or characters between and running the resulting value through a SHA256 hash code function.

Language, a value that sets the user’s language in the application. This is an optional parameter and will default to english if not supplied. Values allowed are:

Gets a list of all partners that are connected to you. This includes precision connect and partner attribute data.

POST Body
If electing to use HTTP Post, the following parameters may be passed in and defaulted on the form.

Below is some sample C# code used to generate a sample URL for Aprimo DM SSO’s GET endpoint.
Running this code produces the sample URL.

https://mysubdomain.aprimodm.com/SSO/Revenew.aspxemail=tchawla@aprimo.com&nonce=30&source=SourceVal&code=B97E50D79ACF75282FEC67DD1182DCA0981C9EC6B9000C2AEE4EC23EC0282C46

using System;
using System.Text;
using System.Security.Cryptography;
namespace AprimoDMSSOSample
{
class Program
{
static void Main(string[] args)
{
// Input Values
string subdomain = "mysubdomain";
string source = "SourceVal";
string nonce = "30";
string email = "tchawla@aprimo.com";
string key = "MyAprimoDMProvidedKey";
string URL = URLGen(subdomain, source, nonce, email, key);
}
///
/// Generates the URL to redirect a user to in order to invoke Aprimo DM SSO.
///
///The source value agreed upon by Aprimo DM. ///Must increment with each request. ///The email address of the user. ///The key value provided by Aprimo DM. /// 
public static string URLGen(
string subdomain, string source, string nonce, string email, string key)
{
// Create a new variable that will hold the URL as it is built.
StringBuilder sb = new StringBuilder("https://");
sb.Append(subdomain);
sb.Append(".aprimodm.com/SSO/RevenewSSO.aspx");
// Append the email address of the user as a query string parameter.
sb.Append("?email=" + email);
// Append the nonce query string parameter.
sb.Append("&nonce=" + nonce);
// Append the source query string parameter.
sb.Append("&source=" + source);
// Calculate the HMAC using email + source + nonce as the message.
string HMAC = CalcuateSHA256HMAC(email + source + nonce, key);
// Append the code query string parameter.
sb.Append("&code=" + HMAC);
// Return the built URL.
return sb.ToString();
}
///
/// Calculates the HMAC using the SHA256 algorithm.
///
///The concatenated email+source+nonce value.
///The key value provided by Aprimo DM. /// The generated HMAC as a string in hex
public static string CalcuateSHA256HMAC(string message, string key)
{
// Set the encoding to work with.
var encoding = new System.Text.UTF8Encoding();
// Convert the string key to a UTF8 byte array.
var keyBytes = encoding.GetBytes(key);
// Create a new HMACSHA256 object and set the key to use.
HMACSHA256 hmacsha256 = new HMACSHA256(keyBytes);
// Convert the value to hash (email+source+nonce) to a UTF-8 byte array.
byte[] messageBytes = encoding.GetBytes(message);
// Calculate the hash code.
var hashmessage = hmacsha256.ComputeHash(messageBytes);
// Covert the byte array to a hex string, removing the -'s.
return BitConverter.ToString(hashmessage).Replace("-", string.Empty);
}
}
}

If writing your HMAC calculation in another programming language, you can leverage the Aprimo DM SSO Sample to validate that your HMAC is calculating properly.
If writing your HMAC calculation in javascript, you may view source on the Aprimo DM SSO Sample to see how it is calculated.

The Aprimo DM SSO Sample is available at: http://revvideo.azurewebsites.net/AprimoDMSSOSample.html.
This generates a GET request.
Below is a screenshot of the SSO sample page.
This sample is written entirely in client-side code. You may view source on the sample page to see the javascript used to generate the request and HMAC. Note that the crypto-js library is used to generate the HMAC in this example which has its own 3rd party license.

Note that the test bench URL field will be a generated URL that pre-populates the source, nonce, email, key, and subdomain fields on the page with your input. This makes it easy to store your test values in a bookmarked URL. Note though that the nonce will need to be changed for each successful request.