PingGateway sessions

PingGateway uses sessions to group requests from a user-agent or other source and to collect and share information across the requests.

PingGateway supports in-memory and JWT-based sessions.

For in-memory sessions, PingGateway stores the session data in memory (default). It sets a session cookie on the user-agent that references the session.
For JSON Web Token (JWT-based) sessions, the user-agent stores the session data. PingGateway puts the session data in a JWT stored as one or more session cookies on the user-agent.

By default, PingGateway uses different session cookie names for administrative and non-administrative connections.

Handlers and filters can access session data through the SessionContext.

Session sharing is not thread-safe, so it is not suitable for concurrent exchanges.

In-memory and JWT-based sessions
Feature	In-memory sessions	JWT-based sessions
Cookie size	Unlimited	The maximum size of the JWT session cookie for a user-agent is 4 KBytes. If the cookie exceeds this size, PingGateway automatically splits it into multiple cookies.
Default session cookie name	`IG_ADMIN_SESSIONID` (administrative connections) `IG_SESSIONID` (other connections)	`openig-jwt-session`
Data types the session can store	All types	JSON-compatible types, such as strings, numbers, booleans, null, and arrays, lists, and maps containing only JSON-compatible types.
Session sharing between PingGateway servers for load balancing and failover	Possible using session stickiness	Possible because the session is a cookie on the user-agent; PingGateway servers must share any encryption keys.
Risk of data inconsistency when simultaneous requests modify the content of a session	Low because PingGateway stores the session content for all exchanges. Processing is not thread-safe.	Higher because the session content is reconstructed from the JWT for each request. Concurrent exchanges don’t have the same content.

In-memory sessions

PingGateway uses in-memory sessions by default.

To configure sessions, use an InMemorySessionManager as the "session" in the AdminHttpApplication (admin.json) for administrative requests and the GatewayHttpApplication (config.json ) or individual Route for other requests.

The default session duration is 30 minutes. Even if the session is empty, the session remains usable until the timeout.

PingGateway can store any object type in an in-memory session.

Because PingGateway stores in-memory session content and shares it across all exchanges, simultaneous requests can update the session with low risk of the data becoming inconsistent. Sessions aren’t thread-safe, however; different requests can simultaneously read and modify a shared session.

JWT-based sessions

To configure JWT-based sessions, use a JwtSessionManager for the "session" in the AdminHttpApplication (admin.json) for administrative requests and the GatewayHttpApplication (config.json ) or individual Route for other requests.

PingGateway serializes session information as a JWT that is encrypted using authenticated encryption and optionally compressed. PingGateway stores the JWT in one or more session cookies on the user-agent. The JWT contains session attributes as JSON with a marker for the session timeout:

PingGateway can only serialize JSON-compatible types in JWT session cookies.
The maximum size of the JWT session cookie for a user-agent is 4 KBytes. If the cookie exceeds this size, PingGateway automatically splits it into multiple cookies.
When PingGateway serializes an empty session, it marks the supporting cookie as expired, so the user-agent effectively discards it.

To prevent PingGateway from cleaning up empty session cookies, add information to the session context with an AssignmentFilter.

PingGateway manages JWT-based sessions as follows:

When a request enters a route using JWT-based sessions PingGateway:
- Creates the SessionContext.
- Verifies the cookie signature.
- Decrypts the content of the cookie.
- Checks the current date is before the session timeout.
As the request passes through the filters and handlers in the route, the filters and handlers can read and modify the session content.
When the request returns to the point where the session was created, such the entrance to a route or config.json, PingGateway updates the cookie as follows:
- If the session content has changed, PingGateway:
  - Serializes the session.
  - Creates one or more new JWT session cookies with the new content.
  - Encrypts the cookies using authenticated encryption.
  - Assigns the cookies an appropriate expiration time.
  - Returns the cookies in the response.
- If the session is empty, PingGateway:
  - Deletes the session.
  - Creates a new expired JWT session cookie
  - Returns the cookie in the response.
- If the session content has not changed, PingGateway does nothing.

Because the session content is stored on the user-agent, PingGateway servers can easily share JWT-based sessions. The user-agent returns the JWT cookies and any PingGateway server can unpack and use the session content.

When PingGateway updates JWT-based sessions in simultaneous requests, there is a high risk of the data becoming inconsistent. PingGateway reconstructs the session content for each exchange. Concurrent exchanges don’t have the same content. PingGateway doesn’t share sessions across requests. Each request has its own session objects that it modifies as necessary, writing its own session to the session cookie regardless of what other requests do.

Session stickiness

Session stickiness helps ensure a client request goes to the server holding the original session data. With session stickiness, a load balancer in front of multiple PingGateway servers sends all requests from the same client session to the same server.

How you configure session stickiness depends on your load balancer.

Configure session stickiness whenever PingGateway stores session data attached to a server-side context. For example, configure session stickiness when using in-memory sessions and multiple PingGateway servers.