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.
