Validating and Maintaining Application Sessions

Overview

In a backend server integration, your application must validate the user's session on every request to a protected API called from the browser. This ensures that only authenticated users can access protected resources through their application session.

Session validation is typically handled by authentication middleware that runs before your API's business logic. The middleware is responsible for:

• Validating the Application Session: Verifying that the request contains a valid, unexpired application session.
• Refreshing Access Tokens: Obtaining a new access token when the existing token has expired, if a refresh token is available.
• Maintaining Session Expiration: Extending the application's session expiration window when the user is active.
• Handling Invalid Sessions: Rejecting unauthenticated requests with an appropriate HTTP response.

For more information about how application sessions are created and stored, see the Session Management documentation.

Validating the Application Session

When the frontend makes a request to a protected backend API, the browser automatically includes the application's session cookie. Before processing the request, the backend must validate the session to determine whether the user is authenticated.

The authentication middleware should perform the following steps:

1. Retrieve the Session Cookie: Extract the application session cookie from the incoming request.

2. Load the Application Session: Retrieve the session data associated with the cookie. For cookie-based sessions, decrypt and verify the cookie's integrity. For server-side sessions, use the session identifier to retrieve the session data from the session store.

3. Validate the Session: Verify that the session exists, has not expired, and contains the required authentication information, such as the authenticated user ID and tenant ID.

4. Refresh the Access Token if Necessary: If the access token has expired or is nearing expiration, use the refresh token to obtain a new access token from Wristband's Token Endpoint. Update the session with the new token information.

5. Extend the Session Expiration: If the session is valid and rolling expiration is enabled, update the session's expiration time and persist the changes.

6. Continue Processing the Request: Allow the request to proceed to the API's business logic.

If the session is missing, expired, or invalid, the middleware should reject the request with a 401 Unauthorized response.

Maintaining Session Expiration

Application sessions typically have an expiration time that determines how long a user can remain authenticated.

One common approach is to use rolling session expiration, also known as sliding expiration. With this approach, the session's expiration window is extended whenever the user makes an authenticated request.

Rolling Session Expiration

With rolling expiration, the session's expiration time is reset to the current time plus the configured session duration.

For example, consider an application configured with a 60-minute session duration:

1. At 1:00 PM, the user logs in and the application creates a session that expires at 2:00 PM.
2. At 1:30 PM, the user makes a request to a protected API.
3. The authentication middleware validates the session and extends its expiration to 2:30 PM.
4. If the user makes no further requests, the session expires at 2:30 PM.

This approach allows active users to remain authenticated without requiring them to log in repeatedly, while automatically expiring sessions after a period of inactivity.

To implement rolling expiration, your backend must update the session's expiration time and persist the updated session whenever an authenticated request is processed.

• Cookie-Based Sessions: Re-encrypt and save the session data, then return an updated session cookie with a refreshed expiration time.
• Server-Side Sessions: Update the session's expiration time in the session store and refresh the session cookie's expiration when necessary.

Application Session vs. Wristband Authentication Session Expiration

Your application's session expiration is independent of the Wristband authentication session.

Extending your application's session expiration does not extend the Wristband authentication session.

Additionally, if your application enforces an absolute session lifetime, rolling expiration must not extend the session beyond that limit.

For more information, see the Sessions documentation.

Refreshing Expired Access Tokens

An application's session can remain valid even after its associated access token expires.

When a protected API requires a valid access token, the authentication middleware should check the token's expiration time before allowing the request to proceed.

If the access token has expired or is nearing expiration, the backend can use the refresh token stored in the application session to request a new access token from Wristband's Token Endpoint.

If the refresh succeeds, the middleware should:

1. Update the session with the new access token and expiration time.
2. Persist the updated session.
3. Continue processing the original API request.

If the refresh token is expired, revoked, or otherwise invalid, the backend should invalidate the application session and return a 401 Unauthorized response.

For more information, see the Refreshing Access Tokens documentation.

Handling Invalid Sessions

When a request does not contain a valid application session, the backend must reject the request before executing the protected API's business logic.

The following table describes the recommended behavior for common authentication failures:

Handling Authentication Failures in the Frontend

When the frontend receives a 401 Unauthorized response, it can redirect the user to your application's Login Endpoint to initiate a new authentication flow.

For implementation examples using Axios and Fetch, see the Handling 401 Unauthorized API Responses documentation.