How To Use OAuth To Integrate 3scale & Stormpath

SaaS On-premises 2.0
In this tutorial, you’ll use the OAuth resource owner grant to integrate two RESTful solutions, 3scale and Stormpath, into your API-based app. By the end, you’ll have outsourced your user management layer and your API will be 100% under control.

he outcome will be something like this:

Stormpath and 3scale integration

Since this tutorial involves customizing and integrating several platforms, including hosting an self-managed 3scale gateway, it assumes you already have some familiarity with 3scale and Stormpath.


  • Authorization server: the entity in charge of generating and managing both the bearer and refresh tokens. In our case, it will be the identity provider (IdP), Stormpath.
  • Access token: a data object that a client can use to authorize user access to a resource. It can have different attributes such as longevity and authorization scope.
  • Refresh token: another type of token that can be used in an authorization server in order to get a new access token with the same author as an existing one.
  • Resource server: hosts the resources, protects and makes the resources available to properly authenticated and authorized clients.
  • Resource owner: sometimes referred to as the API provider. The resource owner manages the resources that are served by the resource server, typically the user of the application.

Resource server: address book sample application

The resources will be hosted by an application running an API. For this tutorial, you’ll use a simple address book application, which will have two interfaces:

  • A web-based GUI, where users can log in and create and manage resources.
  • A RESTful interface, where apps can make calls to log in users and create and manage resources

This application will use Stormpath as the IdP for all user management. This is done transparently to the user so that when someone signs up for this application, a new account is provisioned in Stormpath.

For this tutorial, you’ll use a simple address book application to act as the resource server. The resources will be the contacts created and managed by this application. Please use dummy contact details for testing the integration. Since this application was built for testing purposes only, security and scalability measures have been kept at a minimum for the sake of simplicity.

Authorization server: Stormpath

The authorization server will do these three main tasks:

  • Authenticate users with a login/password combination.
  • Generate grant tokens (access and refresh) for users under its control.
  • Authorize access tokens it has previously generated (or refresh them).

Stormpath has SDKs for many languages – Python, Java, React, Go, PHP, Ruby, and more – in addition to a RESTful API, so you can use any language you prefer.

In our case, the client uses the Stormpath API to communicate with the authorization server, but the resource server uses the Ruby SDK. Many of the details in this tutorial will be generic in order to keep instructions development language agnostic.

API gateway: 3scale

The API gateway you choose should be flexible enough to track all of your API endpoints’ activity, without adding a significant delay to the response or interfering with payload content. It should also provide you with insight into what is happening with your API, so you can easily tell which endpoint is used most, whether a method is being overused, and even monetize the use of your API. 3scale takes care of all of this and more.

3scale’s highly customizable gateway enables the implementation of almost any data workflow – in this case you’ll use OAuth 2.0 – to glue all the elements together in a secure and reliable way.

You’ll use 3scale’s NGINX-based, self-managed gateway deployment to handle traffic management and routing.

Set up the basic workflow (Stormpath integration)

First you’ll get accounts for the resource server and the authorization server and test that they’re working using the client.

Sign up on the resource server and authorization server

In order to provision an account on the resource server, go to the GitHub repo here. At the bottom of the page, click on Deploy to Heroku (you will need a Heroku account). Then enter your Heroku credentials to get logged in.

At the bottom of the following page, you’ll find a Deploy for Free button. Clicking this button will:

  1. Deploy the address book app into your Heroku personal application list (with a custom app name generated for you).
  2. Create a test account in Stormpath, which you can use to test the data flow with the client in the next section.

As you may know if you’re a regular user, Heroku will assign a random unique name to the app (for example “intense-mountain-30759”), which will be an instance of the address book sample app.

You can launch it by following these steps:

  1. Look for the application name that Heroku has generated for you in your Personal Apps section.
  2. Click on that name. This will take you to that specific app page.
  3. On the top right corner of the page, you will notice three vertical dots. Click on them, and then select Open App.

A new tab will open, and you will be on the resource server application start page.

Example app - Address book

At this point, you have an API-based application that has all the user management delegated to the authorization server. You also have some test data in the resource server (a sample contact) to experiment with.

Create an account in the address book app (resource server). Then go to Stormpath (the authentication server) to check that this account is actually being provisioned there (authorization server). Also create one or two contacts to have some more data to visualize on the tests.

If you want to check on your Stormpath instance, go to the app dashboard (click on Personal Apps and then on the app name). Then click on the Stormpath User Management add-on at the bottom of the page. A new tab will open, which will navigate to the Stormpath instance that was created automatically for you. Once in Stormpath:

  1. Navigate to Application.
  2. Click on the application name.
  3. >Click on Accounts.

You will see the account(s) that you create on the address book app.

Check the client

For this tutorial, you’ll use a simple PHP client application (GitHub repo here). This app will allow a user to make a request first to the authorization server to get an access token and then to the resource server to check the resources. Open this URL in your browser to launch it.

Client app

Spend a minute looking at how it’s organized. From top left to bottom right, you find:

  1. The Client Authentication Request section with a form to enter your Stormpath username and password and two radio buttons to select whether you want to call Stormpath directly or go through 3scale.
  2. The Authorization Server Response section, where you’ll see the token provided by the authorization server, using an OAuth client credentials flow.
  3. The Request to Access the Resources section, where you can copy/paste the access token you got on box 2.
  4. Resources Server Response, where you’ll receive the response from the resource server with the list of contacts that the user entered on the address book application.

At the bottom, there are some settings that you’ll set depending on whether you’re making the calls directly to Stormpath or using 3scale. More about this in a minute.

Test the basic workflow (Stormpath integration)

Try out what you have so far.

  1. Go to your Stormpath instance and generate a new API key pair by clicking on your temporary username at the top right of the page and then on My API Keys. (Note: These key pairs have to be created on the tenant account that was provisioned for you automatically, not on the user you created for the address book app.)
Stormpath API keys
  1. You will be taken to your account dashboard. At the bottom of the page, you should see a Create API key button. Click on it to download a file with the API key and secret.
  2. You’ll also need the Stormpath application ID. To get it, on click on the Applications tab in Stormpath and then on the application name. This name should be the same as the application name in Heroku (for example “intense-mountain-30759”). You will find a label with the application ID. Keep that on hand as well.
Stormpath app ID
  1. f you haven’t done it yet, create a new user in the address book application by clicking on Sign up and following the instructions. Remember the username and password that you enter.
  2. Open the client app in a browser.

Fill in the following fields:

a. In the Stormpath settings, enter the app ID from step 3 above. b. In the Stormpath settings, enter the API key from step 2 above. c. In the Stormpath settings, enter the API secret from step 2 above. (Of course in a production environment, the API key and secret should not be entered/transmitted like this.) d. In the Client Authentication Request box, enter the username and password that you created on step 4 above. e. Make sure you have the Directly to Stormpath radio button selected in the top left section. f. Finally, click on Authenticate (Get Token).

If everything went ok, a new token should appear in the Authentication Server Response box.

Copy/paste the token into section 3, and click on Authorize (access resources). This will send a request to the resource server (the address book) to list that user’s contacts, using the access token to authorize the call. The result should be an output of the user´s contacts on section 4.

Client app filled

Add the API gateway

ow you have a working user authentication layer to control access to your resources. There are a number of reasons you would want to go beyond this to control access to your API endpoints with an API gateway:

  • Differentiate and track access by client app.
  • Rate limit by client app and endpoint to protect your valuable resources.
  • Enable/disable access to endpoints for rights and roles.
  • Engage internal and external developers with a developer portal and interactive API documentation.

For this, you’ll use 3scale. If you don’t already have a 3scale account, the process for creating one is really simple. Just go to and click on Start free trial. The onboarding wizard will guide you through the rest of the process (it only takes a couple of minutes).

Configure API gateway authentication mode

Configure the settings in your 3scale account:

  1. Go to Dashboard > API > Integration and click on Edit Integration settings.
  2. In the Gateway section, choose NGINX Self-managed gateway.
  3. In the Authentication section, click on OAuth 1.0 and 2.0.
  4. Finally, click on Update Service.

You have now configured the 3scale gateway to support OAuth 2.0 in a self-managed deployment.

Note: You’ll need to host the NGINX server in order to upload the configuration files that you’re going to set up next. For this, you can follow the Hosting a 3scale NGINX gateway on AWS tutorial. If you want to keep it simple, this other tutorial on how to host an NGINX API gateway on Heroku may come in handy: NGINX Gateway On Heroku

Customize API gateway config files

Get some preconfigured files from this GitHub repo. Either clone it or click on the Download ZIP button to get the files. You should end up with four files (or five including

  1. stormpath.conf
  2. stormpath.lua
  3. get_token.lua
  4. threescale_utils.lua

Numbers 1 and 2 are the main configuration files for the NGINX gateway and the Lua code, which will do some data manipulation of the requests so that the specific flow is implemented as you’d expect. Number 3 is the file that will actually make the call to get the tokens. There is no need to modify this file at all. Move these three files to the NGINX config directory and replace any previous versions.

File 4 is just a library file. You will have to place it somewhere where NGINX will find it. For instance, if you followed the Hosting a 3scale NGINX gateway on AWS tutorial to host your gateway, the /opt/openresty/lualib subdirectory would be a typical location (the LuaLib directory does not exist by default, so you will have to create it). You could also use the /opt/openresty/nginx/conf directory. If NGINX does not find it, check the error.log file. NGINX will tell you in which directories it tries to find this file.

There are several changes you need to make to those files to configure the parameters so they can talk to Stormpath and the address book application. The next sections describe what those changes are. Before that, make sure to change the ownership of the files to root:root. Otherwise some permission issues may prevent things from working.

The changes are all commented inline and can be classified into three groups:

  1. The parameters that you need to set to connect to the 3scale backend
  2. The parameters that you need to set to make calls to the Stormpath API
  3. The parameter that you need to set to tell 3scale where the backend API is (your address book app)


Open the stormpath.conf file and look for all the “CHANGE_ME” strings. These are the parameters in the file that have to be configured manually. Go ahead and update all of them with your values.

There are five changes you need to make:

  1. Set the 3scale providerkey and serviceid so that all the calls to the 3scale backend get authenticated/authorized.
  2. At the beginning of the file, there is an “upstream” section where you define the backend services that 3scale will be calling. From the diagram at the beginning of this document, you’ll see there are two of them. One is always the same – the Stormpath API, which is already configured for you. The other one corresponds to the address book API. This is not a fixed URL, as it is randomly generated for each instance. Here, manually enter the full Heroku app URL.
  3. Specify the Stormpath appid on the location /oauth/stormpathgettoken. As the inline comment says, you need to specify the appid when you call the Stormpath API to get a token so that it knows which user (by the username/password) and which application of that user the token belongs to. Go ahead and also enter the Stormpath appid here.
  4. On the location (/oauth/stormpath_gettoken), specify the Stormpath API key and secret values, so 3scale can authenticate itself against the Stormpath API. Enter the API key/ secret values you used for the previous test.
  5. Finally, update the proxysetheader Host variable on the location /api location.

All of the above changes are commented inline in the file – just look for the CHANGE_ME string.


Open the stormpath.lua file and look for the “CHANGE_ME” strings again. There are only two parameters to change in this file:

  1. Set the ngx.var.proxy_pass to point to the address book Heroku app URL.
  2. Set the 3scale service_id value.

Once you’ve made all of the above changes, restart NGINX.

Test the complete workflow

Now locate these three parameters:

  • The provider ID
  • The service ID
  • The client ID (also known as app ID)

You’ll also need to input the 3scale gateway URL in the 3scale setting section. Here is how to locate them:

To find the service ID, log in to your Admin Portal. Go to the API tab, and find the line that says ID for API calls is XXXX and system name is YYY. The XXXX string is your service ID.

3scale service ID

To find the client ID and secret, click on the Applications tab. Then click on the name on the list that you want to use to for this tutorial. You’ll find the client ID and secret at the bottom left, as show on the screenshot:

3scale app ID

Now that you have the API layer integrated in the workflow, go back to the 3scale-Stormpath OAuth sample client again. Do the same as before, but this time:

  1. Enter the 3scale client ID and secret in the settings at the bottom left of the page.
  2. Make sure to select the Through 3scale radio button option, so the call is now made from the client to the 3scale backend, and from there to the Stormpath and address book backends.

Before you test it, make sure you still have the Stormpath credentials in the settings sections. This time, those credentials will be used by the 3scale gateway to access Stormpath.

The 3scale client ID and secret are used to identify the 3scale application to report the requests, so 3scale can show them in your analytics.

Go ahead and enter all the credentials, and you should see the same results – a new token generated on the second box and a list of contacts in the lower right box. The difference now is the call will be made and tracked by the 3scale gateway.

Go to your 3scale Admin Portal to take a look at the analytics. The aggregated metric should have increased. You can also add a new method. For example, list_resources can show the number of calls made to the “list contacts” endpoint.

3scale Analytics