How to abstract token authentication to a gateway layer - using Stormpath and Nginx

Stormpath has long supported Token Authentication and API key management, so developers can offload API access management. But we have always wanted to simplify this further, by abstracting API authentication to the gateway layer.

Abstracting more and more logic away from the application code dramatically reduces maintenance and complexity – fewer application dependencies that can break over time. Nginx has been successful with this for load balancing, caching, monitoring and management. Now, it’s time for authentication. Regardless of what kind of APIs you build, you probably don’t want to leave them open for anyone to call. Authenticating the caller is still necessary.

The Stormpath Nginx Integration for Token Authentication

For this, you can use our stormpath-nginx integration, which abstracts token authentication and validation upstream to Nginx. This integration allows you to expose OAuth 2.0 at the gateway in front of your application. Nginx is one of the most popular open-source web servers and load balancers, and the integration with Stormpath exposes an OAuth 2.0 /oauth/token endpoint to generate access tokens for your users.

Instead of installing a Stormpath integration or SDK into each one of your API’s codebases, you can instead have Nginx handle your authentication. This reduces the number of application dependencies for your service while giving your service – and each service you add – a shared user store, with authentication and authorization capabilities.

Integrate Stormpath to Nginx

Integrating Stormpath into your nginx.conf file is as easy as:

location /api/ {
    access_by_lua_block {
        local stormpath = require("stormpath-nginx")
    proxy_pass http://localhost:3000/;

When a user makes a request to /api/*, Stormpath will look for and validate an access token for the request. If no access token is found, Stormpath will ask Nginx to render a 401 Unauthorized page. Otherwise, Stormpath will allow the request through and add the following headers:

  • X-Stormpath-Account-Href – a link to the authenticated Stormpath account.
  • X-Stormpath-Application-Href – a link to the Stormpath application that issued the access token.

What this means is your API only needs to look for forwarded headers to understand who the user is and if they authenticated.

Authenticating with Nginx using Stormpath – How it Works

To be able to authenticate into the endpoints exposed through Nginx, you will first need to get an access token. Luckily, the stormpath-nginx integration also exposes an OAuth 2.0 endpoint that can issue access and refresh tokens for authenticated users, which can be configured in nginx.conf by: 

location = /oauth/token {
    content_by_lua_block {
        local stormpath = require('stormpath-nginx')

Once the token endpoint is configured in Nginx, a user can authenticate with a REST call from any client using OAuth 2.0:

POST /oauth/token

The above will return an OAuth 2.0 Access and Refresh token (configurable):

HTTP/1.1 200 OK

The access token generated can now be used to authenticate against the /api/* endpoint using Bearer authorization:

GET /api/123 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

 If the bearer token can be authenticated, Nginx will forward the request to your application code with headers set to let your code who called your endpoint.

The value here is that your application code can abstract token authentication and validation upstream to Nginx. Getting started is as easy as following the instructions here.

Have more questions? Submit a request



Please sign in to leave a comment.