important

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Access token claims should be renamed to match JWT standards

Status

This is just a proposal so far, it hasn't been accepted and needs further discussion.

Status:: proposed
Deciders:: rishabhpoddar, porcellus
Proposed by:: porcellus
Created:: 2022-12-06
Last updated:: 2023-01-02

Context and Problem Statement#

We want to make our access tokens into a standard JWT. This means we will need to add some new claims, but some of them are already present with non-standard names.

Considered Options#

Duplicate claims
Rename claims

Decision Outcome#

We should rename claims to match the standard

We need to match the standard to enable our users to use a jwt verification library on backends without our SDKs.
We should not duplicate claims (if avoidable at all), because that would inflate the access token.

We will flatten the access token structure and add user claims to the root level instead of the old userData claim. Renamed claims:

userId -> sub
expiryTime -> exp (needs to be changed to be in seconds)
timeCreated -> iat (needs to be changed to be in seconds)

Unchanged claim names:

sessionHandle
refreshTokenHash1
parentRefreshTokenHash1
antiCsrfToken

We do not need to add:

aud: We could add a string to indicate it's a supertokens access token, but we'd not gain too much since we already do validation based on the object shape and we'd have to make this configurable anyway.
iss: although this is widely used, it's optional (as per the rfc) and we don't have meaningful information to put here.
nbf: this could contain timeCreated but since we do not issue tokens with nbf in the future this is not useful.
jti: since this has to be globally unique (even among JWTs), we do not have any id to store here.

While optional, we should add the kid (Key ID) Header Parameter

We also need to throw if the user tries to add these claims into a custom payload (checked on the core level), since overwriting these could be a security risk. (e.g.: changing the userId of the session and extending the validity)