Skip to main content

Implement anonymous sessions

Overview

With anonymous sessions, you can keep track of user's action / data before they login, and then transfer that data to their post login session.

Anonymous sessions have different properties than regular, logged in sessions:

  • The userID of anonymous sessions doesn't matter
  • The security constraints on anonymous sessions are lesser than regular sessions, as you would want users to log in before doing anything sensitive anyway.
  • Each visitor that visits your app / website gets an anonymous session if they don't have one previously. This does not require them to log in.
  • Anonymous sessions are not stored in the database to avoid the risk of flooding the database with sessions that are not useful to the app.

Given the different characteristics of anonymous sessions, using a simple, long lived JWT is a perfect use case. They can store any information about the user's activity, and they don't occupy any database space either.

Steps

1. Create the JWT

Start by creating a JWT like in the next example:

import Session from "supertokens-node/recipe/session"

async function createAnonymousJWT(payload: any) {
let jwtResponse = await Session.createJWT({
key: "value",
// more payload...
}, 315360000); // 10 years lifetime
if (jwtResponse.status === "OK") {
// Send JWT as Authorization header to M2
return jwtResponse.jwt;
}
throw new Error("Unable to create JWT. Should never come here.")
}
  • As shown in the code above, you can add any payload you like to the JWT. You can even add a sub (userId) payload with a random UUID if you like, or some user ID with a prefix like "G-.." which indicates this is a guest user ID.
  • You could create your own application middleware which inspects the request and auto adds a JWT to it in the response cookies. This way, whenever a user visits your website and makes an API call, they get a JWT in their cookies, and you can use that JWT to track their activity.

2. Send the JWT to the client

After creating the JWT, you can send it to a user as a cookie. This way you can use it to track the activity during a session.

Verify the JWT

To check if an anonymous session is valid read through the manual JWT verification section. On thing to note here is that in the section about verification using the public key string, you do not need to set useDynamicAccessTokenSigningKey to true. The token creation process in this scenario uses the static signing key (kid starting the s-..) by default.

caution

You cannot use the verifySession or getSession functions to verify JWTs from anonymous sessions. The verifySession and getSession check for the presence of certain claims in the JWT (sessionHandle, refreshTokenHash etc...) that the Session recipe adds for authenticated users.

3. Transfer the data to a logged in session

The idea here is to override the Session recipe on the backend. Whenever the user logs in or signs up, the data from the anonymous session transfers to the logged-in session.

The override attempts to read the request header cookie to get the JWT. It assumes that you have added it to the cookies, verifies it, and then adds the payload to the logged-in session.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
supertokens: {
connectionURI: "...",
},
appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "..."
},
recipeList: [
// ...
Session.init({
override: {
functions: (originalImplementation) => {
return {
...originalImplementation,
createNewSession: async function (input) {
let userId = input.userId;

const request = SuperTokens.getRequestFromUserContext(input.userContext);

let jwt: string | undefined
let jwtPayload = {}

if (request !== undefined) {
jwt = request.getCookieValue("jwt");
} else {
/**
* This is possible if the function is triggered from the user management dashboard
*
* In this case because we cannot read the JWT, we create a session without the custom
* payload properties
*/
}

if (jwt !== undefined) {
// verify JWT using a JWT verification library..

jwtPayload = { /* ... get from decoded jwt ... */};
}

// This goes in the access token, and is available to read on the frontend.
input.accessTokenPayload = {
...input.accessTokenPayload,
...jwtPayload
};

return originalImplementation.createNewSession(input);
},
};
},
},
})
]
});
  • In the above code snippet, the system reads the JWT from the request header cookie. If it exists, it verifies it and then adds the payload to the logged-in session.
  • If the JWT doesn't exist, or if the system cannot verify it, it would be safe to ignore it and create the logged-in session anyway.
  • We assume that the you have saved the JWT in the cookies in with the key of jwt. But if not, you can remove the JWT from the request based on how you have saved it. You can even read the headers from the request.