Metamarkets Support Documentation

Embedding the Metamarkets Dashboard

The Metamarkets dashboard can be embedded into you own web application using an iFrame, a standard HTML element, and authenticated using our built-in support for single-sign-on (SSO) login.
Security is accomplished with a one-way hash using the secret key provided in the Metamarkets account administration page for SSO support.

Embedding the Dashboard

To embed the Metamarkets Dashboard into your web application, you simply need to place a SSO-authenticated iFrame into a HTML body of your application. Shown below is an example of the iFrame element for embedding the Metamarkets dashboard:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Metamarkets iFrame Sample</title>
</head>
<body>
<h1>Metamarkets iFrame Sample</h1>
<iframe src="http://dash.metamarkets.com/sso/v1/login? ?firstName=John&lastName=Doe&email=demo%40metamarkets.com&timestamp=1404419294&companyId=16&securityPolicyIds=518 &verifyHash=<SOME VERIFY HASH>&path=explore"  height="800" width="1200" seamless="seamless"></iframe>
</body>
</html>

Single-Sign-On Authentication for the iFrame Element

To enable seamless integration with your application, we've built-in a SSO authentication mechanism for establishing user identity within the iFrame element, without requiring the user to explicitly login into Metamarkets.

Specifically, we require the iFrame src field to point to our SSO login end-point with the following URL parameters:

´╗┐Parameter Required Description
firstName Yes First name of the user's account in the dashboard. Ex Jane
lastName Yes Last name of the user's account in the dashboard. Ex Smith
email Yes Email address of the user's account in the dashboard. Ex jsmith@example.com
companyId Yes A identification number for your company issued by your Metamarkets representative. Ex 123
securityPolicyIds Yes Comma-separated list of security policy ids to assign the user. At least one ID is required. Security-policy IDs are found in the Metamarkets dashboard. Ex. 518,519,520
timestamp Yes The current timestamp value in seconds (GMT/UTC format). Ex. 1358035200
verifyHash Yes The MD5 hash of the secret key and the parameters listed above. Ex. b6036eb9f947695c46c9f4aee11be0b9
path No The path to the view that will be displayed once the embedded dashboard loads. Ex. explore

NOTE:

email addresses (and any other strings containing characters unsafe for URLs) must be made URL safe by encoding them appropriately. The script examples below show how these strings are URL encoded.

verifyHash is a MD5 hex hash, generated based on the values of the other URL parameters and your account's SSO Secret Key.

Obtaining the SSO Secret Key

The Secret Key is the core authentication token to ensure a secure connection between your application and the Metamarkets dashboard, and should be kept confidential.

Initially, you must contact your Metamarkets representative to generate the first secret key.

If the key's privacy is compromised, you can always reset a new Secret Key:

  1. Log into your dashboard with an administrator account.
  2. Go to the admin screens and choose Single Sign On from the left-hand sidebar menu.
  3. Click Reset secret key. This causes a new secret key to be generated.
  4. Double-click the key in the Current secret key field to select it, then copy the key.

Store the key in a safe place.

Example

Expanding on our sample above, below is a complete example of embedding the Metamarkets dashboard into any HTML webpage.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Metamarkets iFrame Sample</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1/core.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.9-1/md5.js"></script>
</head>
<body>
<h1>Metamarkets iFrame Sample</h1>
<div id="mmx_dash"></div>


<script type="text/javascript">
var generateHash = function(email, firstName, lastName, companyId, securityPolicyIds, secretKey, timestamp) {
    var stringToHash = firstName + '|' + lastName + '|' + email + '|' +
        companyId + '|' + securityPolicyIds + '|' + timestamp + '|' + secretKey
    var verify = CryptoJS.MD5(stringToHash).toString();
    return verify;
}
$(document).ready(function() {
    var firstName = "Jane";
    var lastName = "Smith";
    var email = "jsmith@example.com";
    var companyId = '123';
    var securityPolicyIds = "518,519,520";
    var secretKey = "423d004c716839b4af16ef680cc742f2";
    var timestamp = Math.floor(Date.now() / 1000);
    var verifyHash = generateHash(email, firstName, lastName, companyId, securityPolicyIds, secretKey, timestamp);
    var sso_src = "https://sso.metamarkets.com/sso/v1/login?" +
        'firstName=' + encodeURIComponent(firstName) + '&' +
        'lastName=' + encodeURIComponent(lastName) + '&' +
        'email=' + encodeURIComponent(email) + '&' +
        'companyId=' + companyId + '&' +
        'securityPolicyIds=' + securityPolicyIds + '&' +
        'timestamp=' + timestamp + '&' +
        'verifyHash=' + verifyHash + '&' +
        'path=explore';

    $("div#mmx_dash").html("<iframe src='" + sso_src + "' height='800' width='1200' seamless='seamless'></iframe>");
});
</script>

  </body>
</html>

Creating New Users

The current version of the Metamarkets dashboard SSO framework (v1) supports creation of new user accounts. If a user authenticated via SSO does not exist, a Metamarkets account is created for the user based on the information provided in the authenticated iFrame.
Accounts must have unique email addresses. If the provided email address is already associated with a Metamarkets account, it is assumed to belong to the connecting user.

Working With Security Policies

Each iFrame URL must specify one or more security policies IDs to assign to the account specified in the URL. Security Policies need to be created by the account administrator first, before they can be accessed in the iFrame.

In the SSO URL, you must list the numerical IDs of the policies, not their names. Use the Metamarkets dashboard to find the IDs in the security-policies administration pages.

Embedding the Metamarkets Dashboard


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.