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.

Reserve scopes starting with supertokens.

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 creating scopes we can choose what to allow and/or reserve for special use

Considered Options#

  • Reserve some scopes
  • Allow all scopes

Decision Outcome#

Chosen option: Reserve some scopes (scopes starting with supertokens. + openid), because

  • It's future-proof
  • Doesn't block any usecase

Some scopes we've decided to reserve:

  • openid: this scope will add the id token to the token response. should be always allowed for all clients
  • supertokens.profile: access to email address (+ verification status), phone number and third party provider information
  • supertokens.roles: access to role information
  • supertokens.permissions: access to permission information

Based on the above scopes we will:

  • Add information mainly into the id token
  • Make this information available through the access token calling a user info endpoint
  • Not add these to the access token (although we will allow that to be customizable)
  • Do not add any information outside of the user id (and sessionHandle) without an appropriate scope, since adding PII should always be opt-in.
  • The main information content of the access token is contained in the scopes granted: these should be the main source of information when deciding if an operation is allowed or not. As an example: the user has an admin role, so their sessions can be used to delete users but this is not something they want to do through the forum client app. Keep in mind, that the client applications are usually not first-party, so permissions have to be carefully managed (e.g.: to mitigate a possible XSS in the forum app, even if we are assuming the app devs of the forum are not malicious).

Pros and Cons of the Options#

Reserve some scopes#

  • Future-proof: If we require them in the future we can be sure noone conflicts with it
  • Shouldn't block any usecase - when setting up, they can just choose a different prefix
  • Added docs (but fairly minimal)

    • Allow all scopes#

  • Very easy to communicate
  • Can create problems if we need to use them ourselves
    • Which UI do you use?
    Custom UI
    Pre built UI