Authentication

Authentication is required for all Chartworks requests that involve data. Each product API requires an access token (obtained from the federation service) to be passed in the request. This token allows access to the APIs. Chartworks provides two options to authenticate and obtain a token. Please note that each token is specific to a single individual user; therefore each time you render or init a chartworks chart for an individual user they will need to have their own token. You cannot, for example, authenticate to obtain a token and then use this single token for multiple users.

All requests must occur over HTTPS. Non-secure requests will fail, as will API requests made without an access token.

Option 1: SAML 2.0

SAML (Security Assertion Markup Language) is an XML based standard that allows web domains to securely exchange user authentication and authorization data. Chartworks supports the exchange of SAML bearer assertions for access tokens.

Clients must first interact with an identity provider to authenticate the end user and obtain a SAML assertion. The assertion is then sent to the token URL endpoint. If authentication is successful an access token is returned in the JSON response. See the Step by Step guide for full details.

Simple Example

Firstly the client must obtain a valid base64 encoded SAML assertion from the identity provider.

Client then POSTs the assertion and other required parameters to the token endpoint URL:

POST https://sso.markitondemand.com/as/token.oauth2 HTTP/1.2
Content-Type: application/x-www-form-urlencoded
Host: sso.markitondemand.com
Content-Length: ...

grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&client_id=<CLIENTID>&scope=chartworks-html5%20chartworks-mobile%20chartworks-image&assertion=<ASSERTION>

Successful token endpoint response:

{
    "access_token": "KQrqWdCDdexi3Ry2vW0k0bmmvdlp",
    "token_type": "Bearer" 
}

Step by Step Guide

Step 1: Obtain assertion

Client must obtain a valid, digitally signed, base64 encoded SAML assertion from the identity provider. How this occurs is outside the scope of this guide.

The resulting assertion must conform to the guidelines laid out in RFC 7522.

Assertion Attributes

The SAML assertion must contain the following attributes:

Name	Value
Subject (NameID)	The assertion Subject must contain the unique username for the authenticated end user. If you are consuming real-time market data this username will be the identifier used in the monthly quote reports Chartworks sends you.
user_tier	The user tier value is provided to you by Chartworks once you purchase one of the charting products. The tier is used to define quote entitlements for your users. A standard setup is to have one tier for users that are entitled to real-time market data and a second tier for users that are only entitled to delayed market data. This way you can ensure users not entitled to real-time data cannot receive this data. Your organization can have up to 3 tiers. Defining these tiers will be handled during the setup. Tier(s) are unique to your organization.

Step 2: Post to Token Endpoint URL

The request should be posted to the token endpoint URL with a Content-Type of application/x-www-form-urlencoded. The request form must contain the following inputs and be sent over HTTPS:

Name	Value
grant_type	urn:ietf:params:oauth:grant-type:saml2-bearer
client_id	The client id provided to you by Chartworks once you purchase one of the charting products. The client id is unique to your organization.
scope	Space separated list of requested scopes. Scopes correspond to the Chartworks products you have purchased. See Scopes for available values.
assertion	Base64 encoded assertion obtained in Step 1

See Authentication Response for response details.

Next Steps

If you're ready to move ahead with SAML as your authentication method we'll need the following:

• Your X509 public signing key
• Your SAML entity/issuer ID

If you use a SAML framework that supports metadata XML exchange, you can just send us the metadata file and we can import the info right into our system. After we have the above we'll provide our info to you and we can start testing.

Option 2: Encrypted Auth String (AES)

Option 2 involves passing authentication parameters encrypted with 256-bit Advanced Encryption Standard (AES). To obtain an access token the client first encrypts the parameters defined below using a shared encryption key. The result is sent to the token endpoint URL. If authentication is successful the access token is returned in the JSON response. See the Step by Step guide for full details.

Simple Example

Firstly the client must generate a valid encrypted authentication string using the instructions provided below. Here is an example of the plaintext auth string with required parameters, before encryption:

user_id=joeUser&user_tier=exampleTier&user_timestamp=20160314133000

Example encrypted string with base64 and URL encoding applied:

29Q7Soy3b6Wlr2%2F5FV1TcuObVkmt%2Be%2F4Ntgpd4S4bbSy0MN%2BfbZcmJgKOA7Y3AHGRNJNgPGkj1uNVv25FWYWacvlSZpwsGux2N%2F5RMa8RFk%3D

Client then POSTs the auth string and other required parameters to the token endpoint:

POST https://sso.markitondemand.com/as/token.oauth2 HTTP/1.2
Content-Type: application/x-www-form-urlencoded
Host: sso.markitondemand.com
Content-Length: ...

grant_type=password&client_id=<CLIENT_ID>&validator_id=<VALIDATOR_ID>&scope=chartworks-html5%20chartworks-mobile%20chartworks-image&username=joeUser&password=29Q7Soy3b6Wlr2%2F5FV1TcuObVkmt%2Be%2F4Ntgpd4S4bbSy0MN%2BfbZcmJgKOA7Y3AHGRNJNgPGkj1uNVv25FWYWacvlSZpwsGux2N%2F5RMa8RFk%3D

Successful token endpoint response:

{
    "access_token": "KQrqWdCDdexi3Ry2vW0k0bmmvdlp",
    "token_type": "Bearer"
}

If you are using something like Postman to test this out your setup should look like the below. Note that some apps, like Postman, do the URL encoding for you so don't double encode your strings!

Step by Step Guide

Step 1: Build the authentication string

The authentication string should be built by concatenating the following fields with '&' as the separator:

Name	Value
user_id	The unique username for the authenticated end user. If you are consuming real-time market data this username will be the identifier used in the monthly quote reports Chartworks sends you.
user_tier	The user tier value is provided to you by Chartworks once you purchase one of the charting products. The tier is used to define quote entitlements for your users. A standard setup is to have one tier for users that are entitled to real-time market data and a second tier for users that are only entitled to delayed market data. This way you can ensure users not entitled to real-time data cannot receive this data. Your organization can have up to 3 tiers. Defining these tiers will be handled during the setup. Tier(s) are unique to your organization.
user_timestamp	UTC timestamp that indicates the moment in time the encryption string was created.

user_timestamp format is YYYYMMDDhhmmss where:

YYYY = four-digit year

MM = two-digit month (01=January, etc.)

DD = two-digit day of month (01 through 31)

hh = two digit hour in 24 hour format (00 through 23)

mm = two digit minute (00 through 59)

ss = two digit second (00 through 59)

Example

user_timestamp=20160314133000

Step 2: Encrypt the string

Take the inputs listed in Step 1 separated with ampersands to form the following plaintext string:

user_id=joeUser&user_tier=exampleTier&user_timestamp=20160314133000

Next take the string and encrypt it using the provided encryption key. Various libraries are available across multiple languages that handle AES 256 bit encryption. After encryption, base64 encode the result, and then URL encode. The final result should look something like this (actual result will differ with real encryption key):

29Q7Soy3b6Wlr2%2F5FV1TcuObVkmt%2Be%2F4Ntgpd4S4bbSy0MN%2BfbZcmJgKOA7Y3AHGRNJNgPGkj1uNVv25FWYWacvlSZpwsGux2N%2F5RMa8RFk%3D

This encrypted string will be valid for +/- 5 minutes from the user_timestamp provided. This means you must call the token endpoint URL (next step) within +/- 5 minutes of the user_timestamp for it to be accepted.

Step 3: Post to Token Endpoint URL

The request should be posted to the token endpoint URL with a Content-Type of application/x-www-form-urlencoded. The request form must contain the following inputs and be sent over HTTPS:

Name	Value
grant_type	password
client_id	The client id provided to you by Chartworks once you purchase one of the charting products. The client id is unique to your organization.
validator_id	If you are using AES for authentication you will also be provided a validator id, which you must pass here.
scope	Space separated list of requested scopes. Scopes correspond to the Chartworks products you have purchased. See Scopes for available values.
username	Plaintext username. This must match the user_id field passed inside the encrypted auth string payload.
password	The full encrypted and encoded auth string obtained in Step 2.

See Authentication Response for response details.

Scopes

The request must include a scope parameter containing a space-delimited list of requested scopes as per RFC 6749. For Chartworks, the available scopes correspond to the different Chartworks product offerings. Here are the available values:

Scope	Description
chartworks-html5	HTML5 charts
chartworks-mobile	iOS/Android charts
chartworks-image	Image charts

If a scope is requested for a Chartworks product which has not been purchased, an error will be returned. If an API request is made for a product using a token which does not include the corresponding scope, an error will be returned.

The scope parameter must be included on all token requests.

Authentication Response

Success

If validation was successful using either of the above options, the API will send a JSON response, for example:

{
    "access_token": "KQrqWdCDdexi3Ry2vW0k0bmmvdlp",
    "token_type": "Bearer"
}

The JSON response contains the following properties:

access_token string

Access token to be passed into the Chartworks products.

token_type string

Type of access token. Currently this will always be Bearer.

Errors

If authentication is not successful the token endpoint will respond with the appropriate HTTP status code. The response body may contain additional information about the failure.

Token Duration

Once authenticated the access token is good for 120 minutes unless it is revoked earlier. Each of the Chartworks products will return an error when an access token is rejected due to timeout. See individual product documentation on how this is handled.