3E API

02 - API Authentication and Access

OVERVIEW

For on-premises 3E instances the 3E API uses Integrated Windows Authentication for authentication. Authorization is provided through security on the 3E User. For 3E in the Cloud the 3E API uses OpenId Connect and OAuth 2.0 protocol for authentication and authorization. This following information quick start steps on how to use the OAuth 2.0 authorization process to access the 3E API. It also provides details on token management and revoking user consent.

Quick Start Steps

Token Expiration

Token Storage

Revoking Consent

Note: Currently the 3E API supports use cases for server applications.

QUICK START STEPS

Use the following steps for 3E API authentication and usage:

  • Obtain OAuth2 Credentials for Your App
  • Define Allowed Callback URLs
  • Define Allowed Logout URLs
  • Download OAuth Library
  • Prepare Authorization Request
  • Redirect to Thomson Reuters Authorization Server
  • Obtain Access Token
  • Handle the Authorization Server Response 

Step 1: Obtain OAuth2 Credentials for Your App

To begin, obtain OAuth 2.0 client credentials (i.e., client ID / client secret) by creating a new OAuth Client Application. To create OAuth Client Application you have to reach out to open a Support case with a request for client credentials. Once your OAuth client is created in Thomson Reuters Authorization Server to represent your application, your application can requests an access token from the Thomson Reuters Authorization Server.

Step 2: Define Allowed Callback URLs

When you send the request to create an OAuth client for your application, include redirect URIs. These URIs handle responses from the Thomson Reuters Authorization Server and are called after the application user authorizes the connection. URIs in this list are the only ones to which the authorization response can be sent from the Thomson Reuters Authorization Server.

You must define at least one URI specifically for your application’s authenticated endpoint before you can use OAuth 2.0. For the lower environment, this list can include localhost. 

Step 3: Define Allowed Logout URLs

This step is optional. If you plan to redirect a user back to the application after logout, provide the list of allowed Logout URIs.

Step 4: Download OAuth Library

Download and use your prefered OAuth 2.0 library.

Step 5: Prepare Authorization Request

Your application must create the authorization request with the parameters that identify the application and permissions that the user will be asked to grant to your application.

Parameter Description
client id This value identifies the application that was given by TR representative
client_secret   This value is secret for application that was given by TR representative
scope The scope parameter indicates which 3E API endpoints the user will be give access to
redirect_uri The URI that TR server will redirect during the authroization flow

Code to demonstrate how to initialize authorization request:

var startUrl = $"{settings.Authority}/authorize?response_type=code"
    + $"&client_id={UrlEncoder.Default.Encode(settings.ClientId)}"
    + $"&scope={UrlEncoder.Default.Encode(settings.Scope)}"
    + $"&redirect_uri={UrlEncoder.Default.Encode(settings.ReplyUrl)}"
    + $"&login_hint=thomsonreuters.com"
    + $"&connection=sso-auth-nonprod"
    + $"&audience={UrlEncoder.Default.Encode(settings.Audience)}";

Navigate(startUrl);

Step 6: Redirect to Thomson Reuters Authorization Server

Redirect the user to Thomson Reuters Authorization Server using the URL prepared above to initiate the authentication and authorization process. This step is required when your application first needs to access user’s data. In the case of incremental authorization, this step also occurs when your application first needs to access additional resources that it does not yet have permission to access.

https://auth-nonprod.thomsonreuters.com/authorize?response_type=code
    &client_id=JfY4DPn51F5Wv4O551QUl5jbhZmF7oiD
    &scope=openid%20offline_access%20https%3A%2F%2Fapi.thomsonreuters.com%2Fauth%2F3e.core.runtime
    &redirect_uri=http%3A%2F%2Flocalhost%3A8686%2Fsampleapp%2Fauth
    &login_hint=thomsonreuters.com
    &connection=sso-auth-nonprod
    &audience=https%3A%2F%2F3ecloud.thomsonreuters.com%2Fapi%2Fnprd%2F3e-hardening-int%2F3e_api%2Fih0aw5rqtuuq2lcpwqqjbw

Step 7: Obtain Access Token

Before your application can start using the 3E API, it must obtain an access token that grants access to the API endpoints. The scope parameter used while requesting the access token controls the set of resources and operations that an access token permits. During the access token request, your application sends one or more values in the scope parameter.

Obtaining the token requires an authentication step where the app user logs in using their account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent.

If the user grants the permission, the Thomson Reuters Authorization Server sends your application an authorization code at the callback endpoint that you defined in the Redirect URI. This authorization code can then be exchanged to obtain the access token. If the user does not grant the permission, the server returns an error.

Example: User is presented with consent screen to give application permission to call 3E APIs on user's behalf:

Image

Step 8: Handle the Authorization Server Response 

The Thomson Reuters Authorization Server responds to your application’s access request by using the redirect URI (redirect_uri) specified in the request.

If the user approves the access request, then the response contains an authorization code. An example callback looks like the following:

http://localhost:8686/sampleapp/auth?code=4JZ7sLWz3RGwX4nx

Once an authorization code is successfully acquired it can be used to obtain access and refresh tokens:

var code = await browser.Login();
var client = new HttpClient();

var request = new FormUrlEncodedContent(new Dictionary<string, string> {
    { "grant_type", "authorization_code"},
    { "code", code } ,
    { "client_id", ciamSettings.ClientId },
    { "client_secret", ciamSettings.ClientSecret },
    { "redirect_uri", ciamSettings.ReplyUrl}
});

var response = await client.PostAsync($"{ciamSettings.Authority}/oauth/token", request);
var tokenResponse = await ProtocolResponse.FromHttpResponseAsync<TokenResponse>(response);

if (tokenResponse.IsError)
{
    logger.Log($"Failed to authenticate: {tokenResponse.Error} {tokenResponse.ErrorDescription}");
    return false;
}

await store.SaveToken(tokenResponse.RefreshToken);
return CompleteCIAM(tokenResponse.AccessToken, tokenResponse.ExpiresIn);

TOKEN EXPIRATION



Access tokens are valid for 60 minutes (i.e., one hour), after which you need to get a new one using the rotating refresh token obtained during Step 4 above. You must write your code to anticipate the possibility that a granted access token might no longer work.

Rotating Refresh Tokens are valid for 90 days from the day they are issued. Once the rotating refresh token expires, the user must re-connect to 3E through your application. 

TOKEN STORAGE

Access tokens carry the information to access an API. A rotating Refresh Token carries information necessary to get a new Access Token. Third-party partners must never expose Access Tokens and Rotating Refresh Tokens to anyone else apart from the application requesting the tokens.

Access Token generally do not need to be persisted. Third-party partners must keep Access Tokens only in volatile memory (e.g., RAM). Do not store Access Tokens in persistent memory like databases, files or tapes.

If a Rotating Refresh Token needs to be stored in persistent memory, Third-party clients must encrypt the Refresh Tokens with a strong symmetric encryption algorithm and then store the encrypted Rotating Refresh Token in persistent memory.

REVOKING CONSENT

Currently to revoke a user's consent, the user must open a Support Case and TR has to revoke the consent for the user.

Note: The TR Authorization Server will provide self service Manage Profile UI at a future date so users can revoke the consent themselves for third-party applications.