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.
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:
<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×tamp=1404419294&companyId=16&securityPolicyIds=518 &verifyHash=<SOME VERIFY HASH>&path=explore" height="800" width="1200" seamless="seamless"></iframe> </body> </html>
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:
|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|
|Yes||Email address of the user's account in the dashboard. Ex firstname.lastname@example.org|
|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|
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.
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:
- Log into your dashboard with an administrator account.
- Go to the admin screens and choose Single Sign On from the left-hand sidebar menu.
- Click Reset secret key. This causes a new secret key to be generated.
- Double-click the key in the Current secret key field to select it, then copy the key.
Store the key in a safe place.
Expanding on our sample above, below is a complete example of embedding the Metamarkets dashboard into any HTML webpage.
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.
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.