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.

Session verification should check headers then cookies

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-10-25
Last updated:
2022-11-24

Context and Problem Statement#

If the FE sends a request using the wrong authentication method (e.g.: using headers instead of cookies), it could mean:

  1. There is an old session present on the FE
  2. Our SDK is outdated on the FE
  3. Manual requests (SSR)
  4. Postman without appropriate headers

Depends on default auth mode decision 0003

Example usecases:

  • Browser w/ SDK
  • Browser w/ old SDK (we require sync update of FE and BE)
  • Browser wo/ SDK (we are not optimizing for this, but basically the same as Postman)
  • Mobile apps w/ SDK
  • Mobile apps wo/ SDK
  • CLI
  • M2M
  • SSR (same as M2M)
  • SSR (same as M2M) w/ ability to read access token on the frontend (for web sockets for example)
  • Postman (basically CLI w/ cookie storage)
  • Native/desktop apps (same as mobile apps)
  • E2E testing (Same as mobile without SDK)
  • Browser extension w/ SDK (same as browser w/ SDK + some customization)
  • Migration (from other services using Authorization header with a JWT)

These can be reduced to two things:

  • Access to our FE SDK
  • Built-in cookie support

Considered Options#

  • Reject
  • Allow fallback
  • Allow fallback if rid header not set
  • Allow fallback if auth mode header not set
  • Session verification should check headers then cookies

Decision Outcome#

Session verification should check headers then cookies:

  • If idRefreshToken is present, we reject with TRY_REFRESH_TOKEN
  • Headers is the default method as per this decision
  • Make sure that updating the access token updates in the fallback case use the same as the incoming request. (e.g: if we read a session from cookies then updateAccessTokenPayload should update the cookies, not headers)

Expected behaviour as a table#

getTokenTransferMethodsessionRequiredAuthorization headerAccess token cookieOutput
*falsenonenoneundefined
cookiefalseexistsnoneundefined
headerfalsenoneexistsundefined
*truenonenoneUNAUTHORISED
cookietrueexistsnoneUNAUTHORISED
headertruenoneexistsUNAUTHORISED
any*existsexistBased on session validation of header
header*existsexistBased on session validation of header
cookie*existsexistBased on session validation of cookie
any*existsnoneBased on session validation of header
header*existsnoneBased on session validation of header
any*noneexistsBased on session validation of cookie
cookie*noneexistsBased on session validation of cookie
  • Also check this decision: Treat Authorization header as empty if it doesn't contain a SuperTokens token
  • Also check this decision: Optional session verification should throw TRY_REFRESH_TOKEN errors

Pros and Cons of the Options#

Reject#

  • Easier to communicate - if it doesn't match we reject
  • Forces the user to sign in again, since refresh won't allow an upgrade (check [here](./0008))
  • Strictly matches settings
  • Cookie based requests without our SDKs need to set preference/rid in header, but this is less used
  • With access to our (client) SDK all cases work equally well provided sensible default

    • Allow fallback#

  • Easier to communicate
  • Can be counter-intuitive: an auth method is set but we don't always respect it
  • With access to our (client) SDK all cases work equally well provided sensible default

    • Allow fallback if rid header not set#

  • Harder to communicate - the seemingly unrelated rid header changes things
  • With access to our (client) SDK all cases work equally well provided sensible default

    • Allow fallback if auth mode header not set#

  • Easier to communicate
  • We should still make the backend be able to validate it
  • With access to our (client) SDK all cases work equally well provided sensible default

    • Session verification should check headers then cookies#

    Meaning, it always uses fallback, ignoring the auth mode header

  • Easiest to communicate
  • Makes it clear that the auth mode sent by the frontend is just a preference
  • We should still make the backend be able to validate it
  • With access to our (client) SDK all cases work equally well provided sensible default
    • Which frontend SDK do you use?
    supertokens-web-js / mobile
    supertokens-auth-react