Which frontend SDK do you use?

supertokens-web-js / mobile

supertokens-auth-react

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)
• 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

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

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