Introduction
Partner token authentication allows seamless authentication in CQG Desktop web application.
Definition of terms
| JWT | JSON Web Tokens, open, industry standard RFC 7519 (https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties, https://jwt.io/. A JWT is represented as a sequence of URL-safe parts separated by period ('.') characters. Each part contains a base64url-encoded value. |
| CWAS | CQG WebAPI Server is a product that provides an easy to use interface for CQG Desktop and Mobile clients as well as for 3rd party applications to realtime market data, historical data, symbol resolution and trading capabilities of CQGs existing systems. |
| CQG Auth Server | Server that authenticates user by various means: login/password, one-time password, refresh token, partner token. |
| CQGDESKTOP | CQG Desktop, web-based single-page-application that allows receiving real-time market data and place orders. |
Operating principal
Signed tokens can verify the integrity of the claims contained within it, while encrypted tokens hide those claims from other parties. For partner token authentication we shall use signed tokens.
To setup partner token authentication a partner shall:
- Use encryption algorithm RS256 (RSA encryption + SHA256 hash).
- Generate public/private key pair (private key must be kept in safe place) or can use existing. Note: you can generate several key-pairs. Having multiple keys allows key rotation (gradual replacing soon-to-expire certificate with new one).
- Provide public key(s) (certificates) to CQG.
- Verify iss (token issuer, partner identifier) claim value with CQG (CQG will check it for collision with other registered partners).
CQG will provide you CQGDESKTOPesktop base url for integration.
Partner shall generate token according to https://jwt.io/ rules and shall specify the following claims:
- sub — (registered claim name) partner user name
- exp — (registered claim name) expiration time on or after which the JWT must not be accepted for processing, numeric, unix time seconds.
- iss — (registered claim name) issuer claim value verified by CQG, string.
When partner token is ready, partner app shall build URL that will be used to navigate to CQGDESKTOPesktop website. URL shall have format
https://m.cqg.com/{brand-name}/desktop/main?partnerToken={partner-token}When navigated to that URL CQGDESKTOP application shall extract partner token from query string, send it to CQG Auth Server, receive access token and using it, will establish connection with CQG WebAPI Server.
Example
Partner Some Partner, having SomePartnerApp, wants to implement JWT-based authentication with CQG (launch CQGDESKTOP from SomePartnerApp seamlessly). It generates public/private key-pair. E.g.
Private key -----BEGIN RSA PRIVATE KEY----- MIICXAIBAAKBgQC9PYMDsIFdSBwLuyhSjK7Htx3W+SNcMZUCkk+7aLHVQWrhuwRn jghxs8gnvecMxi3RaPjF/0lHrwey4KPSjXLrzz5VQ5cq40KGWkIQg6vqr+T7LMQW zcrnJpawUAmsXizks47yLO5Uz36TIeDi/gnrL6vQRvK3F8PDugkmo/FkQQIDAQAB AoGBALxh94I8uwr5NbIX5dQHaBY4G+Rcru6gDQ46SFTvq9f2/0cmvQO5SH6n0aB+ UvtMbWABd2Ti9Tf+7VMMfQik9rg+5SnLs7P+yPhn0v1/EJKO/kQYJ3seWqQCWc45 tIJE2oC/TUhTPxGcUMmqTVGiE5RoTgfC/IWxbq58BYLrlb7hAkEA9jUygfAGjTsA 7HiiXyDUUoRR+G/pU15cR3pLAS9YyXpwPzqSgVcfBhLMpyb0KenUq0uuxrUpOSan AMQzClrHcwJBAMTESnay+lL3AyZbcaaLVQZDG/KUlKvn/0CvZrT1pzQF51dc2dhT irA0OEMyvpTx0onkEf1J22pSRkacYb/aMHsCQHwdyT5zz/m2evq6vbATDrYiemgx koAym3Z1Egag5bN8A8X8Mwr87mjTZVQGcSQH+uv3lT4a6ZMkByB9x/U6Wj0CQCgo 6AnR/cVxJPNvNoMHbRMaH1ojeTSc5TwOkKfee4HispTiHpRIeMX94n3UnZFIye/a 3NEVgfLxV+aRhGHj5oECQCFhlpPWps2RBiW38GkZfimqQB7pjb/OXnoCnoAgfiOw SOcH1aXYbXVLJjAUPG8NP34ou58AtIHaUIi82OVQ16o= -----END RSA PRIVATE KEY----- Public key -----BEGIN PUBLIC KEY----- MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC9PYMDsIFdSBwLuyhSjK7Htx3W +SNcMZUCkk+7aLHVQWrhuwRnjghxs8gnvecMxi3RaPjF/0lHrwey4KPSjXLrzz5V Q5cq40KGWkIQg6vqr+T7LMQWzcrnJpawUAmsXizks47yLO5Uz36TIeDi/gnrL6vQ RvK3F8PDugkmo/FkQQIDAQAB -----END PUBLIC KEY-----
Then partner sends public key to CQG. CQG registers this public key in CMS/GW, allows partner users to be authenticated by partner JWT, assigns issuer-id, that would be e.g. caus—some-fcm, choose brand-name for partner, that would be e.g. somebrand (separate brand allows customization of CQGDESKTOP), and sends these values to the partner. Partner will use these values during JWT generation (iss claim value) and url building.
After that partner can start generating JWT-s.
Let's assume we want to authenticate user with partner user name someuser. JWT header shall be
{
"alg": "RS256",
"typ": "JWT"
}
JWT payload data shall be
{
"sub": "someuser",
"exp": 1516239022,
"iss": "caus--some-partner"
}
sub — contains partner user name, exp — token expiration time, numeric, unix time, number of seconds since 1970 representing UTC time, iss — token issuer-id that was assigned/verified by CQG. To generate JWT manually in testing purposes you can go to https://jwt.io/#debugger, select RS256 algorithm, paste JWT payload data, paste private key. Web page will generate JWT for you, for the example data above that would be
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21ldXNlciIsImV4cCI6MTUxNjIzOTAyMiwiaXNzIjoiY2F1cy0tc29tZS1wYXJ0bmVyIn0.aOLyxjzY7BRugwosgAHyY8pY9Ml6bjjsYcTiKDhIAgUN1EpKsaPoY01Q3yruESJ8lUOgTjCsDBlOpVsf2bhVHTYWvK72ZrgzGn5zHqNqN82of3DwOwePA8H44haVzPVSb1vDTc7--9Ah-d97NPxw_fqAl9og3lWq2h3Qy7geLyQ
SomePartnerApp builds url and opens it in browser window. No need to encode JWT additionally. It is already URL-safe. URL will be
https://m.cqg.com/somebrand/desktop/main?partnerToken=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21ldXNlciIsImV4cCI6MTUxNjIzOTAyMiwiaXNzIjoiY2F1cy0tc29tZS1wYXJ0bmVyIn0.aOLyxjzY7BRugwosgAHyY8pY9Ml6bjjsYcTiKDhIAgUN1EpKsaPoY01Q3yruESJ8lUOgTjCsDBlOpVsf2bhVHTYWvK72ZrgzGn5zHqNqN82of3DwOwePA8H44haVzPVSb1vDTc7--9Ah-d97NPxw_fqAl9og3lWq2h3Qy7geLyQ
After that CQGDESKTOP will be loaded and it will open session for someuser login. Internally CQGDESKTOP connects to CQG Auth Server, provides partner token, receives access token, and connects to CWAS using provided access token.
Sequence diagram
The above can be illustrated with the following sequence diagram
