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

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

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:

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)~~
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:

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)
We could add a configurable validation function that checks if a request is allowed to use a token transfer method, but this can be done later.
- Also, the usefulness of it is limited, since an attacker could just call logout and login with their own user using the appropriate token transfer method

getTokenTransferMethod	sessionRequired	Authorization header	Access token cookie	Output
*	false	none	none	undefined
cookie	false	exists	none	undefined
header	false	none	exists	undefined
*	true	none	none	UNAUTHORISED
cookie	true	exists	none	UNAUTHORISED
header	true	none	exists	UNAUTHORISED
any	*	exists	exist	Based on session validation of header
header	*	exists	exist	Based on session validation of header
cookie	*	exists	exist	Based on session validation of cookie
any	*	exists	none	Based on session validation of header
header	*	exists	none	Based on session validation of header
any	*	none	exists	Based on session validation of cookie
cookie	*	none	exists	Based 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

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