CQG OAuth 2.0 Documentation

Introduction

This document covers developer's documentation for CQG ID endpoints usage by app. CQG ID endpoints implements authentication and authorization with the industry standard protocol OAuth 2.0. It supports only explicit authorization flow with PKCE.

Related Documents

1. OAuth 2.0 Specifications: https://tools.ietf.org/html/rfc6749
2. OAuth for native apps: https://tools.ietf.org/html/rfc8252
3. Proof key for code exchange: https://tools.ietf.org/html/rfc7636
4. Code example of native app on windows: https://github.com/googlesamples/oauth-apps-for-windows

The basics

App registration

You must register application that uses the CQG ID endpoints by contacting CQG directly. The app registration process collects and assigns special values for your app.

At first you need to provide these values to CQG:

• Application name. This name will be shown on Authorization endpoint page during user's logon process. Can be omitted. In this case no application name will be shown.
• A Redirect URI (reply URL) that will be used by Authorization endpoint to provide authorization code and redirect user once your app successfully authorized.
• Application type: spa (browser single page application), native or webapp (server rendered web application).
• Whether refresh tokens functionality is needed.

Then CQG will provide unique values which identifies your app:

• A Client ID that uniquely identifies your app.
• Client secret (application password) which is used for authorization code exchange. For webapp application type only. Client Secret must be kept securely.

Redirect URI

Redirect URI must start with https. Example: https://yourcompany.com/auth.

For loopback technique, when native app listens for response on local server, http://127.0.0.1/ {specialAppPath} should be used.

Endpoints

CQG ID provides two endpoints for authorization flow:

1. User authorization endpoint: https://login.cqg.com/oauth/v2/auth - endpoint for user sign in with credentials and providing access to resource for application with authorization code on behalf of this user
2. Token endpoint: https://aserv.cqgone.com/oauth/v2/token - endpoint for retrieving access token to resource from authorization code or refresh token.

For testing and development purposes the following ones should be used:

1. https://uatlogin.cqg.com/oauth/v2/auth
2. https://uataserv.cqg.com/oauth/v2/token

Authorization flow

Native app flow

Basically, authorization flow contains the following steps:

1. Request an authorization code:
   • After startup, native application opens browser with CQG User authorization endpoint with required query parameters.
   • Application starts to listen on (redirect URI) loopback IP for HTTP request with user authorization result, containing authorization code or error.
   • After user's successful sign on, CQG User authorization endpoint will answer to redirect URI with authorization code.
2. Request an access token:
   • Application gets authorization code and does POST request to CQG Token endpoint with required parameters in order to exchange code to access token and optionally refresh token.
   • Token endpoint answers with access token and optional refresh token.
3. Use the access token:
   • Application opens connection with desired CQG API with given access token.
4. Refresh the access token:
   • If alive refresh token exists, access token already used and application needs to open connection with CQG API again, it does POST request to CQG Token endpoint with refresh token and required parameters.
   • Token endpoint answers with new access token and new refresh token.

Single page app flow

Single page application is executed only in browser. The flow is almost the same, with the differences only in:

1. Request an authorization code:
   • After startup or by user action, SPA application redirects to CQG User authorization endpoint with required query parameters.
   • After user's successful sign on, CQG User authorization endpoint redirects user back to redirect URI (SPA) with authorization code.

Next steps are the same with the only difference, they are executed right in the browser.

Web app flow

The flow is almost the same, with the only difference that web application isn't fully executed in browser, web app server renders pages and do redirect requests for browser.

Also, it does communication with Token Server and API on its side, in secure environment, so client secret can be used here.

Detailed flow

Request an authorization code

In order to authenticate/authorize user with our sign-in form, CQG User authorization endpoint must be opened in browser with the following required query parameters:

Example:

https://login.cqg.com/oauth/v2/auth?

client_id=23dfeab-23d7-80be-79bc-sadg343df3fe

&client_version=2.0

&response_type=code

&redirect_uri=http%3A%2F%2F127.0.0.1%3A3453%2Fcode

&scope=wss%3A%2F%2Fapi.cqg.com+offline_access

&code_challenge=GSDFrer334OWYzMzA3MTIAGdgsgASFNmVjNDE5YmEyZGRSGfasfdmZ2342MTQ1dgasdg3NDcxY2Nl

&code_challenge_method=S256

&state=12345

Successful response

CQG User authorization endpoint will respond to this address via GET method with this query parameters:

Example:

GET https://127.0.0.1/code?

code=fsASDfgsdFsdgssdGHBsadhfdhGuNHSUYBrq

&state=12345

Error response

In case of error endpoint will respond with the following parameters to redirect_uri:

The following error codes can be returned:

In case of redirect_uri or/and cliend_id is invalid, error will be shown only in browser.

Request an access token

In order to exchange an authorization code for an access token, do POST request to CQG Token endpoint with the following parameters:

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

Example:

POST /token HTTP/1.1

Host: https://aserv.cqgone.com/oauth/v2

Content-Type: application/x-www-form-urlencoded

client_id=32523523324234

&code=fsASDfgsdFsdgssdGHBsadhfdhGuNHSUYBrq

&client_secret=ASFfefdf32432LFfjssdf&gsagGDSGsdgdsfdsfsdgSGD3wtwt23gGDSGsgsdgsd

&redirect_uri=http%3A%2F%2F127.0.0.1%3A3453%2Fcode

&grant_type=authorization_code

&code_verifier=GAGkFdsafdnsfjdsfFGAewgewgew

Successful response

Server will respond with JSON and following parameters:

Example:

{

"access_token": "LKHKLHsafHFDMBMNOWQBdfsd34234UzI1NiIsgsagg53252Znl0aEV1Q...",

"token_type": "Bearer",

"expires_in": 3599,

"scope": "wss%3A%2F%2Fapi.cqg.com

"refresh_token": "BwBBAAvPM1KaPlrEqGsfdsafGUT235sdGQWR4B5...",

"refresh_token_expires_in": 86400

}

Then client app can access requested resource with provided access token.

Error response

The following errors can be returned:

Refresh the access token

Access tokens are short lived, you need to refresh them after they expire to access resources again.

In order to exchange refresh token for an access token, do POST to token endpoint with the following parameters:

Successful response

Server will respond with JSON and following parameters:

Parameter Description access_token Access token for requested scope. expires_in Lifetime of token in seconds. scope Given resources. refresh_token New refresh token in order to retrieve access token. Previous used refresh token is automatically expired and can't be used twice. refresh_token_expires_in Lifetime of refresh token in seconds. token_type "Bearer" value.

Error response

See error response for initial access token acquire step.