Session management

Sessions track user interactions with a resource within a given time frame. For example, the resource may be an application (app), or identity provider (IdP)—a service that creates, manages, and stores digital identities like Transmit Security. By managing sessions, you can allow your users to securely access your application, without needing to reauthenticate for every request. This provides an enhanced identity experience that doesn't compromise on security.

Application sessions

An application session (also known as a local session) is created by the app when the user logs in. By default, a session ends when the user leaves the website or closes the browser. However, an app can extend the session by storing information in a cookie so the user won't need to authenticate each time they return. The session lifetime is managed by the app. Once the application session is over, the user must reauthenticate.

IdP sessions

An IdP session is created by Transmit Security when a user logs into the app. Each IdP session is bound to a specific user. A cookie is used to track the IdP session. The IdP session is active until it expires, unless terminated before (see Session lifetime).

Typically, both the application session and IdP session are used to determine if the user is authenticated whenever access is requested. Once the application session is over, authentication is always required. If both sessions are active, the user may still need to reauthenticate, depending on how long has passed since their last authentication. Once the IdP session is over, the app may rely on the current authentication until it expires, but access can no longer be extended without reauthentication.

Access and refresh tokens

Every user authentication creates a new session, and returns an access token and refresh token. These tokens are bound to the session, user, and client. A valid access token is required to authorize user access to the application, even if there's an active session. The access token (JWT) contains the expiration, user ID, and authorization information—including which resource can be accessed and the user's roles to determine their permissions.

Access tokens are short-lived, but can be refreshed as needed. If the access token expires, the refresh token can be used to retrieve a new access token. Since refresh tokens are rotated upon each use, a new refresh token is returned too. By default, access tokens expire after 1 hour, while refresh tokens expire after 2 weeks. However, these expirations can be customized by creating resources.

In more practical terms, the first access token corresponds to the user's first login of the session. Suppose the user then leaves the website and returns a couple hours later. The access token is now expired. So the refresh token is used to refresh their access, without requiring the user to reauthenticate. Now suppose the user visits the website again only after a month. This time the refresh token is expired so there's no way to gain access without logging in again.

Session lifetime

The session lifetime is the maximum amount of time a session can be active, and is set using session expiration. This is also the absolute lifetime of the refresh token, since new access tokens can no longer be retrieved once the session expires. The default session expiration is 1 year, but the expiration can be customized by creating resources. Creating resources also allows you to set different expirations based on the resource, such as shorter sessions for more sensitive resources like a payment page.

A session is terminated in several ways: if the end-user initiates an IdP logout using the Logout API or if an admin revokes the session using the Session Revocation API. A logout will delete all the sessions for the relevant user. The session revocation call will delete all the sessions for the specified user, as well as revoke the corresponding refresh tokens.

Session cookie

Typically, a session cookie is used to store the information needed to obtain user access and authorization, without requiring the user to authenticate. Here are some security guidelines when creating applications sessions using cookies: