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 hour and a user can have an unlimited number of active sessions.

A session is represented by the Openfort 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 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.

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

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.

import Openfort from "@openfort/openfort-node";
const openfort = openfort(process.env.OPENFORT_SK);
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.

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

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.