Session Management

Overview

After a user authenticates with Wristband, your application needs to maintain their authenticated state across subsequent requests. In a backend server integration, this is typically accomplished using an application session stored in a browser cookie.

There are two common approaches to managing application sessions: cookie-based sessions and server-side sessions. Both use cookies to identify authenticated users, but they differ in where session data is stored and how it is managed.

Managing Application Sessions

When a user successfully authenticates, your application's Callback Endpoint exchanges the authorization code for tokens and creates an application session. This session maintains the user's authenticated state, allowing subsequent requests to be processed without requiring the user to log in again.

An application session typically contains the following information:

• User ID: Identifies the authenticated user.
• Tenant ID: Identifies the tenant the user is authenticated with.
• Access Token: Used to authenticate requests to Wristband APIs or your application's backend APIs.
• Refresh Token: Used to obtain new access tokens without requiring the user to reauthenticate.
• Access Token Expiration: Indicates when the access token expires and needs to be refreshed.

The application session is maintained by your backend server and is separate from the authentication session managed by Wristband.

Cookie-Based Sessions

Cookie-based sessions store the user's session data directly in a browser cookie. Each time the browser sends a request to your backend server, the session cookie is automatically included, allowing the server to retrieve the user's authenticated state.

Since session data is stored in the browser, the cookie must be encrypted and protected against tampering. This is especially important when the session contains sensitive information, such as access tokens and refresh tokens.

Advantages:

• No external datastore is required to persist sessions.
• Session data is available directly from the cookie, eliminating the need for additional datastore lookups.

Considerations:

• Browsers generally limit individual cookies to approximately 4 KB. Applications with larger sessions may need to use server-side storage.
• Sessions cannot be immediately revoked from the server without additional mechanisms, since session data is stored in the user's browser.

Although cookie-based sessions cannot be immediately invalidated from the server, refresh token revocation provides an alternative for achieving near-real-time session revocation.

Your backend server can check the access token's expiration time on each authenticated request and automatically refresh it when necessary. By revoking a user's refresh token, you prevent the application from obtaining new access tokens once the current access token expires. If access tokens are configured with short expiration times, this effectively limits how long a revoked session can remain active.

When the backend server attempts to refresh an access token using a revoked refresh token, Wristband rejects the request. The backend should then return a 401 Unauthorized response, allowing the frontend to initiate the appropriate session cleanup.

While this approach does not provide immediate session revocation, short-lived access tokens combined with refresh token revocation can provide near-real-time session invalidation without requiring a centralized session datastore.

Server-Side Sessions

Server-side sessions store the user's session data in an external datastore, such as Redis, rather than directly in the browser cookie.

Instead of containing the full session data, the browser cookie contains a session identifier. When the backend server receives a request, it uses this identifier to retrieve the corresponding session data from the datastore.

Advantages:

• Supports larger sessions without being constrained by browser cookie size limits.
• Provides greater control over session management, including the ability to immediately invalidate sessions by deleting them from the datastore.
• Keeps sensitive session data on the backend server rather than storing it in the browser.

Considerations:

• Requires an external datastore to persist session information.
• Introduces additional infrastructure complexity and potential latency when retrieving session data.

Securing the Session Cookie

Regardless of which session management approach you choose, your application should configure its session cookie with appropriate security attributes.

The following cookie attributes are recommended:

• HttpOnly: Prevents JavaScript running in the browser from accessing the session cookie, helping reduce the risk of session theft through cross-site scripting (XSS).
• Secure: Ensures the session cookie is only transmitted over HTTPS.
• SameSite: Controls whether the browser includes the session cookie in cross-site requests. Use Lax or Strict when possible to help protect against cross-site request forgery (CSRF).
• Path and Domain: Restrict where the browser sends the session cookie to avoid unnecessarily exposing it to other application paths or subdomains.

You should also configure an appropriate cookie expiration time based on your application's session security requirements.

Preventing Session Cookie Caching

Responses that create, update, or clear application session cookies should include appropriate cache-control headers to prevent browsers, CDNs, and intermediary proxies from caching session-related information.

We recommend including the following headers in these responses:

Cache-Control: no-store
Pragma: no-cache

• Cache-Control: no-store: Instructs browsers and intermediary caches not to store the response.
• Pragma: no-cache: Provides backward compatibility with older HTTP/1.0 caches.

These headers should be applied to responses that establish or modify application sessions, including your Callback Endpoint, Logout Endpoint, and protected APIs that update the application session cookie.

Clearing the Application Session on Logout

When a user logs out, your application's Logout Endpoint is responsible for terminating the application session. The cleanup process depends on whether you're using cookie-based or server-side sessions.

Cookie-Based Sessions

For cookie-based sessions, your backend server must clear the session cookie stored in the user's browser. This can be accomplished by returning a Set-Cookie header that sets the cookie's Max-Age to 0 and its value to an empty string.

When clearing the cookie, ensure that its Path and Domain attributes match those used when the cookie was originally created.

Server-Side Sessions

For server-side sessions, your backend server must perform two operations:

1. Delete the Session Data: Remove the user's session data from the external datastore, using the session identifier from the cookie.
2. Clear the Session Cookie: Return a Set-Cookie header that clears the session identifier cookie from the user's browser.

Once the application session has been cleared, subsequent requests to protected APIs will no longer have a valid application session and should receive a 401 Unauthorized response.

Accessing Session Data From the Frontend

In a backend server integration, the application's session cookie should be configured with the HttpOnly attribute. This prevents client-side JavaScript from directly accessing the cookie or its contents.

However, frontend applications often need access to certain session information, such as the authenticated user's identity or tenant information, to initialize their authentication context and display personalized content.

To support this, your backend server should expose a Session Endpoint that allows the frontend to retrieve the relevant session information.

The Session Endpoint performs the following steps:

1. Client Requests Session Data: The frontend sends a request to the application's Session Endpoint, automatically including the session cookie.
2. Backend Validates the Session: Authentication middleware retrieves and validates the session information using the session cookie.
3. Backend Returns Session Data: If the session is valid, the endpoint returns the session information needed by the frontend. Otherwise, it returns a 401 Unauthorized response.

The frontend can use this response to initialize its authentication context and determine whether the user is currently authenticated.