At Stormpath, we spend a lot of time designing features to help developers build applications using best practices for authentication, authorization, and user data security.

Now, Stormpath makes it easy for developers to generate OAuth 2.0 access tokens. This new feature gives your applications a way to authorize requests for other applications and micro-services that you own.

Developers often come to us with these questions:

  • How do I secure my API so only authenticated users can access it?
  • How do I manage stateless tokens and still control access after a logout or if I need to revoke a token?
  • How to do I store session information in my application that doesn’t incur state on my server or APIs?

Stormpath OAuth Support allows you to do all these things, and this post will show you how to use this feature, or at least understand the functionality required for a good token management system. You can also go straight to the deep documentation on how to use Stormpath to manage tokens in our Token Management Guide.

Before we get into the nitty gritty though…

A Crash Course in Token-Based Authentication and Management

Token-based authentication secures an application based on a security token that is generated for the user on authentication. Since HTTP is considered stateless, if your application authenticates a user (one HTTP request), your application won’t know who the user is on the next request. This is why many applications pass some information to tie the request to a user. Traditionally, this information requires state to be stored on the server and a session identifier to be stored on the client.

Token-based authentication is all about removing the need to store information on the server while giving extra security to keep the token secure on the client. This helps you as a developer build stateless, scalable applications or services.

Stormpath complies with OAuth 2.0 to provide this functionality.

Why OAuth 2.0?

OAuth 2.0 is an authorization framework. It’s a protocol that defines how to delegate authentication or provide authorization. OAuth 2.0 is prevalent across many mobile and web applications today. If you have ever logged into a website using Facebook or Google, you have used one of OAuth 2.0’s many authorization flows. You can read more about the different OAuth 2.0 authorization flows or grant types in this great article by Randall Degges.

OAuth 2.0 supports many authorization grant types. Among them, Stormpath currently supports:

  • Password Grant Type that grants the ability to get an Access Token based on a login and password for your application.
  • Client Credentials Grant Type (which is supported through our API Key Management feature) that grants the ability to exchange an API Key for the Access Token.
  • Refresh Grant Type that grants the ability to generate another Access Token based on a special Refresh Token.

Managing OAuth 2.0 Access and Refresh Tokens

OAuth 2.0 gives us two types of tokens to manage:

  • Access Tokens
  • Refresh Tokens

The Access Token grants access to a protected resource or API. The Access Token that Stormpath generates for accounts on authentication is a JSON Web Token, or JWT. The JWT makes sure that the Access Token is not tampered with on the client and is only valid for a specified duration.

The Refresh Token is a special token used to generate additional Access Tokens. This allows you to have a short-lived Access Token without having to collect credentials from the user every single time you need a new Access Token.

When using OAuth 2.0, the Access Token and Refresh Token are returned in the same response during the token exchange, this is called an Access Token Response.

How to Use Stormpath for Token Management

Now to the fun part, the code!

When building this type of functionality, there are four discrete actions that can be performed with tokens: generating, validating, refreshing, and revoking.

The examples here use the Stormpath Node SDK, but this functionality is available in the other Stormpath SDKs. Also, if you are using a Stormpath integration (like express-stormpath with stormpath-angular), it will use OAuth 2.0 Access Tokens automatically.

How To Generate OAuth Tokens

Before you can manage and validate tokens for authorization, you need to generate a token. Stormpath exposes an OAuth 2.0 endpoint off of your Stormpath Application href, which the SDKs use to generate tokens.

To generate a token for your client, you can expose your own OAuth 2.0 endpoints and then sent the OAuth request on to Stormpath, essentially functioning as a proxy. Alternatively, you collect the client’s credentials and use Stormpath (either with the SDK or via REST) to exchange these for an OAuth token.

Generating a token requires that the account exists in Stormpath, is associated with the Stormpath Application generating the token, and provides valid credentials for the account.

The access and refresh token expirations are configurable because different applications may have different requirements around how long a token should live, or how often the user should need to provide his credentials (which would be controlled by the refresh token expiration). By default, Stormpath Access Tokens expire in one hour, and the refresh tokens expire in 60 days.

The Access Token Response has the following structure:

This response tells you exactly when the Access Token will expire. There is also a stormpath_access_token_href which gives you the location of the Access Token in Stormpath, which is useful if you need to, for example, revoke the token.

The long strings of characters that represent the Access and Refresh Tokens are JSON Web Tokens, or JWT. The JWT is signed with your API Key Secret used to initialize the client. This is useful if you need to validate the signature locally using a JWT library.

Once your application has the Access Token, it can be stored on the client and passed in additional requests to your application or API.

How To Validate OAuth Tokens

Once you have generated a token, you usually deliver it back to the client that requested it. The client then stores it and passes the Access Token property in requests to your application. This is usually done with either a cookie value, or an Authorization header in HTTP. For example:

Validating the token allows you to verify the authenticity of the token (by checking its digital signature you can check that it is not expired and verify that it hasn’t been tampered with) and get information about who the token belongs to by the claims stored in the token.

Once you receive an Access Token you can validate it either locally, and using Stormpath. The following table illustrates the differences:

Validation Criteria Locally    Stormpath
Token hasn’t been tampered with yes yes
Token hasn’t expired yes yes
Token hasn’t been revoked no yes
Account hasn’t been disabled, and hasn’t been deleted no yes
Issuer is Stormpath yes yes
Issuing application is still enabled, and hasn’t been deleted no yes
Account is still in an account store for the issuing application   no yes

Why is this important? Because the level of validation that each application needs may differ. If you need to validate the state of the account / application or if you need to use token revocation, then using Stormpath to validate the token is the obvious choice. This does require a request to the Stormpath REST API. If you only require that the token has not expired and has not been tampered with, you can validate the token locally and minimize the network requests to Stormpath.

To validate the token with Stormpath’s Node SDK:

Or, if you are validating the token locally:

How To Refresh OAuth Tokens

Passing Access Tokens for authorization allows access to resources in your application. But what happens when the Access Token expires? You could require the user to authenticate again, or use the Refresh Token.

A Refresh Token allows you to generate new Access Tokens for a user without collecting credentials again. It gives an elegant way of changing out an old Access Token with a new one without effecting the user experience.

For example, if you generated an Access Token Response with a token expiration of 30 minutes and a Refresh Token time of 1 day, you would be able to generate a new Access Token when the old one expires (every 30 minutes) for 24 hours straight. Once the Access Token expires after 1 day, the Refresh Token will also expire, and the user will need to log in again.

Stormpath gives you the ability to quickly refresh a token if it expires.

How To Revoke OAuth Tokens

Revoking tokens is an important feature for managing tokens, especially for a couple different scenarios:

  • The user has explicitly logged out, and your application needs to revoke their access, requiring authentication again.
  • The application, device, or client has been compromised and you need to revoke tokens for all accounts.

Stormpath gives you the ability to quickly revoke a token, just by deleting it. There are a couple ways you can get the Access or Refresh token revoked:

  • Query the collection of accessTokens or refreshTokens on an account.
  • Using the stormpath_access_token_href property in the access token response.
  • Validate the token using the Stormpath API, which will return the access token.

Once you have the token you want to revoke, just delete it:

When you attempt to validate the token against the Stormpath API and it doesn’t exist, it will fail validating so you know it is revoked.

Wrapping Up

Token authentication and access token management give your application a way to authorize requests and control user access securely and easily.

You can read more on how to use Stormpath to manage tokens in our Token Management Guide.

Any questions or comments? Feel free to leave them here or reach out to me directly on Twitter (@omgitstom).