Child pages
  • How to Request an HTRC Access Token
Skip to end of metadata
Go to start of metadata

The HTRC Data API is protected from access by software programs that are not known to HTRC.   To do this, it uses the OAuth2 security mechanism.  To use the Data API, your program will need to request an access token. According to the OAuth2 specification, the minimum requirement to get an access token is to have a 'Client ID / Client Secret' pair which is already registered in WSO2IS. If you are not using a client provided by HTRC (such as HTRC Portal or HTRC Agent) you will need to register your own OAuth2 client. Then you can request an access token using the Client ID / Client Secret pair of that OAuth2.

Register an OAuth2 Client in WSO2IS

The instructions for a program to register itself as an OAuth2 client are as follows.   The program must register itself in the WSO2 Identity Server that HTRC uses (WSO2IS). 

Before registering a new client in WSO2 IS, you will need to have an account in WSO2IS. After successful login, you will see the following menu under the Main tab. Then you will need to select Manage->OAuth tab.

Under the 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.This 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, in this scenario, will most probably run on a terminal or a desktop app, and will be trusted and known by the user, it will probably be more convenient for you to use Resource owner password credentials or Client credentials grant types to get 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 will work only for the above two grant types. For Client Credentials grant type, it is not necessary to set userName and passWord parameters. However, they will be useful for auditing purposes, and so we strongly encourage 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. The redirect_uri parameter in the authorization code request should match this callback url, as otherwise WSO2 IS will display an error message. This is used as a security measure to make sure that third parties have not hijacked client credentials.

 



 




  • No labels