Add OAuth Support to a Legacy App With Four Lines of JS

×

Status message

New Feature: Guest Login function added to facilitate site exploration without registering. Try it out!

by Joe Stubbs

This guide provides a simple way to add support for retrieving Araport access tokens using the OAuth2 protocol. It leverages the "Implicit flow" of the OAuth2 spec and can be used in any web-based application but is particularly suited for pure JavaScript applications with no backend server and legacy applications where tighter OAuth integration would be difficult. Our solution leverages the JSO library because it is particularly simple to use; however, if tighter platform integration or more advanced functionality is required we recommend the Araport JavaScript SDK.

Step-by-step guide

This guide is organized into two tasks: registering an application as an OAuth client with Araport and implementing the OAuth Implicit Grant protocol using the JSO library. The former is a requirement for the latter so we discuss it first, but if you have already registered your application as an OAuth client, feel free to skip down to the section on "Adding OAuth Support Using the JSO Library".

Registering an OAuth2 Client

The first thing to do is to register your application as an Araport OAuth client if you haven't already. Client registration is accomplished by making a POST to the clients service. There are two key pieces of information you need to pass in the POST body:

  1. clientName - a unique identifier for your client.
  2. callbackUrl - the web-accessible URL where you will be retrieving the access token. It is this URL where you will add the JavaScript solution we describe in the next section.

Here is an example call to the clients service using the Linux command line HTTP client curl and the resulting response (sensitive data have been scrubbed):

$ curl -u "jstubbs:<password>" -X POST --data "clientName=oauth_ex&description=example&callbackUrl=http://localhost:9000/agavejs.html" "https://api.araport.org/clients/v2"

{
    "message": "Client created successfully.",
    "result": {
        "_links": {
            "self": {
                "href": "http://api.araport.org/clients/v2/oauth_ex"
            },
            "subscriber": {
                "href": "http://api.araport.org/profiles/v2/jstubbs"
            },
            "subscriptions": {
                "href": "http://api.araport.org/clients/v2/oauth_ex/subscriptions/"
            }
        },
        "callbackUrl": "http://localhost:9000/agavejs.html",
        "consumerKey": "eQ08****************umUa",
        "consumerSecret": "G0_0*******************GcEa",
        "description": "example",
        "name": "oauth_ex",
        "tier": "Unlimited"
    },
    "status": "success",
    "version": "2.0.0-SNAPSHOT-rc3fad"
}

In this example, I am using the name "oauth_ex" for my client and I am registering a callbackUrl of http://localhost:9000/agavejs.html since this is just an example running on my local machine. Take note of the consumerKey returned as you will need this below.

Adding OAuth Support Using the JSO Library

Now that we have registered our client, we are ready to add the JavaScript solution to our application. Here are the steps:

  1. Download the JSO library directly from github:

        $ git clone https://github.com/andreassolberg/jso
    
    

    Or install directly into your project using bower:

        $ bower install jso --save
    
    
  2. Next, load the JSO library into your web application. The library is contained in a single file, jso.js, which is in the src directory of the git hub repository (it is not currently served by any CDN). Copy that file to an appropriate location in your application, for instance within a static media directory, and link to it using a script tag:

    <script type="text/javascript" src="static/js/jso.js"></script>
    
    

    If you are using bower, the script tag will look something like this:

    <script type="text/javascript" src="bower_components/jso/build/jso.js"></script>
    
    
  3. With the script loaded, create a jso object with your configuration in it.

    var jso = new JSO({
           providerID: "araport_example",
           client_id: "eQ08***********************umUa",
           redirect_uri: "http://localhost:9000/agavejs.html",
           authorization: "https://api.araport.org/oauth2/authorize",
           scopes: { request: ["PRODUCTION"]},
        });
    

    Here is an explanation of the arguments:

    Argument Explanation
    providerID Optional name tag used to prefix the data stored in local storage.
    client_id The “consumerKey” returned to you by the Agave clients service.
    redirect_uri The URI that the user will be redirected back to when completed. This should be the same URL that the page is presented on and should match the value of callbackUrl passed to the Agave clients service when registering the client.
    authorization The URL of the Araport authorization server.
    scopes The scope requested for - should always be PRODUCTION for the current Araport OAuth server.

    For more options, see the JSO documentation: https://github.com/andreassolberg/jso/blob/master/README-getting-started.md

    Note: Creating the jso object will automatically take care of detecting whether there is a token in local storage and, if not, redirecting the user to the Agave login server. You may wish to do this in a window for a better user experience.

  4. JSO requires invoking the callback method before retrieving the token:

    jso.callback();
    
  5. Access the token using the convenience function:

    jso.getToken(function(token) {
           console.log("I got the token: ", token);
           console.log(“Access token string itself:”, token.access_token);
        });
    
  6. Optionally, create a logout service using the jso.wipeTokens() function:

    <button type="button" onclick="jso.wipeTokens(); alert('You have been logged out.');"> Logout </button>