View on GitHub

Computational Science in the Cloud Institute 2016

Introduction to OAuth and the Agave API

In this module we introduce OAuth and the Agave API.


HTTP Basic Auth is pretty easy to use, but it has some limitations, the primary one being that we have to pass the secret into every request. At best this is annoying and a little insecure, but what if we are writing an application for others and they do not want to share their github password with us? This is where OAuth comes in.

Basic concepts

The key concepts in OAuth are:

If you ever used a site that said “Log in with your Facebook or Google account” then you have used OAuth. An in-depth treatment of OAuth is beyond the scope of this course, but we will see it in a little detail when we explore the Agave API.

Agave API

Agave ( is an API platform developed here at TACC for conducting computational science experiments on HPC and cloud resources.

We will introduce Agave towards two objectives:

In fact, Agave has many more APIs that may be of interest to you such as the Jobs API for launching and managing jobs on remote computers such as Stampede, or the Meta API for storing arbitrary metadata objects about scientific experiments.

Agave is a full-featured OAuth provider and leverages the TACC identity system behind the scenes. The hands on portions below will leverage your TACC username and password.

To get started, we are going to generate a set of Agave client keys (OAuth client credentials). Generating OAuth clients uses HTTP Basic Authentication with your TACC username and password. We will do this in a Jupyter notebook. The

Exercise. Use HTTP Basic Auth with your TACC username and password against the Agave clients service to list all your OAuth clients. Explore some of the endpoints within the clients service. Discuss the notion of API subscriptions.

Creating a client

To create a simple OAuth client that has access to all basic Agave APIs, we need to make a POST request to the clients service. The only required field we need to pass in is clientName to give a name to our client. Each client we create must have a unique name.

In order to create an Agave OAuth client, we make a POST request to the Agave clients service. The only required field we need to pass in is clientName to give a name to our client. Each client we create must have a unique name.

Exercise. Generate an Agave client by making a POST request to the clients service.

Clients are identified by their key and secret. These two important properties are returned in the fields consumerKey and consumerSecret respectively.

Exercise. Extract the key and secret from the client you just generated into variables in the notebook. We will need these fields to interact with the Agave OAuth token service and generate an access token.

Generating Access and Refresh Tokens

We’re now ready to generate an OAuth token. This token will represent both the user and client application. In this case, they are owned by the same individual, but in general they will not be.

To generate an OAuth token, we make a POST request to Agave’s token service. We have to pass in several fields to make the request:

It might seem odd that we are passing in the username and password when that was one of the things we were trying to avoid. There are two points to make:

  • first, we only have to pass it in once to get the access token and then all subsequent requests will use the access token.
  • second, in general we could use a different grant type to not have to collect the password at all, but in this introduction we are taking the simplest approach.

A note about scopes:

scopes in OAuth can be used to limit/restrict the kinds of access the client has. The scope of PRODUCTION indicates that the client will have full access (i.e., read, write, update, execute) to the user’s resources.

Also, keep in mind that the Agave token service URL is simply - it does not have a v2 in it.

Semantically, the idea was that the token service was independent of the Agave platform version.

The response, if successful, will contain the following fields:

Exercise. Generate an access and refresh token using the Agave token endpoint.

Using an access token

Once we have an access token we are ready to interact with the rest of the Agave services. All requests to Agave using this access token will be done on behalf of the user whose credentials were used to retrieve the token (as well as the OAuth client that was used).

In order to make a request to Agave using the access token, we need to pass the token into the Authorization header of the request. The value of the header must be formatted like so: “Bearer "

As a simple check, we’ll use the Agave Profiles service to pull the “profile” associated with this token. The Agave Profiles service maintains some details about registered users.

Exercise. Use the access token to make a request to the Agave profiles service "me" endpoint to retrieve the profile associated with the token.