Skip to main content

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

Active session can't change auth-modes


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

rishabhpoddar, porcellus
Proposed by:
Last updated:

Context and Problem Statement#

We need to decide if we can upgrade in get/verifySession on refresh calls

Considered Options#

  • All
  • Refresh only
  • None (change in settings only take effect when creating new session)

Decision Outcome#

Active session can't change auth-modes. Reasons:

  • Allowing it in all request would increase implementation complexity for not much gain and it'd make our vulnerability of XSS attacks worse.
  • If we allow changing the auth-mode during session refresh we increase the attack surface of XSS.
  • An XSS attack could still steal tokens by changing the auth-method during sign-in, but in this case they could also capture the user credentials.
  • This means that changing the default auth-mode in the frontend SDK will only have effect after the user logs in again.

As a consequence:

  • Refresh session will not change the auth-mode of incoming requests.
  • In case both cookies and headers are there, we default to headers (see here)
  • Respecting the auth-mode header in case both exist during a refresh call would provide no real advantage:
    • this should not happen while using a FE SDK:
      • when refreshing or creating sessions we clear the token transfer methods we are not using (e.g.: we clear cookies when creating a session using headers).
      • there can be some edge cases (changing versions back-and-forth during development): we are not optimising for this
    • the most likely case is someone sending manual requests:
      • Headers should take priority as that's more likely to be intentional.
    • it could be an attacker through XSS:
      • even if we reject this/use cookies, they could call logout to clear old cookies before adding their own tokens, completely replacing the session
  • In case both cookies and headers are there, refresh will clear the one we are not using.

Expected behaviour of refreshSession as a table#

getTokenTransferMethodAuthorization headerRefresh token cookieOutputSet tokens inCleared tokens
anynoneexistsValidate refresh token from cookiecookiesnone
cookienoneexistsValidate refresh token from cookiecookiesnone
anyexistsnoneValidate refresh token from headerheadersnone
headerexistsnoneValidate refresh token from headerheadersnone
anyexistsexistsValidate refresh token from headerheaderscookies
headerexistsexistsValidate refresh token from headerheaderscookies
cookieexistsexistsValidate refresh token from cookiecookiesheaders
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI