Sessions

For this section, we'll define a session as a period during which a user interacts with an application after successfully logging in. It begins when the user logs in and ends when they log out or when the session expires due to inactivity or other defined criteria. During this session, the user can access and use the application without needing to repeatedly enter their login credentials.

In Wristband, there are two separate notions of a session: authentication sessions and application sessions.

Authentication (Auth) Session

Wristband maintains an authentication (auth) session for any user who logs into your application, ensuring a streamlined SSO experience for any inbound SSO integrations. Authentication sessions are stored in cookies in the browser and are associated with the following domains:

• Multi-tenant applications: Authentication session cookies are associated with the Wristband tenant vanity domain, or with the tenant custom domain if custom domains are active for your application.
• Single-tenant applications: Authentication session cookies are associated with the Wristband application vanity domain, or with the application custom domain if custom domains are active for your application.

When an auth session cookie is present, the user will bypass the login screen when calling Wristband's Authorize API and immediately be logged into the application.

The following Wristband workflows lead to an auth session being created:

• Signup (with Email Verification workflow policy)
• User Activation
• Login
• New User Invite
• Existing User Invite
• Forgot Password (with Immediate Login workflow policy)

Authentication Prompt Options

The prompt parameter is an optional parameter that you can pass in an authorization request when redirecting to Wristband's Authorize API. It can control the behavior of the login process by telling Wristband how to handle the user's interaction during the authorization code flow. The following prompt values are supported in Wristband:

By default, when the prompt parameter is omitted from the authorization request, the following rules are applied:

• If an auth session is not present or invalid, then the user will be redirected to the login page.
• If the auth session is both present and valid, then automatically log the user into the application. There is one exception: when a max age value was specified in the authorization request and the max age time has elapsed. In that case, the user will be redirected to the login page.

Authentication Max Age

Your application can also optionally specify a max_age parameter when making an authorization request to Wristband. This controls the maximum authentication age by specifying the allowable elapsed time in seconds since the last time the user was actively authenticated. If the elapsed time is greater than this value, then the end user will be redirected to the login page to reauthenticate.

Auth Session Expiration

Auth session expiration, also known as session timeout, refers to the automatic termination of a user's authenticated session with Wristband after a predefined period of inactivity or a specific duration. When the auth session expires, the user is required to log in again to access your application.

Wristband provides two settings you can configure to determine the duration of the expiration window: idle expiration time and absolute expiration time.

Idle Expiration Time

Idle expiration time, also known as inactivity timeout, refers to the period of inactivity by a user within a Wristband auth session. Inactivity means that the user has not interacted with Wristband's Authorize API. If the user remains idle for a specific duration, the auth session expires, and they will need to reauthenticate on the login page the next time the application redirects to the Authorize API. This mitigates the risk of unauthorized access if a user leaves their session unattended, especially in scenarios where others may have access to their device.

The maximum possible idle expiration time allowed is 90 days, and the exact value can be configured in the Wristband dashboard.

Your application can extend the duration of the idle expiration window for any user's active authentication session by interacting with Wristband's Authorize API. For example, if your application stores access and refresh tokens in a session cookie, and both tokens expired, then the next time your user tried to perform an action that required a token, the application would initiate a new authorization code flow with Wristband to get new tokens. Since the user's auth session with Wristband exists and has not exceeded the idle expiration timeout window, Wristband would allow the user to bypass entering their credentials and send the user back into the application with the new tokens.

Absolute Expiration Time

Absolute expiration time, also referred to as maximum session duration, is the maximum amount of time a user's auth session with Wristband is allowed to remain active, regardless of any user activity or interaction with Wristband's Authorize API. Once this predefined duration is reached, the session expires, and the user is required to log in again.

The primary purpose of this absolute timeout is to prevent the potential for indefinitely long sessions and reduce the risk of unauthorized access. The maximum possible absolute expiration time allowed is 365 days, and the exact value can be configured in the Wristband dashboard.

📘

Note About Idle and Absolute Expirations

When configuring auth session expiration times in the Wristband dashboard, the idle expiration time must always be set to a value that is lower than the absolute expiration time.

Application Session

Even though your application will use Wristband to authenticate users, your application should also keep track of the users that are logging in to your application. Your application can store and manage its own separate session independently of the Wristband auth session. This is called the application session. The typical data you would store and associate with an application session is:

• Access and refresh tokens (and optionally the ID token)
• Access token expiration time
• Some subset of user data for the currently logged-in user (i.e., userId, email, etc.)
• Some subset of tenant data for the tenant to which the logged-in user belongs (i.e., tenantId, tenantDomainName, etc.)

There is more data that you could associate with an application session, but that would be context-dependent on what your application is trying to accomplish.

There are multiple ways to handle storing and managing application sessions depending on the type of application.

Web Application Sessions

Web applications have some kind of backend server that interacts with the browser in some capacity. There are methods of managing application sessions for this type of application: client sessions or server sessions. For either method, there is an application session cookie involved. That cookie must have the following attributes set to be secure: HttpOnly; SameSite=<Lax|Strict>; Secure;.

Client-Side Session

Client-side sessions are where all of the application session data is stored inside the application session cookie. There are cases where applications, even if they do have a backend server, don't want to worry about storing state in an external data store. For those cases, you can store that application session data in a secure, HTTP-only cookie in the browser. This makes your application sessions stateless since you don't have to rely on the backend completely. This is particularly useful in serverless architectures where you're trying to reduce your backend dependencies. However, the backend must encrypt that data before storing it in the cookie.

When an authenticated user is interacting with an application that leverages client-side application sessions, each API call to the backend will pass along that encrypted application session cookie. The backend will then decrypt the cookie to access the data inside and manage access tokens.

Server-Side Session

Server-side sessions are where all of the application session data is stored in an external datastore (such as Redis, for example), and only the session UUID is stored with the application session cookie. The server would still need to pass back the encrypted session cookie to the browser after the user authenticates, but the contents of the cookie in this case would be a session identifier that the server can use to perform session lookups. This is useful for applications with very large application sessions that can't fit within the 4KB size limit of cookies.

When an authenticated user interacts with an application that utilizes server-side application sessions, each API call to the backend will transmit the encrypted application session cookie. The backend will then decrypt the cookie, take the session identifier from the cookie, and look up the application session data from the datastore. From there, the backend can access the data and manage access tokens.

Single Page Application Sessions

Single-page applications can store application session data in locations such as inside application memory, in the browser's local storage/session storage, or in the browser's indexed DB. This is an acceptable approach in some cases, though it is less secure than having an application session cookie. We highly recommend that your single-page application also has a backend server behind it, if possible, to maximize security for your application.

Native Application Sessions

For desktop and mobile applications, it is common to store access and refresh tokens in the platform-respective credential stores (i.e., Windows Credential Manager, macOS Keychain, Android Keystore, etc.). Any other application session data of interest outside of the tokens could simply be stored in application memory.

Ending Sessions on Logout

When an authenticated user logs out of your application, the application should destroy both the authentication session and application session.

Cleanup the Application Session

How you clean up the application session depends on the type of application that you are developing.

Cleanup for Web Applications

Regardless of whether the application session is a client-side session or a server-side session, the application session cookie should be destroyed by the backend server. Additionally, if the application session is stored server-side, a delete session operation should be performed against the external datastore where the session lives.

Cleanup for Single Page Applications

If the application is a single-page application, then all application session data stored in memory/local storage/etc. should be deleted.

Cleanup for Native Applications

If the application is a native application, then all application session data stored in the keychain/keystore should be deleted.

Revoke Refresh Tokens

If the application has a refresh token for the authenticated user, the application should call the Wristband Revoke Token API to revoke the refresh token for that user.

Cleanup the Wristband Authentication Session

The application should redirect to the Wristband Logout API, where the Wristband authentication session for that user will be destroyed.