CSRF, cookies & tokens

Protect sessions and requests

When you sign in to a website, the site must know it is still you on every later request. A request is one message from the browser to a server, such as "show my account" or "move $50". This lesson shows how to keep those requests safe.

It uses ideas from earlier lessons: cookies, Web Storage, fetch, requests in depth, and CORS. Here you put them together to protect a signed-in user.

Browsers group web addresses in two ways:

• An origin is three parts of a URL: the scheme (https), the host (app.example.co.uk), and the port (443 for https unless the URL says another). Two URLs have the same origin only when all three parts match.
• A site is wider. It is the scheme plus the registrable domain: the part of the host a person can buy, such as example.co.uk. So app.example.co.uk and api.example.co.uk are the same site.

The scheme counts for sites too: http://example.com and https://example.com are different sites. To find the registrable domain, browsers use the Public Suffix List, a long list of endings such as .com and .co.uk. The code below uses a tiny sample of that list so you can read it.

1const publicSuffixSample = ["co.uk", "github.io", "com", "org", "net", "dev"];2 3function registrableDomain(hostname) {4  const labels = hostname.toLowerCase().split(".");5  const suffix = publicSuffixSample6    .sort((a, b) => b.split(".").length - a.split(".").length)7    .find((item) => hostname === item || hostname.endsWith("." + item));8  if (!suffix) return labels.slice(-2).join(".");9  const suffixLength = suffix.split(".").length;10  return labels.slice(labels.length - suffixLength - 1).join(".");11}12 13function site(url) {14  const parsed = new URL(url);15  return parsed.protocol + "//" + registrableDomain(parsed.hostname);16}17 18function sameOrigin(a, b) {19  return new URL(a).origin === new URL(b).origin;20}21 22function sameSite(a, b) {23  return site(a) === site(b);24}25 26const page = "https://app.example.co.uk/settings";27const api = "https://api.example.co.uk/profile";28console.log(sameOrigin(page, api));29console.log(sameSite(page, api));30console.log(site(api));

Lines 3-11 find the registrable domain from the sample list. Lines 13-16 build the site: the scheme plus that domain. Line 18 compares origins, and line 22 compares sites.

• Line 28 prints false: the page and the API have different hosts, so they are not the same origin.
• Line 29 prints true: both end in example.co.uk, so they are the same site.
• Line 30 prints the API's site, https://example.co.uk.

Now, sessions. A session is how a server remembers that you signed in. There are two common kinds:

• A cookie session: the server gives the browser a random session ID in a cookie, often with HttpOnly; Secure; SameSite=Lax. The browser then adds that cookie to matching requests by itself. The server looks up the ID to find out who you are.
• A bearer token: the app adds a header such as Authorization: Bearer ... to each request. "Bearer" means whoever holds the token can use it, like cash. So where you keep it, and how long it lasts, matter.

Both kinds face a risk called XSS (cross-site scripting): an attacker's script running inside your page. The table compares the two kinds. Each row is one kind of session.

A CSRF attack uses one browser habit. The browser adds matching cookies to a request, even when another site started the request.

Here is the classic example. A page on another site has a hidden form. The form sends itself to a bank where you are signed in. That page can't read the bank's reply. But the request may still reach the bank with your session cookie, and the bank may move the money.

Which requests are at risk?

• At risk: requests that change something, such as moving money, when the server knows you by a cookie.
• Lower risk: GET requests that only read. Keep GET safe: it should never change anything, because links, preloading, search crawlers, and images can all send a GET.
• A different problem: the browser never adds a bearer token from JavaScript storage by itself. But an XSS script can steal the token or use it.

A cookie's SameSite attribute tells the browser when to send it with a request that another site started. If a cookie has no SameSite, browsers today treat it as Lax.

1const cookie = {};2const effectiveSameSite = cookie.sameSite ?? "Lax";3console.log(effectiveSameSite);

Line 1 models a cookie with no sameSite value. Line 2 uses ??, which picks the right side when the left side is null or undefined. So it picks "Lax". Line 3 prints Lax. In real apps, always write the attribute, so anyone reading the code sees the rule you chose.

The step-through below runs a request from attacker.example to bank.example. The picture shows its two results.

1function shouldAttachCookie(cookie, request) {2  const sameSite = cookie.sameSite ?? "Lax";3  const crossSite = request.topLevelSite !== request.requestSite;4  const safeTopLevelGet = request.topLevelNavigation && request.method === "GET";5 6  if (sameSite === "None" && !cookie.secure) return false;7  if (!crossSite) return true;8  if (sameSite === "Strict") return false;9  if (sameSite === "Lax") return safeTopLevelGet;10  return true;11}12 13const request = {Run14  topLevelSite: "https://attacker.example",15  requestSite: "https://bank.example",16  method: "POST",17  topLevelNavigation: true,18};19 20console.log(shouldAttachCookie({ sameSite: "Lax", secure: true }, request));21console.log(shouldAttachCookie({ sameSite: "None", secure: true }, request));

Today's major browsers treat a missing SameSite as Lax. A cookie with SameSite=None must also have Secure, which means the browser only sends it over HTTPS.

Chrome once had a short exception called "Lax+POST". For two minutes after a cookie with no SameSite was set, Chrome still sent it with a form POST from another site. Don't build on that old exception. Write the attribute you mean, and check every write on the server.

SameSite is one strong layer, not the whole defense. The next layer is a CSRF token.

A synchronizer token is a random value the server saves with your session. The server also puts it into its own forms and pages. When a request wants to change something, the server checks that the request carries the same value. Another site can't read your page, so it can't copy the token.

1function tokenMatches(sessionToken, submittedToken) {2  return typeof submittedToken === "string" && sessionToken === submittedToken;3}4const sessionToken = "random-session-token";5console.log(tokenMatches(sessionToken, "random-session-token"));6console.log(tokenMatches(sessionToken, ""));

• Lines 1-3 define tokenMatches. It gives true only when the sent token is a string and equals the session's token.
• Line 4 is the token saved in the session.
• Line 5 sends the same token and prints true.
• Line 6 sends an empty string and prints false.

This is a small model. Real tokens must be random, belong to one session, and be checked on the server.

A second design is the double-submit cookie. The server puts a CSRF value in a cookie, and the page repeats it in a form field or a header. Checking that the two are equal is not enough. A sibling subdomain, such as blog.example.com next to app.example.com, may be able to set a matching cookie. So sign the token and tie it to the session.

Where you can, make the CSRF cookie host-only: leave out the Domain attribute, so only your exact host gets it. Neither token design stops XSS. A script running inside your page can read the token and use it.

1// Server-side sketch, not browser JavaScript.2if (["POST", "PUT", "PATCH", "DELETE"].includes(request.method)) {3  assertSameOrigin(request.headers.get("Origin"));4  assertEquals(request.session.csrfToken, request.body.csrfToken);5  performStateChange();6}7 

Line 1 says this is server code, not browser code. Line 2 picks the methods that change things: POST, PUT, PATCH, and DELETE. Line 3 checks the Origin header, and line 4 checks the token. Only then does line 5 make the change.

The server can also check where a request came from. Browsers add an Origin header to most requests that change things. It holds the origin of the page that sent the request. When Origin is missing, the server may use the origin from the Referer header instead. Referer holds the URL of the page that sent the request.

• Compare the origin with an exact list of allowed origins.
• Parse the URL first, then compare scheme, host, and port.
• Never accept a match on just the start or end of the text. https://app.example.evil.test also starts with https://app.example.
• If both headers are missing or broken, reject the write.

1const allowedOrigin = "https://app.example";2function matches(origin, referer) {3  const value = origin || referer;4  if (!value) return false;5  try { return new URL(value).origin === allowedOrigin; } catch { return false; }6}7console.log(matches("https://app.example", ""));8console.log(matches("", "https://evil.example/form"));9console.log(matches("", ""));10console.log(matches("", "https://app.example/form"));11console.log(matches("not a URL", "https://app.example/form"));

Line 3 uses origin, or referer when origin is empty. Line 4 rejects a request with neither. Line 5 parses the URL and compares its origin with the allowed one. If parsing fails, it gives false. The five calls print:

• Line 7: true. The Origin is the app.
• Line 8: false. The Referer is from another site.
• Line 9: false. Both headers are missing.
• Line 10: true. Origin is missing, and the Referer is from the app.
• Line 11: false. The Origin is not a valid URL. When in doubt, the check says no.

Some privacy settings remove Referer details. So decide on purpose what happens when neither header can be checked. Don't allow the write by default.

A JSON API can add one more check: a custom header such as X-CSRF-Token. A normal HTML form can't set custom headers. And when a page on another origin uses fetch with a custom header, or with the content type application/json, the browser first sends a preflight. A preflight is a quick OPTIONS request that asks the server, "May I send this?"

Keep the server's list of allowed origins strict, and reject form-style content types on these endpoints. A preflight is an extra browser check. It doesn't decide whether the user may do the action.

1const token = "session-token";2const form = { contentType: "application/x-www-form-urlencoded", headers: {} };3const app = { contentType: "application/json", headers: { "X-CSRF-Token": token } };4const accepts = (request) => request.contentType === "application/json" && request.headers["X-CSRF-Token"] === token;5console.log(accepts(form));6console.log(accepts(app));

Line 4 accepts a request only when it is JSON and carries the right token. The form request on line 2 has neither, so line 5 prints false. The app request on line 3 has both, so line 6 prints true. A real server must also check the session, and whether this user may do this action.

1document.cookie = "cf_visible_token=reader; Max-Age=60; Path=/; SameSite=Lax";2const visible = document.cookie.includes("cf_visible_token=reader");3console.log(visible);4document.cookie = "cf_visible_token=; Max-Age=0; Path=/";

Line 1 writes a cookie named cf_visible_token that lasts 60 seconds. Line 2 checks whether document.cookie contains it. Line 3 prints true, because this cookie is not HttpOnly. Line 4 deletes it by setting Max-Age=0.

1Set-Cookie: __Host-session=abc123; Path=/; HttpOnly; Secure; SameSite=Lax2Set-Cookie: csrf=public-token; Path=/; Secure; SameSite=Lax

Line 1 is the session cookie: HttpOnly, Secure, and SameSite=Lax. The __Host- name prefix makes the browser accept it only with Secure, Path=/, and no Domain, so it belongs to one exact host. Line 2 is a CSRF cookie without HttpOnly, so your own page script can read it and copy it into a header.

Browser storage is not a safe. The Web Storage lesson showed that any script on the page can read localStorage and sessionStorage. If an XSS bug lets an attacker's script run, that script can copy tokens from there, or call your APIs with them.

1const localStorage = new Map();2localStorage.set("access_token", "eyJhbGciOiJub25l" + "." + "eyJzdWIiOiIxMjMifQ" + ".");3 4function injectedScript(storage) {5  return storage.get("access_token");6}7 8console.log(injectedScript(localStorage).slice(0, 6));9console.log("XSS can read JS storage");

• Line 1 uses a Map to stand in for localStorage, so the demo stays inside this page.
• Line 2 saves a sample token under the name access_token.
• Lines 4-6 stand for a script an attacker slipped into the page. It only needs one line to read the token.
• Line 8 prints the first six characters, eyJhbG. Line 9 prints the point of the demo.

The table compares five places to keep a token. Each row says what that place protects and what risk is left.

Many tokens are JWTs (JSON Web Tokens). The last section explains them. A JWT holds claims: named fields such as who the user is. The exp claim says when the token expires. It is a Unix timestamp in seconds: the number of seconds since 1 January 1970.

The server must check the token's signature and its exp. A countdown in the page is only a hint for the user.

1const nowSeconds = 1_800_000_000;2const expSeconds = nowSeconds + 300;3const secondsRemaining = expSeconds - nowSeconds;4console.log(secondsRemaining);5console.log(expSeconds <= nowSeconds);

Line 1 sets a sample clock. Line 2 sets the expiry 300 seconds later. Line 3 subtracts to get the time left. Line 4 prints 300. Line 5 prints false: the token has not expired yet. These numbers are made up; this is not a real token.

Two kinds of token often work together:

• An access token is sent to the API. Give it a short life, so a stolen copy stops working soon. A short life doesn't stop theft. It only limits how long a stolen token works.
• A refresh token gets a new access token when the old one expires. Rotate it: after each use, hand out a new one and cancel the old one. If someone uses an old one again, it was probably stolen, so cancel every refresh token in that chain. Give refresh sessions an end date too, then ask the user to sign in again.

HttpOnly stops page scripts from reading a cookie. It doesn't stop an XSS script from sending requests from your page, and the browser adds the cookie to those. So keep CSRF defenses and permission checks.

A token kept only in a JavaScript variable is called in memory. An XSS script can still use it while the page is open. A backend-for-frontend (BFF) is a small server of your own that keeps the OAuth tokens. The browser only gets a session cookie for the BFF, and that cookie still needs CSRF defenses.

CORS (Cross-Origin Resource Sharing) answers one small browser question: may this page read the reply from another origin? It doesn't decide whether the server should do the action.

A simple request is one a normal HTML form could send: GET, HEAD, or POST, with only basic headers. The browser sends it with no preflight, so it reaches the server. Tools outside the browser, such as curl, ignore CORS completely. So your API must check every request: who sent it, whether they may do this, and whether the data is valid.

The picture shows the first case in the step-through below: a simple POST, and a reply with no CORS headers.

1function decideCors(request, response) {2  const simpleMethod = ["GET", "HEAD", "POST"].includes(request.method);3  const simpleContentType = ["text/plain", "multipart/form-data", "application/x-www-form-urlencoded"]4    .includes(request.headers["Content-Type"]);5  const simple = simpleMethod && simpleContentType;6 7  const actualRequestSent = simple || response["Access-Control-Allow-Methods"]?.includes(request.method);8  const readable = response["Access-Control-Allow-Origin"] === request.origin &&9    (request.credentials !== "include" || response["Access-Control-Allow-Credentials"] === "true");10 11  return { simple, actualRequestSent, readable };12}13 14const request = {Run15  origin: "https://app.example",16  method: "POST",17  headers: { "Content-Type": "text/plain" },18  credentials: "include",19};20const response = {};21const result = decideCors(request, response);22console.log(result.simple);23console.log(result.actualRequestSent);24console.log(result.readable);

1function decideCors(request, response) {2  const simpleMethod = ["GET", "HEAD", "POST"].includes(request.method);3  const simpleContentType = ["text/plain", "multipart/form-data", "application/x-www-form-urlencoded"]4    .includes(request.headers["Content-Type"]);5  const simple = simpleMethod && simpleContentType;6 7  const actualRequestSent = simple || response["Access-Control-Allow-Methods"]?.includes(request.method);8  const readable = response["Access-Control-Allow-Origin"] === request.origin &&9    (request.credentials !== "include" || response["Access-Control-Allow-Credentials"] === "true");10 11  return { simple, actualRequestSent, readable };12}13 14const request = {15  origin: "https://app.example",16  method: "POST",17  headers: { "Content-Type": "text/plain" },18  credentials: "include",19};20const response = {};21const result = decideCors(request, response);22console.log(result.simple);23console.log(result.actualRequestSent);24console.log(result.readable);

Reading a reply that was sent with cookies has stricter rules. Access-Control-Allow-Origin: * can't be used with credentials (cookies or HTTP sign-in). The server must name the exact allowed origin and also send Access-Control-Allow-Credentials: true.

If the server copies the request's origin into that header, it should also send Vary: Origin. That tells shared caches to keep a separate copy of the reply for each origin.

OAuth is a standard way for an app to get permission to use an API for a user. It has four roles. Each row of the table names one role and who plays it.

A browser single-page app (SPA) is a public client: it can't keep a client secret, because anyone can read its code. So SPAs use the authorization code flow with PKCE (Proof Key for Code Exchange):

1. The app makes a long random string, the code_verifier, and keeps it.
2. It hashes the verifier into a code_challenge and sends that with the sign-in redirect.
3. After the user signs in, the app gets a one-time authorization code.
4. The app swaps the code for tokens and sends the verifier along. The server hashes the verifier and checks that it matches the challenge.

A hash is a one-way scramble: easy to compute, but you can't get the verifier back from the challenge. So someone who steals the code can't swap it for tokens without the verifier.

Resource owner: the person signing in
Client: the JavaScript app or its backend-for-frontend
Authorization server: issues codes and tokens
Resource server: the API that accepts access tokens
Flow for SPAs: authorization code + PKCE + state, not implicit

1function base64url(bytes) {2  let binary = "";3  for (const byte of bytes) binary += String.fromCharCode(byte);4  return btoa(binary).split("+").join("-").split("/").join("_").replace(/=+$/g, "");5}6 7async function pkceChallengeFromVerifier(verifier) {8  const bytes = new TextEncoder().encode(verifier);9  const digest = await crypto.subtle.digest("SHA-256", bytes);10  return base64url(new Uint8Array(digest));11}12 13(async () => {14  const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";15  const challenge = await pkceChallengeFromVerifier(verifier);16  console.log(challenge);17  console.log(challenge === "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM");18})();

The state parameter is separate from PKCE. It is a random value the app sends with the redirect and checks when the user comes back. It proves the reply belongs to the sign-in this browser started. That stops CSRF-style mix-ups.

Three kinds of token come out of OAuth:

• Access tokens go to the API, which OAuth calls the resource server.
• Refresh tokens get new access tokens. Rotate them, or bind them to the app that got them, so no one else can use them.
• ID tokens come from OpenID Connect. They tell your app who signed in. They are not for calling APIs.

OAuth security advice no longer recommends the old implicit flow, which put tokens straight into the URL. OAuth 2.1 drafts remove it. Use the authorization code flow with PKCE instead.

Many OAuth and OpenID Connect systems use JWTs. A JWT is three parts joined by dots:

• The header says how the token was signed, such as RS256.
• The payload holds the claims, such as sub, the user's ID.
• The signature proves who made the token and that nobody changed it.

The header and payload are base64url text: JSON turned into URL-safe letters, as in the Text encoding lesson. Anyone can decode them. Decoding is not verifying.

Verifying checks the signature with a trusted key. It also checks claims such as who issued the token (iss), who it is for (aud), and when it expires (exp).

1function base64UrlToText(part) {2  const base64 = part.replace(/-/g, "+").replace(/_/g, "/")3    .padEnd(Math.ceil(part.length / 4) * 4, "=");4  const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));5  return new TextDecoder().decode(bytes);6}7 8const token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJyb2xlIjoicmVhZGVyIn0.signature";9const [headerPart, payloadPart] = token.split(".");10const header = JSON.parse(base64UrlToText(headerPart));11const payload = JSON.parse(base64UrlToText(payloadPart));12 13console.log(header.alg);14console.log(payload.sub);15console.log("read, not verified");

• Lines 2-3 turn base64url back into normal base64 and add = padding at the end.
• Line 4 turns that into bytes, and line 5 turns the bytes into text.
• Line 9 splits the token at the dots. Lines 10-11 read the header and the payload as JSON.
• The code prints RS256, then 123, then read, not verified. Nothing here checked the signature.

Common misconceptions

• "CORS stops CSRF." It doesn't. CORS decides whether a page may read a reply. CSRF is about fake requests that change things.
• "With SameSite, I don't need tokens." SameSite is one layer. Important writes still need checks on the server.
• "HttpOnly cookies are always safer." They hide the value from scripts, but the browser still sends them with requests.
• "localStorage is safe because only my origin can read it." An XSS script runs in your origin, so it can read it too.
• "JWTs are secure because they look scrambled." Anyone can decode base64url. Trust comes from checking the signature and claims.
• "PKCE replaces the state parameter." PKCE protects the code swap. state protects the redirect back to your app.

The table puts four of these ideas side by side. Each row says what the idea does and what it doesn't do.

Key takeaways

• CSRF targets requests that change something and use a cookie to know the user, because the browser adds matching cookies by itself.
• Keep GET safe. Set SameSite on purpose. Check a CSRF token and the Origin header on every write, and check the user may do it.
• Any script on the page can read Web Storage, so an XSS bug can steal tokens from localStorage or sessionStorage.
• HttpOnly cookies keep tokens away from scripts, but they still need CSRF defenses.
• CORS decides whether a page may read a reply. It doesn't decide on the server who may act.
• SPAs should use the authorization code flow with PKCE and state. Decoding a JWT is not verifying it.

Final definition: safe sign-in in the browser uses several layers. Choose how the proof of who you are travels. Block fake writes from other sites. Keep tokens away from page scripts when you can. And check every token or session on the server.

Up next: prototype pollution, where merging untrusted objects can change every object in your app.