We know that session management can have a huge impact on user experience and customer retention. Imagine if you had to re-authenticate to your most commonly used apps every few minutes?! With that in mind, Passage has added support for long-lived sessions and token revocation, enabling a better user experience and improved security. These additional session management capabilities allow for greater security while providing long-lived sessions often needed for PWA and mobile apps.

Stateless Session Management

Stateless session management means that the session token is not stored anywhere on the server (the Passage server or your application server). This is done in the form of JSON Web Tokens (JWTs), which are JSON-formatted tokens that are cryptographically signed by Passage to ensure they have not been tampered with. To verify a session, an application can use the public key provided by Passage to check the signature on the token. If it passes, the data in the JWT can be trusted.

JWTs provide great session security with low latency because they can be verified without contacting the Passage API. The downside to stateless sessions is that revocation and long lived sessions (common in PWAs) can be difficult, if not impossible, to implement.

Refresh Tokens

That's where refresh tokens come in. Passage now supports a hybrid session management solution that provides the low latency of stateless JWT-based sessions, with the revocation capabilities of stateful sessions.

Here’s how it works: When a user logs into your application with Passage, they are issued an auth token and a refresh token. The auth token is a stateless JWT that can be verified using a public key from Passage. It is designed to be a short-lived. The refresh token is a long-lived stateful token that can be used to get a new auth token when one has expired.

Behind the scenes, Passage isn’t storing these tokens in our database. We store an HMAC of the tokens to ensure that we never hold any data that can be used to access your customer’s accounts.

Refresh Token Rotation

To provide additional security out of the box, Passage has also introduced refresh token rotation that is enabled by default whenever you use refresh tokens. Rotation means that every time a refresh token is used to get a new auth token, a new refresh token is also issued and the original refresh token is invalidated.

The main reason for this is to prevent replay attacks - someone gaining access to the original refresh token and trying to use it to get an auth token. Passage provides an additional layer of security by detecting when an old refresh token has been compromised, invalidating all tokens related to the compromised refresh token, and requiring the user to re-authenticate.

Configuration in Passage

Here's how to use it: Refresh tokens are disabled by default. To enable this functionality visit Authentication → Session Management in the Passage Console. From there, choose your session timeouts.

• The auth token lifetime should be short when enabling refresh tokens, from seconds to about 10 minutes.
• The absolute expiration corresponds to the expiration of a refresh token and should be the maximum session length that you want to enforce.
• The inactivity timeout will end inactive sessions and require users to re-authentication on next visit.

Here are some suggestions based on the type of application:

• For most consumer applications, you can probably use our defaults: 1 hour auth token, 30 day absolute lifetime, and 5 day inactivity timeout.
• For applications requiring higher security due to sensitive data or transactions, consider lowering the thresholds to 5 minute auth token, 24 hour absolute timeout, 30 minute inactivity timeout.
• For long lived applications like mobile, we recommend a 1 hour auth token, 180 day absolute lifetime, and no inactivity timeout. These are typically apps where users may not log in often, but you don't want to make them re-authenticate.

Lastly, if this doesn't meet your requirements for fully stateful sessions, you could instead exchange a Passage JWT for a session token from your application. Then you can manage the session token database or cache, ensure revocation happens immediately, and keep latency low by using caching and reducing external network requests.

Conclusion

There are a lot of different variables that go into designing session management that is secure and doesn’t add friction for your users. Feel free to reach out if you’d like some more information on the options and recommendations above. We are always around in Discord or via email at support@passage.id.

‍