Navigation

Requesting Access Token to Access HTRC Data API

Introduction

Because HTRC anticipates providing access to the full 11M+ volume corpus, the Data API is protected by an access token that authenticates a person. According to OAuth2 specification, minimum requirement to get an access token is client ID/secret pair which is already registered in WSO2IS. If you are not using a client provided by HTRC, such as HTRC Portal or Agent, your need to register your own OAuth2 client. Then you can use client ID/secret pair of that OAuth2 client to request an access token.

Register an OAuth2 Client in WSO2IS

Following is the process to register an OAuth2 client in WSO2IS. Before register a new client in WSO2 IS, you need to have an account in WSO2IS. After successful login, you’ll get the following menu under Main tab. Then have to select Manage->OAuth tab.

Under OAuth Management page select Register New Application to register a new client application.

Then select ‘2.0’ as OAuth Version and specify other basic information including callback Url[1].

Once you click on Add you’ll redirect to OAuth Management page which list currently registered client applications.

You can get Client ID and Client Secret by clicking the link of your client application.These information is required when developing the token request.

Requesting a OAuth2 Access Token

In order to request an access token you need to select one of the  authorization grant types in OAuth2. Since the client of this scenario will most probably run on terminal or desktop app and will be  trusted and known by the user, it is more convenient to use Resource owner password credentials or Client credentials grant types to grab a token.

Below is the code which can used to build the access token request. Here it is used OAuthClientRequest utility from Apache Amber library to build the redirect URL. What this code basically does is build the URL which we are going to use for redirecting back to WSO2 IS. This would works only for above two grant types. For Client Credentials grant type, it is not necessary to set userName and passWord parameters. But they would be useful in auditing purposes, so we strongly encouraged you to use “Resource owner password credentials grant type”. 

OAuthClientRequest accessTokenRequest = OAuthClientRequest
                   .tokenLocation("https://sandbox.htrc.illinois.edu:9443/oauth2endpoints/token")
                   .setGrantType(GrantType.PASSWORD)
                   .setClientId(clientID)
                   .setClientSecret(clientSecret)
                   .setUsername(userName)
                   .setPassword(passWord)
                   .buildBodyMessage();


OAuth2Client accessTokenClient = new OAuth2Client(new URLConnectionClient());


OAuthClientResponse accessTokenResponse = accessTokenClient.accessToken(accessTokenRequest);


String accessToken = accessTokenResponse.getParam(Constants.OAUTH2_ACCESS_TOKEN);

 

 

 

 

 

 

 

 

 

 

 

Once you get back the access token from the WSO2 IS, you can save it in the session and use it with future requests to secured APIs.

Sending OAuth2 Token with Data API Request

To send a request to a Data API service instance that is protected by OAuth2, the request must have the OAuth2 Token in the HTTP request header "Authorization" as the following:

Authorization: Bearer <OAuth2 Access Token>

where <OAuth2 Access Token> is the token returned from WSO2 IS in the previous section.  The token must be concatenated with the string literal "Bearer " (note the trailing space).

Below is an example of setting this header in Java:

String accessToken = ... // obtain the access token from WSO2 IS

HttpsURLConnection httpsURLConnection = ... //instantiate the HTTPS URL Connection

httpsURLConnection.addRequestProperty("Authorization", "Bearer " + accessToken);

Maven Dependencies

To use OAuthClientRequest, OAuthClientResponse and OAuth2Client in your java projects, you need to add following maven dependencies and repositories to your pom.xml file.

<dependency>

    <groupId>org.apache.amber</groupId>

    <artifactId>oauth2-client</artifactId>

    <version>0.22.1358727-wso2v2</version>

</dependency>

 

<dependency>

    <groupId>org.apache.amber</groupId>

    <artifactId>oauth2-common</artifactId>

    <version>0.22.1358727-wso2v2</version>

</dependency>

 

<dependency>

    <groupId>edu.indiana.d2i.htrc.oauth2</groupId>

    <artifactId>client-api</artifactId>

    <version>1.0.1</version>

</dependency>

 

<repository>

    <id>internal</id>

    <name>Internal Release Repository</name>

    <url>http://htrc.illinois.edu:8080/archiva/repository/internal/</url>

    <releases>

        <enabled>true</enabled>

    </releases>

    <snapshots>

        <enabled>false</enabled>

    </snapshots>

</repository>

<repository>

    <id>snapshots</id>

    <name>Internal Snapshot Repository</name>

    <url>http://htrc.illinois.edu:8080/archiva/repository/snapshots/</url>

    <releases>

        <enabled>false</enabled>

    </releases>

    <snapshots>

        <enabled>true</enabled>

        <updatePolicy>always</updatePolicy>

    </snapshots>

</repository>

 

 [1]  This callback Url will be used for validating incoming authorization requests.  redirect_uri parameter in authorization code request should match this callback url, otherwise WSO2 IS will display an error message. This is used as a security measure to make sure that third parties haven’t hijacked client credentials.