Session Management

Improve security and user experience by enabling refresh tokens.

Passage supports a variety of session management capabilities that improve security and end user experience by enabling long-lived sessions (for mobile apps and PWAs) and token revocation support.

Stateless Session Management

This is the default setting for new applications in Passage. For stateless sessions, there is only a single configuration option available - the token expiration time. To change this setting, visit Authentication --> Session Settings in the Passage Console.

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 mobile applications) can be difficult, if not impossible, to implement.

Refresh Tokens

Passage also supports a hybrid session management solution that provide 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 and grants users access to your application. It is designed to be 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.

See Refresh Tokens to learn how to configure and use refresh tokens in your application.

Behind the scenes, Passage isn’t storing these sensitive tokens in our database. We store a cryptographic hash (HMAC) that allows us to validate an authentic data signature without holding any additional data linked to your customer 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.

Suggested Token Lifetimes

Here are some suggestions based on the type of application:

  • For most consumer applications, you can probably use our defaults: 1 hour auth token lifetime, 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 lifetime, 24 hour absolute timeout, 30 minute inactivity timeout.

  • For long lived applications like mobile, we recommend a 1 hour auth token lifetime, 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.

Last updated