Article

OAuth grant types in Refinitiv Data Platform

Gurpreet Bal
Platform Application Developer Platform Application Developer

Introduction

Refinitiv Data Platform (RDP) is a cloud based service, to provide unified access to Refinitiv content and services. RDP provides a single point of API-driven content and is backed by standard authentication and entitlements. The requested data is delivered through a delivery mechanism, which is best suited for that particular data set. In this article we briefly look at OAuth authentication mechanisms supported by RDP, and which one is a best fit for a given application.

OAuth Grant types

OAuth 2.0 specification specifies following grant types:

  • Password
  • Refresh Token
  • Authorization Code
  • Implicit
  • Client Credentials
  • Device Code

A summary of these grant types is:

Grant Type

Description

Supported by RDP

Password

An application provides a user name and password combination to get a token.

Yes

Refresh Token

An application uses a token to get a new token

Yes

Authorization Code

An application gets a code in response to direct user authentication, which can be exchanged for a token.

Yes

Implicit

An application directly gets a token in response to direct user authentication.

Yes

Client Credentials

A fixed secret pass-phrase is used to get a token. It is suitable for machine-to-machine authentication.

Yes, Authentication v2

Device Code

An input constrained device gets a code as a result of authentication from another device. The code can then be exchanged for a token.

No

Here:

Token refers to an opaque string which is required to access protected resource - for e.g. invoking a REST API call to get ESG data.

Code refers to an opaque string which can not be directly used to get data.

Use

Password Grant

Getting an Access token by providing a username and password is the simplest means of authentication. An application sends in a HTTP-POST request message to the authorization service. This request message must contain a preregistered application ID, which is encoded and carried in the Authorization header of POST message. The authorization service responds to successful login by providing a valid Access and Refresh tokens. Password grant type is typically used in applications, in which a user directly types in a username/password combination into the application before requesting data.

 

 

Here is an example of a password grant interaction:

    	
            

POST https://api.refinitiv.com/auth/oauth2/beta1/token HTTP/1.1

Host: api.refinitiv.com

User-Agent: python-requests/2.14.2

Accept-Encoding: gzip, deflate

Accept: application/json

Connection: keep-alive

Content-Length: 112

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

Authorization: Basic RDZEN****Q3NDo=

 

username=****&password=****&grant_type=password&scope=trapi

 

 

HTTP/1.1 200 OK

Date: Mon, 29 Jul 2019 12:54:23 GMT

Content-Type: application/json

Connection: keep-alive

X-Amzn-Trace-Id: Root=1-5d3eec7c-4119aa4af2855b8723fe4b77

X-Tr-Requestid: 6e80898a-72f7-4425-bfd4-36fa228d5825

Content-Length: 5535

 

{

"access_token": "eyJ0e****effg",

"refresh_token": "****-def6-47b3-aeb2-1468796846b5",

"expires_in": "300",

"scope": "trapi.admin.accounts",

"token_type": "Bearer"

}

Use: A Password grant is used in standalone server type applications, where the client application and the device can be trusted with credentials. An example is a Java or Python based server application getting ESG data and performing custom analytics and storing it to a database.

Refresh Grant

A refresh grant is almost always used in every workflow, once the primary means of getting a code or initial token is resolved. An application can initially use any of the available grant types to get an Access and Refresh tokens. Subsequently, whenever Access token expires, the long lived Refresh token can be used with refresh grant to get a new set of Access and Refresh tokens.

 

 

Sample interaction with RDP: User send a HTTP POST request with old Refresh token as one of the required parameters.

    	
            

POST https://api.refinitiv.com/auth/oauth2/v1/token HTTP/1.1

Host: api.refinitiv.com

User-Agent: python-requests/2.14.2

Accept-Encoding: gzip, deflate

Accept: application/json

Connection: keep-alive

Content-Length: 106

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

Authorization: Basic RDZEN****Q3NDo=

 

refresh_token=****&username=****&grant_type=refresh_token

 

 

HTTP/1.1 200 OK

Date: Mon, 29 Jul 2019 13:05:02 GMT

Content-Type: application/json

Connection: keep-alive

X-Amzn-Trace-Id: Root=1-5d3eeefd-e357f480db8d1020ef3fa3a0

X-Tr-Requestid: 494d97e2-526a-43f8-9da6-e0cf3221f5b3

Content-Length: 5533

 

 

{

"access_token": "eyJ0e****effg",

"refresh_token": "****-def6-47b3-aeb2-1468796846b5",

"expires_in": "300",

"scope": "trapi.admin.accounts",

"token_type": "Bearer"

}

Use: A Refresh grant is used in all application scenarios.

Authorization Code Grant

Authorization Code grant workflow, is used by public clients to exchange an authorization code for an access token. In this workflow, a user directly authenticates with authorization service, and successful interaction results in the generation of a Code. This Authorization Code can be exchanged for an Access and Refresh tokens through a back channel. Unlike Implicit grant, the tokens always stay in the secure server side session, rather than a client side session, which is not secure and can be compromised. Authorization Code grant is used in a federated authentication workflow and often used when user-login and data is to be provided through a web page.

 

 

See this tutorial for a working example and a detailed explanation of Authorization Code workflow.

Use: Authorization Code grant is typically used in web applications or mobile apps. A user does not have to provide their username or password to the web application, but rather logs-in directly to RDP login page.

Implicit Grant

The Implicit grant type is a simplified version of Authorization Code Grant that can be used by public clients. Here a successful user authentication directly gets an Access token without an extra authorization code exchange step. Implicit grant workflow was developed before web standards allowed cross-origin requests, and the Authorization Code Grant workflow could not be used in a browser based application. Recently, the industry best practice has changed to recommend that public clients should use the authorization code flow with the PKCE extension instead.

 

 

Use: Implicit grant is also typically used in web applications or mobile apps. The RDP API documentation website, which uses interactive try-it-now feature and Swagger documentation, uses Implicit grant. The Access and Refresh tokens are generated when the user first logs in, and it is retained and used in each data API request.

Summary

Use password grant for trusted applications, and use Authorization Code Grant for website or mobile apps.