Home

User Session (JWT/Authorization)

Understand how to onboard with the Openfort signer solution.

What is a session?#

A session is created when a user signs in. By default, it lasts 1 and a user can have an unlimited number of active sessions on as many devices.

A session is represented by the Supabase Auth access token in the form of a JWT, and a refresh token which is a unique string.

Access tokens are designed to be short lived, usually between 5 minutes and 1 hour while refresh tokens never expire but can only be used once. You can exchange a refresh token only once to get a new access and refresh token pair.

This process is called refreshing the session.

A session terminates, depending on configuration, when:

  • The user clicks sign out.
  • The user changes their password or performs a security sensitive action.
  • It times out due to inactivity.
  • It reaches its maximum lifetime.
  • A user signs in on another device.

Access token format#

Openfort access tokens are JSON Web Tokens (JWT), signed with the ES256 algorithm. These JWTs include certain information about the user in its claims, namely:

  • sid is the user’s current session ID
  • sub is the user’s player Id
  • iss is the token issuer, which should always be openfort.xyz
  • aud is your Openfort app ID
  • iat is the timestamp of when the JWT was issued
  • exp is the timestamp of when the JWT will expire and is no longer valid. This is generally 1 hour after the JWT was issued.

Authorizing requests with the access token#

To include the current user's access token on requests to your backend, follow the instructions below. Make sure to follow the appropriate instructions if your app uses local storage.


_12
import {getAccessToken} from '@openfort/openfort-js';
_12
_12
const authToken = await getAccessToken();
_12
_12
const response = await fetch(<your-api-route>, {
_12
method: <your-request-method>
_12
body: <your-request-body>,
_12
headers: {
_12
'Authorization': `Bearer ${accessToken}`,
_12
/* Add any other request headers you'd like */
_12
}
_12
});

Verifying the user's access token#

Once you've obtained the user's access token from a request, you should verify the token against Openfort's verification key for your app to confirm that the token was issued by Openfort and the user referenced by the player Id in the token is truly authenticated.

The access token is a standard ES256 JWT and the verification key is a standard Ed25519 public key. You can verify the access token against the public key using the official supported libraries library or using a third-party library for managing tokens.


_10
import Openfort from "@openfort/openfort-node";
_10
const openfort = openfort(process.env.OPENFORT_SK);
_10
_10
const authSession = openfort.iam.verifyAuthToken(token);

Log out a user#

When your user logs out, call logout() to remove them from the browser session and any objects from localStorage.


_10
import Openfort from "@openfort/openfort-js";
_10
const openfort = Openfort('YOUR_OPENFORT_PUBLISHABLE_KEY');
_10
_10
async function logout() {
_10
await openfort.logout();
_10
}

Upon sign out, all refresh tokens and potentially other database objects related to the affected sessions are destroyed and the client library removes the session stored in the browser.

caution

Access tokens of revoked sessions remain valid until their expiry time, encoded in the exp claim. The user won't be immediately logged out and will only be logged out when the access token expires.