Sessions, cookies, storage and logging in

HTTP forgets everything#

The web’s transport, HTTP, is stateless: each request is a self-contained question, and the server answers it without remembering the last one. Ask for /inbox twice and, as far as the protocol is concerned, two strangers asked.

Every feature that needs memory (a login, a shopping cart, a language choice, a “don’t show this again”) has to be added on top. The browser carries the memory and hands it back with each request. There are two places it can live:

• In the request itself, as a cookie: a small piece of text the browser sends automatically, so the server sees it on every request.
• In the page’s storage, as web storage: data the page’s own JavaScript reads and writes. The server sees it only if the script chooses to send it.

Cookies, in depth#

A cookie is born when a server answers with a Set-Cookie header. The browser stores it, and sends it back in a Cookie header on later requests that match:

HTTP/1.1 200 OKSet-Cookie: sid=9f2c41ab7e; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=2592000GET /inbox HTTP/1.1Host: shop.example.comCookie: sid=9f2c41ab7e; theme=dark

Everything after the first name=value pair is an attribute that tells the browser when the cookie applies and how to protect it:

Cookie names can also carry a prefix that the browser enforces: __Secure- requires Secure, and __Host- additionally requires Path=/ and no Domain, which pins the cookie to one host.

First-party and third-party#

A cookie is first-party when it belongs to the site shown in the address bar and third-party when it is set by something embedded in the page: an ad, a video player, a “like” button. The same third-party service embedded on many sites can recognise you on all of them, which is how cross-site tracking works. Browsers have been closing that door in different ways: blocking third-party cookies, applying SameSite=Lax by default, and partitioning (each top-level site gets its own copy of the third-party cookie, so the embedded service cannot connect your visits).

“Same site” has a precise meaning: the registrable domain, the part of the host you can buy, found with the Public Suffix List. shop.example.com and www.example.com are the same site; example.com and example.org are not; alice.github.io and bob.github.io are different sites, because github.io is on the list.

Limits and the rest#

Browsers cap a cookie at about 4 KB and the number of cookies per domain (Chrome: about 180), dropping the oldest. Cookies are also not private to a port or to http versus https in the way origins are, which is part of why they are easy to misuse. A cookie is the key to the account: if a server uses a random sid value as proof of login, whoever holds that value is that user.

Web storage#

Cookies are small and travel on every request. For larger data that only the page needs, browsers provide storage APIs. They are scoped to an origin (defined below).

localStorage and sessionStorage hold strings as key and value pairs and are synchronous. IndexedDB is a real database of objects, with indexes and transactions, and is asynchronous. Single-page apps often keep their session token, user settings or an offline copy of data in these places, not in cookies, so saving only the cookies may not be enough to restore a login.

Two more places hold state: the HTTP cache (files the browser reuses instead of downloading again) and service workers with their Cache Storage (a script that can answer requests itself, which is how sites work offline).

Origins and the same-origin policy#

An origin is the triple of scheme, host and port, and two URLs are the same origin only if all three match. The comparison table is in Origins: the unit of trust.

The same-origin policy is the browser’s main security rule: a page can read data only from its own origin. A script on evil.example cannot read your localStorage for bank.example, cannot read the response of a request to bank.example, and cannot reach into a bank.example iframe. Sites that want to share data on purpose use CORS headers (Access-Control-Allow-Origin) or postMessage.

This rule explains two behaviours you will meet in automation:

• Storage belongs to the origin, so you must be on a page of that origin before you can read or write its localStorage.
• A cookie belongs to a domain, so a cookie for example.com can only be added while the browser can attribute it to that domain.

Sessions and tokens#

Authentication answers “who are you?”. Authorization answers “what may you do?”. They are different checks, and mixing them up is how broken access control happens. The sections from here on are about the first.

After a login the server needs a way to recognise you on the next request. There are two main designs.

Where the token lives matters. A cookie marked HttpOnly cannot be read by page JavaScript, so a cross-site scripting bug cannot steal it. A token in localStorage can be read by any script on the page. The sections above show how cookies and storage behave.

How a login persists#

The password is sent once. The server hands back an opaque session id, the browser attaches it to every later request, and the server looks the id up. Some sites keep a signed token (a JWT) in a cookie or in localStorage instead; a “remember me” login is a persistent cookie with a long Max-Age. The server decides when the login ends: the session record can expire, be revoked, or be tied to details such as the IP address or the browser. A saved state that worked yesterday can therefore stop working even though the cookie is unchanged.

Until it ends, though, the cookie is the login: copy it into another browser and that browser is logged in. That is the basis of the fast test logins below.

HTTP Basic authentication#

Basic authentication is built into HTTP. The server answers 401 with a header WWW-Authenticate: Basic realm="...", the browser pops up its own username and password box, and from then on it sends

Authorization: Basic dXNlcjpwYXNzd29yZA==

which is the Base64 of user:password. That is an encoding, not encryption (see encryption), so Basic is safe only over https.

For automation the awkward part is the native dialog: it is not part of the page, so no selector can reach it. The ways around it are to put the credentials in the address (https://user:pass@host/, accepted for the first navigation by most browsers), to send the Authorization header yourself by intercepting requests (network), or to answer the Fetch.authRequired event of the DevTools Protocol. Bearer tokens use the same header with a different word: Authorization: Bearer <token>.

OAuth 2.0 and OpenID Connect#

“Sign in with Google” uses two standards. OAuth 2.0 lets an app get limited access to your account without ever seeing your password. OpenID Connect (OIDC) adds an ID token on top, so the app also learns who you are.

The usual flow is the authorization code flow with PKCE:

The browser is sent away to the provider and back. The password is typed on the provider’s page only.

Three terms help: the state value stops a forged return; PKCE stops someone who steals the code from using it; and the scope names what access is asked for.

Tests and OAuth. The redirect chain crosses several origins, so a test must wait for the browser to come back to the app rather than act at once. Do not automate a login on a real public provider: they detect bots, ask for MFA and may lock the account. Use a provider test tenant, a fake identity provider that your suite starts, or skip the redirect altogether with the fast login below.

JWTs#

A JSON Web Token is a compact, signed note. It is three Base64URL parts joined by dots: a header, a payload and a signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyLTQyIiwiZXhwIjoxNzAwMDAwMDAwfQ.sig... header   -> {"alg":"HS256"} payload  -> {"sub":"user-42","exp":1700000000} signature-> HMAC (or a private-key signature) of the first two parts

The payload holds claims: sub (who), iss (who issued it), aud (who it is for), iat and exp (issued and expiry times, in seconds since 1970).

• It is signed, not encrypted. Anyone can read the payload by decoding it, so never put a secret in a JWT.
• The server must check the signature, the expiry and the audience, and must refuse the none algorithm. Skipping any of these is a classic hole.
• Access tokens are short (minutes) and are renewed with a longer-lived refresh token.

Multi-factor authentication and TOTP#

MFA asks for more than one kind of proof: something you know (a password), something you have (a phone, a key) and something you are (a fingerprint).

The common “have” is a TOTP (time-based one-time password), the six digits in an authenticator app, defined in RFC 6238. When you enrol, the site shows a QR code that holds a shared secret (a Base32 text). From then on both sides compute the same value:

code = last six digits of  HMAC(secret, floor(unix_time / 30))

A new code appears every 30 seconds and the server accepts the current one (often the neighbouring ones too, for clock drift). Nothing travels between phone and server; only the shared secret and the clock matter.

For a test account this is good news: a TOTP is just a calculation. Keep the Base32 secret of the test account in your secret store and compute the code when the login asks for it. Two practical rules: the machine’s clock must be right, and if the current window has only a second or two left, wait for the next one, or the code will have expired by the time it is submitted. Codes sent by SMS or email need a test inbox or number; push approvals (“tap yes on your phone”) cannot be automated at all, so ask for a test account that uses TOTP.

Passkeys#

A passkey replaces the password with a key pair, using the WebAuthn standard. The device creates the pair when you register; the private key never leaves it (and is unlocked by a fingerprint, face or PIN), and the site stores only the public key. To log in, the site sends a random challenge, the device signs it, the site checks the signature. There is no password to steal or phish, and the key works only for the site it was made for.

For tests the unlock step is a native system dialog, which automation cannot click. The DevTools Protocol has a WebAuthn domain with virtual authenticators: a fake device inside the browser that approves requests on its own. See Passkeys and WebAuthn for the commands.

Profiles, and what is in one#

A browser profile is a folder on disk, the user data directory (--user-data-dir). It holds the cookie database, localStorage, IndexedDB, the cache, saved passwords, extensions and settings. If you start Chrome again with the same folder, it is the same user: still logged in, same history.

Two rules follow:

• A fresh profile is a fresh visitor. The default for automation: every run starts with an empty temporary profile and the site sees a first visit.
• One browser per profile folder. Chrome locks the folder, so two browsers cannot share it at the same time.

Chrome also has two modes that never write a profile to disk: incognito (a temporary profile that is thrown away) and guest (a clean profile with no sign-in).

Contexts: isolation without a second browser#

A browser context is the DevTools Protocol’s name for what Chrome shows as an incognito window: a set of tabs with their own cookies, storage and cache, sharing nothing with any other context in the same Chrome process. It is far cheaper than starting another browser, which makes it the right unit for “one clean user per test” and for running many users in parallel.

Logging in fast in tests#

A UI login can take seconds and may involve a redirect chain, MFA and rate limits. Doing it before every test is slow and fragile. Because the cookie is the login, you can do it once and reuse it.

Saving a signed-in state#

These are the calls for each step. To save the state, use save_cookies in BaseCase, page.cookies().save(path, filter) for a file in the pure CDP engine, or save_session on a pool lease for an in-memory copy (and the localStorage entries as well, where the site keeps its token there). To load it, open the site’s origin first, because cookies belong to a domain, then call load_cookies, page.cookies().load(path, filter) or load_session.

The in-memory form is a Session: the cookies plus the localStorage entries of one origin, built with Session::new(cookies) and with_local_storage(origin, entries). A SessionStore keeps named sessions for as long as the process runs; it does not write to disk. Both drop what has expired: Session::without_expired(now) and SessionStore::prune_expired(now), where now is a Unix time in seconds, the unit a Cookie’s expires field uses.

How seleniumbase-rs uses it#

Sessions in each engine#

use seleniumbase_rs::sb_cdp::{Cookie, SameSite};page.goto("https://example.com").await?; // be on the origin firstpage.cookies()    .set(&[Cookie::new("theme", "dark")        .domain("example.com")        .path("/")        .secure(true)        .same_site(SameSite::Lax)])    .await?;page.local_storage().set("onboarding", "done").await?;for cookie in page.cookies().all().await? {    println!("{} = {} (HttpOnly: {})", cookie.name, cookie.value, cookie.http_only);}

let worker = pool.acquire().await?;worker.page().goto("https://example.com/login").await?;// ... sign in ...worker.save_session("alice").await?;worker.release().await;let another = pool.acquire().await?;another.page().goto("https://example.com").await?;another.load_session("alice").await?; // signed in, without logging in againanother.release().await;

Logins, TOTP and saved sessions#

// The Base32 secret comes from your secret store, not from the source file.let secret = std::env::var("TEST_USER_TOTP_SECRET")?;// ... after the username and password step, on the page that asks for the code:sb.enter_totp_code("#otp", &secret).await?;

// First run, after a real login through the page:sb.save_cookies("app_login").await?;        // saved_cookies/app_login.txt// Later runs, after opening any page of the same site:sb.load_cookies("app_login").await?;// ... then reload the page: the session is signed in.

use seleniumbase_rs::sb_cdp::{Cookie, Session, SessionStore};let store = SessionStore::new();store.save("alice", Session::new(vec![Cookie::new("sid", "s3cret")]));let shared = store.clone();          // a second worker's handle to the same storelet alice = shared.load("alice");    // Some(Session) with the cookie

Where to go next#