At Stormpath, we care – a lot – about the craft of API development. We want to help developers focus on building robust, intuitive and scalable APIs, and let go of the worry and hassle of authenticating those services. 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

I’m happy to announce the 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:

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:

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

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

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

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.

Pretty easy right? 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.

If you have any questions, comments, or suggestions, feel free to reach out to me by email or via Twitter @omgitstom.