The best way to securely manage user sessions
June 08, 2019

The best way to securely manage user sessions

This is part 2 in a two-part series on session management. If the reader understands the general concepts of JWT (JSON web token) and user sessions, then Part 2 can be read without reading Part 1.

Part 1: Introduction to session management, analysis of most commonly used session flows, and best practices

Part 2: Analysis of a new open source session flow that is secure and easy to integrate

Part 1 provided an educational guide into session management (how auth tokens are handled, stored and changed during an active session) and we discussed several commonly employed session flows. However, we believe that the flows mentioned in Part 1 are sub-optimum in terms of security for most use cases. We came across a flow conceptualized by the IETF (Internet Engineering Task Force) in RFC 6819. We’ve taken the proposed flow, built it and upon request of others, have open sourced our code for the wider community.

In this post, we’ll explore and analyze the session flow, talk through some implementation details and provide you with a customizable library. The library is production ready and can be integrated with your system in under a day. It’s called SuperTokens.

Suggested Flow

Rotating refresh tokens with short-lived access tokens
managing user sessions using rotating refresh tokens

The table below compares the different storage mechanisms across all the various relevant properties. Note that ‘browser storage’ can actually be either local or session storage, IndexedDB or Web SQL.

Damage Analysis
The critical auth token is perpetually exposed over two attack surfaces, the frontend, and the backend and occasionally exposed over transit.

Effect of stolen auth tokens:
Access token stolen: The attacker will have unauthorised access for a short period of time (until token expiry)

Refresh token stolen: Detection of theft will enable the stolen refresh token to be invalidated, limiting the damage to a short period of time

Detection of theft:
Access token stolen: This theft may only be detected through the use of heuristic algorithms or if the user notifies the provider / developer of the service.

Refresh token stolen: Detection of theft will be possible as long as both the attacker and victim use the refresh token at least once post the attack. This is illustrated through an example below.

Once detected:
Access tokens need not be revoked since they are short lived. However, if needed, Opaque access tokens can be revoked by removing them from the database.

Refresh tokens can be revoked easily by removing it from the database.

That summarizes the discussion of the conceptual flow. Below, are some additional pointers to keep in mind for readers that would like to implement this flow on their own. Alternatively, we have an open source implementation of this flow available on Github.

Notes for implementation

  1. The backend invalidates previous tokens when it generates a new pair. In the situation where the frontend does not receive the new tokens (for whatever reason), it will continue to use the previous invalidated ones — resulting in the user being logged out. To prevent this, the backend should invalidate the previous tokens only when the frontend uses the new tokens — confirming its successful receipt.
  2. The system generates a new, different refresh token (RT) each time a valid RT is used. To prevent false positives (an indication of theft) and user logouts, one must factor in race conditions that can occur on the frontend[2].
  3. If a refresh token is revoked, then ideally its access token should also be revoked.
  4. Detection of refresh token theft does not require the database to explicitly store invalidated tokens. This can be achieved through structuring the refresh tokens using parent-child hierarchies (see Github implementation).
  5. Implementations with JWT access tokens can be as scalable, in terms of space and time complexity, as session flow 5 in part 1. We only need to store one refresh token per logged in user per device in the database.

That concludes the bulk of the matter we have on session management. Below you will find a GitHub repository with the source code that deals with all of the implementation issues. It is highly customizable to your requirements and can be quickly integrated into your system. It is also very secure in terms of prevention and detection of token theft. We’d love to know what you think of it — please do leave a comment or email us.

SuperTokens Library

We promise to support our library (fix bugs, address issues, add features and update documentation) and be responsive (via SO, email etc).

To show some additional love to our early readers, we’re offering the following dedicated support:

Please visit our documentation page to find the correct library for your technical stack.

Final conclusions and recommendations

Building a production-ready session management solution is nontrivial. It requires deep knowledge and is expensive in terms of time and money. Many developers do not prioritize session management — leading to suboptimal, unsecured systems in production.

We’ve discussed various session flows in these two posts. Depending on the requirements, one flow might be better suited than the others. In general, our recommendation would be the following:

For services that deal with very sensitive data (eg: a stock trading platform or something like Ashley Madison), security may take precedence over user experience. The ideal flow here would be to use our flow with short lived refresh tokens and shorter lived Opaque access tokens. The expiry time of a refresh token would depend on the amount of time you in which you would log out a user due to inactivity (Let’s call this time T). Each time a refresh token is used, the new token will be alive for time T. You may also want to have a hard limit on the lifetime of an entire session. That is, regardless of user activity, the session would expire in this amount of time. This would be estimated, for example, based on how long you expect users to be on your service in a given day.

For all other services, use our flow with JWT access tokens (for easier scalability) and long lived refresh tokens. You can also use blacklisting to instantly revoke access tokens (this would increase the time per API, but you would save on space in comparison to using Opaque access tokens). However, if you do not want to rely on one shared key for all your authentication (even if that key keeps changing), or if saving network bandwidth is of priority, then use Opaque access tokens. Additionally, security can be improved through the use of 2-factor authentication or passwordless login methods. The latter has the benefit of not requiring users to remember yet another password.

And that’s it! Please do let us know what you thought while reading this through the comments or by emailing us here. We hope this was useful.


race condition in session management