Skip to main content
important

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

Make the token structure customizable

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:
2023-05-11

Context and Problem Statement#

When building the OAuth2 access & id_tokens we can make the token structure/contents customizable.

Considered Options#

  • Do not allow customisation of claims
  • Make the token structure customizable

Decision Outcome#

Chosen option: Make the token structure customizable

  • Fits into our model: other similar things are customizable
  • Enables all use-cases/custom scopes

Further considerations:

  • We can add createNewAccessToken and createNewIdToken to the overrideable interface of the OAuth2 recipe.
    • These functions will get all information we have about the current flow (requested scopes, user info, etc)
    • These functions will get the "default" access token payload as a parameter. This will include:
      • all default claims (e.g.: sub)
      • other claims if we choose to add default implementation for other scopes (e.g.: supertokens.email could add the user email and verification status into the id_token)
    • These functions will NOT be affected by whatever is added to createNewSession (in the Session recipe)
  • We will recommend people to add third-party integration (i.e.: hasura) related claims into the access token by overriding createNewAccessToken
    • They fit the resource server role in OAuth2.
    • This can be done based on the requested/approved scopes in the override
    • Competitors go with either this or adding custom claims into the id_token.
    • Both tokens are customizable, so both solutions work. This is mostly about recommendation
    • Users should use the access token (and not the id token) to query the oauth server as well as their own backend. Their own backend includes third party services like hasura, so it makes sense to recommend people to add custom claims into the access token and not id token.

Pros and Cons of the Options#

Only standard claims#

  • Smaller interface & Less docs
  • Custom claims could require embedding information in these tokens

    • Make the token structure customizable#

  • Fits into our model: other similar things are customizable
  • Enables all use-cases/custom scopes
  • Bigger interface and more docs
    • Looking for older version of the documentation?
    Which UI do you use?
    Custom UI
    Pre built UI