Design sign up and sign in

Requirements: the front door of the product

Every SaaS product has the same front door: a page where people create an account, and a page where they come back. Behind those two pages sit five more flows that people only notice when they break: sign out, forgot password, a second factor (MFA, multi-factor authentication), sign-in with Google or another provider, and passkeys, the new kind of credential that replaces the password with a key stored on your phone or laptop.

This is a frontend question, but the server owns the truth. The server checks passwords, issues sessions and decides who can see what. The frontend owns everything around that: which method to offer, how the forms behave with password managers, where the session lives in the browser, how redirects come back safely, what errors say, and what happens to the rest of the app when the session ends.

Many of the classic ways to break a sign-in page are frontend mistakes: a token in localStorage read by an injected script, an open redirect after sign-in, an error message that confirms an account exists.

Questions to ask

Each question changes a real decision later in the guide. The middle column is what this guide assumes.

Functional requirements

• Sign up with email (verified by a link or code), with Google, or with a passkey created right after the first sign-in.
• Sign in with whatever method the account has: password, email code, Google, passkey, or company SSO.
• A second factor when the account or workspace requires it: authenticator app (TOTP), security key, or SMS as a last resort.
• Forgot password and account recovery that never reveal whether an email is registered.
• Return to the page you were on (a deep link, a half-written comment) after signing in.
• Sign out of this device, and sign out of every device from settings.
• Re-authentication (step-up) before sensitive actions, without losing the form the person is in.

Non-functional requirements

• Security: session secrets unreachable from JavaScript, CSRF-safe writes, no account enumeration, rate limits on every guessable step, validated redirects.
• Speed: the sign-in page is a landing page for many people. Aim for LCP (Largest Contentful Paint, when the main content appears) under 1.5 seconds on a mid-range phone, a JavaScript budget under 80 KB gzipped, and no third-party scripts except the identity provider button.
• Conversion: a returning user with a passkey or a saved password signs in with 1 or 2 taps. Every extra step loses people: measure the drop-off of each screen.
• Accessibility: WCAG 2.2 AA, including success criterion 3.3.8 Accessible Authentication: no step may require remembering, transcribing or solving something unless there is a way around it.
• Reliability: a sign-in outage is a full product outage. The page must load even if the Google button or the CAPTCHA script fails.

Out of scope

We leave out the server side of password hashing (the backend uses a slow hash such as Argon2id), building our own identity provider, SAML internals, and roles and permissions after sign-in (see the permission-based UI problem). We mention them only where they shape the frontend.

What makes sign-in hard

A sign-in page looks like two inputs and a button. Five properties of the problem make it much harder than that, and each one drives a chapter later on.

1. It is the most attacked page you own. Bots try leaked email and password pairs from other sites (credential stuffing) at thousands of attempts a minute. Every message, status code and response time is read by someone trying to learn which accounts exist.
2. It holds the one secret that unlocks everything. After sign-in, the browser carries a session: a cookie or a token. If any script on any page of your origin can read it, a single XSS bug anywhere in the app becomes a full account takeover.
3. It crosses origins and devices. Google sign-in leaves your site and comes back. A magic link opens in a different browser than the one that asked for it. A passkey can live on a phone while the person sits at a laptop. Each crossing needs state that survives it and checks that it was not forged.
4. Security and conversion pull in opposite directions. Every extra step, CAPTCHA or code costs real sign-ups. Every shortcut costs real accounts. The design has to put friction only where risk is.
5. Sessions end in the middle of work. A token expires while someone writes a long comment. Another tab signs out. An admin revokes all sessions. The app must notice, ask again, and keep the unsaved work.

Here is how the rest of the guide maps to those five.

• The sign-in methods chapter decides which credentials we accept and how one screen routes to each.
• The forms chapter makes passwords and codes work with password managers and assistive tech.
• The session chapter decides where the secret lives.
• The OAuth and passkeys chapters handle the cross-origin and cross-device flows, and the MFA chapter adds the second factor.
• The errors chapter keeps the page from leaking accounts.
• The redirects and session end chapters handle deep links and sessions that end in the middle of work.

The wireframe above is the screen we are designing toward: one email field first, a passkey offered from the browser's autofill menu, a Google button, and a single Continue. The method screen that follows depends on the account. A first-time visitor never sees a wall of five buttons and three inputs.

Choosing the sign-in methods

The naive design is the classic form: email, password, a Sign in button, and below it a row of social buttons. It works until the requirements arrive. A company workspace must go through its own SAML provider, so the password field is wrong for those people.

Someone who signed up with Google types a password they never set and gets "wrong password". A person with a passkey still sees a password box and assumes they need one. "I can't sign in" is one of the most common kinds of support ticket in a SaaS help desk, and many of those tickets come from people picking the wrong method.

So the first decision is which credentials to accept at all. Each has a different cost in security, conversion and support.

Identifier-first: ask who, then ask how

An identifier-first flow splits sign-in into two screens. Screen one asks only for the email (the identifier), and the frontend posts it to POST /api/auth/lookup. The server answers with the next step: a password screen, an email code, or a redirect to the company SSO. Google and Microsoft account sign-in work this way, as do many products with enterprise SSO.

That lookup endpoint is the sharpest edge in the design, because it can become an account directory for attackers. If an unknown email gets "no account" and a known one gets "enter password", a bot can test a million emails. Two rules fix it.

First, the response for an unknown email looks exactly like the response for a password account: show the password screen (or send a code) either way, and fail later with the same generic message. Second, only reveal things that are public anyway. An SSO redirect is decided by the email domain (@acme.com), not by whether the person exists, so it leaks nothing about the individual.

type NextStep =
  | { step: "password"; pending: string }   // also returned for unknown emails
  | { step: "email-code"; pending: string } // a code is on its way
  | { step: "sso"; redirectUrl: string };   // decided by the email domain

async function lookup(email: string): Promise<NextStep> {
  const res = await fetch("/api/auth/lookup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email }),
  });
  if (res.status === 429) throw new RateLimited(res.headers.get("Retry-After"));
  return res.json();
}

Try each method in the lab below. Watch the requests, the number of steps, and what an attacker learns from the replies when the email is not registered.

The magic link trap

Email links have a failure that surprises teams in production. Many corporate email security gateways and link-protection services open the links in incoming mail to scan them before anyone clicks. If GET /auth/magic?token=abc signs the person in and marks the token used, the scanner uses it first, and the real person gets "link expired".

The fix: the link opens a page with a Continue button, and only the POST from that button redeems the token. A second fix is to send a 6-digit code next to the link, so someone reading mail on a phone can type the code on the laptop where they started.

Forms that work with password managers and people

Most sign-in friction is not the method, it is the form. A password manager that does not offer to fill, a code that must be typed digit by digit, a rule like "must contain a symbol" that rejects a 30-character passphrase: each one costs sign-ins and sends people to the reset flow. The fixes are mostly HTML attributes that cost nothing.

Tell the browser what each field is

The autocomplete attribute is how browsers and password managers know what to fill. Without it they guess from names and labels, and they guess wrong on custom designs. Four tokens matter here: username on the email field, current-password on sign-in, new-password on sign-up and reset (which also tells the manager to offer a generated password), and one-time-code on code fields (which lets iOS and macOS offer the code from a text message or email).

<form method="post" action="/auth/password">
  <label for="email">Email</label>
  <input id="email" name="email" type="email"
         autocomplete="username webauthn" required>

  <label for="pw">Password</label>
  <input id="pw" name="password" type="password"
         autocomplete="current-password" required>
  <button type="button" aria-pressed="false"
          aria-controls="pw">Show password</button>

  <button type="submit">Sign in</button>
</form>

<!-- sign-up and reset -->
<input type="password" autocomplete="new-password"
       aria-describedby="pw-hint">
<!-- verification code -->
<input inputmode="numeric" autocomplete="one-time-code"
       maxlength="6" pattern="[0-9]{6}">

• Keep a hidden username on the password step. In identifier-first, the email was on screen one. Put it in a read-only or visually hidden autocomplete="username" field on the password screen too, or managers save the password with no username attached.
• Never block paste. Blocking paste breaks people who copy from a password vault, and NIST SP 800-63B says verifiers must allow password managers and should allow paste. It does nothing against bots, which do not paste.
• Offer a show-password toggle. A real button that switches the input type between password and text, with aria-pressed. It replaces the old "confirm password" field: one field you can check beats two you type blind.
• Do not split the email from the domain or auto-capitalize it. Add autocapitalize="none" and spellcheck="false" on the email field.

Password rules: length over complexity

The old rules (one upper case, one digit, one symbol, change every 90 days) made passwords like Summer2025! that are easy to guess and hard to remember. NIST SP 800-63B Revision 4 (the US government's authentication guideline, final in 2025) turns that around. Verifiers must not require mixes of character types and must not force periodic changes.

A password used alone must be at least 15 characters; one used with a second factor at least 8. Verifiers must allow password managers and autofill, and should allow paste, accept at least 64 characters, and accept every printable character including spaces. And they must reject passwords found on a blocklist of common, expected or breached passwords.

Checking breached passwords without sending them

How do you check a new password against hundreds of millions of breached ones without sending it anywhere? The Have I Been Pwned range API uses k-anonymity: you hash the password with SHA-1, send only the first 5 hex characters, and get back every breached hash suffix that starts with that prefix, with a count for each. Today that is roughly 2,000 lines per prefix. You compare the rest of the hash locally.

The service never learns the password or even its full hash. The check can run in the browser for instant feedback while typing, but the server must repeat it on submit, because the browser check can be skipped.

async function timesBreached(password: string): Promise<number> {
  const bytes = new TextEncoder().encode(password);
  const digest = await crypto.subtle.digest("SHA-1", bytes);
  const hex = [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("")
    .toUpperCase();
  const prefix = hex.slice(0, 5);
  const suffix = hex.slice(5);
  const res = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
    headers: { "Add-Padding": "true" },
  });
  for (const line of (await res.text()).split("\n")) {
    const [s, count] = line.trim().split(":");
    if (s === suffix) return Number(count);
  }
  return 0;
}

Add-Padding: true asks the API to add a random number of fake entries to every response, so someone watching the encrypted traffic cannot guess the prefix from the response size. Padded lines have a count of 0, so a real match always has a count above 0. Debounce the check by about 400 ms while typing, and show the result as guidance, not a red error, until the person submits.

Where the session lives in the browser

After any sign-in method succeeds, the server hands the browser a session: proof that later requests come from the same signed-in person. The naive SPA stores an access token, often a JWT, in localStorage and adds it as an Authorization: Bearer header on every fetch. It survives reloads and works across tabs, which is why so many tutorials do it.

It breaks on the first XSS bug. Any script running on your origin, including a compromised analytics package or one unescaped comment, can run localStorage.getItem("token") and send the token to its own server. The attacker now uses the account from their own machine, for as long as the token lives, even after the bug is fixed. The xss and auth-tokens lessons cover the mechanics; here we decide what this app does.

The lab below runs the four choices against the events that matter: an injected script, a forged cross-site form, a reload, a second tab, and a sign-out in another tab. Notice that no choice survives XSS completely. Even with an HttpOnly cookie, an injected script can send requests from inside the page while it is open. The difference is that it cannot take the session away and keep using it later.

The cookie, attribute by attribute

HTTP/1.1 200 OK
Set-Cookie: __Host-session=s_9fK2...; Path=/; Secure; HttpOnly;
            SameSite=Lax; Max-Age=1209600
Cache-Control: no-store

SameSite=Lax is not a full CSRF defense. It treats blog.example.com and app.example.com as the same site, so a bug on any subdomain can still send forged requests. Add one more check on every state-changing request: the BFF rejects writes whose Origin header is not our app, or requires a CSRF token header that only our own JavaScript can add (the csrf lesson compares these). Do it on the sign-in endpoint too: login CSRF signs a victim into the attacker's account, so anything they save lands where the attacker can read it.

Why Lax and not Strict? RFC 10017 and the auth-tokens lesson suggest SameSite=Strict for a BFF cookie, and it is stronger. But Strict leaves the cookie off the first request when someone follows a link from Slack or email, and our BFF reads the cookie when it serves the HTML (the redirects chapter), so a signed-in person would land on sign-in. We keep Lax and rely on the Origin check for writes; an app that only reads the session from fetch calls after the page loads can use Strict.

How data flows through the BFF

Putting the BFF at app.example.com/api instead of calling api.example.com directly also removes CORS from the picture: every call is same-origin, so there are no preflight requests and no Access-Control-Allow-Credentials to get wrong. The BFF adds the upstream bearer token when it forwards each call. The cors lesson explains what we avoid.

Social sign-in with OAuth and OpenID Connect

"Continue with Google" uses two standards stacked together. OAuth 2.0 is a way for one site to get permission from another. OpenID Connect (OIDC) adds identity on top: an ID token, a signed JWT that says who signed in, with claims like sub (a stable user ID), email and email_verified. The flow every current guide recommends for browsers is the authorization code flow with PKCE.

The naive version is the old implicit flow: the provider puts the token straight into the URL fragment and the SPA reads it. Tokens in URLs end up in browser history and logs, and any script on the page can grab them. RFC 9700, the OAuth security best current practice, says not to use the implicit flow, and RFC 10017 says browser apps must not. With our BFF, the browser never sees a provider token at all.

The authorization code flow, step by step

1. The person presses "Continue with Google". The SPA navigates the whole page to /api/auth/google/start?returnTo=/projects/42 on our BFF.
2. The BFF makes three random values: state (ties the reply to this browser), nonce (ties the ID token to this sign-in), and a PKCE code_verifier (43 to 128 characters). It stores them in a short-lived, HttpOnly cookie or server-side, keyed to this browser, along with the validated return path.
3. It redirects to Google with response_type=code, client_id, redirect_uri, scope=openid email profile, state, nonce, and code_challenge (the SHA-256 of the verifier, base64url encoded) with code_challenge_method=S256.
4. The person approves at Google. Google redirects to /api/auth/google/callback?code=...&state=....
5. The BFF checks that state matches what it stored. If not, it stops: someone may be pushing their own code into our browser (a login CSRF).
6. It posts the code and the code_verifier to Google's token endpoint with its client secret, and gets back an ID token. It verifies the signature, iss, aud, expiry and nonce.
7. It finds or creates the account by sub, sets our own session cookie, and redirects to the saved return path.

PKCE (Proof Key for Code Exchange) protects step 6. If an attacker steals the code from a log or a malicious extension, they still cannot trade it, because only our BFF knows the verifier whose hash went out in step 3.

Match accounts by sub, not by email. The sub claim is stable for one provider (iss), while emails can change at the provider. Linking a Google identity to an existing password account just because the email matches lets anyone who controls a matching Google account take over. Link only after the person signs in to the existing account, or after the provider marks the email verified and you have decided to trust that provider for that domain.

Why third-party cookies matter here

Older SPA libraries kept a session alive with a hidden iframe to the provider ("silent refresh"). That iframe needs the provider's cookie in a third-party context. Safari blocks third-party cookies by default and Firefox partitions them per site, so silent refresh fails there and people get signed out at random.

Chrome decided in 2025 to keep third-party cookies, but you cannot design for one browser. The BFF avoids the whole problem: our session is a first-party cookie, and the provider is only involved at the moment of sign-in.

Passkeys: sign-in without a shared secret

A passkey is a WebAuthn credential: a key pair the device creates for one website. The private key never leaves the authenticator, the thing that holds it. That is either a passkey provider on the device, often synced across the person's devices (iCloud Keychain, Google Password Manager, Windows Hello, or a password manager like 1Password), or a roaming authenticator such as a USB or NFC security key.

The server stores only the public key. To sign in, the server sends a random challenge, the authenticator signs it after a fingerprint, face or PIN check, and the server verifies the signature.

Two facts make passkeys the strongest method we offer. A leak of our database gives the attacker only public keys, which sign nothing. And the browser binds each passkey to a relying party ID (our domain, example.com), so a lookalike page at examp1e.com cannot ask for it. Phishing, the attack that defeats passwords and SMS codes, does not work.

Creating a passkey

Offer creation at moments of success, not as a wall at sign-up: right after a password or email-code sign-in ("Sign in faster next time?"), and in security settings. The server generates the options; the frontend passes them to navigator.credentials.create and posts the result back.

async function addPasskey() {
  const json = await api.post("/api/auth/passkeys/options");
  const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(json);
  // publicKey.rp.id = "example.com", user.id = opaque bytes, not the email
  // authenticatorSelection: { residentKey: "required", userVerification: "preferred" }
  // excludeCredentials lists passkeys this account already has
  try {
    const cred = await navigator.credentials.create({ publicKey });
    await api.post("/api/auth/passkeys", (cred as PublicKeyCredential).toJSON());
    toast("Passkey added");
  } catch (err) {
    if (err instanceof DOMException && err.name === "NotAllowedError") return; // cancelled
    if (err instanceof DOMException && err.name === "InvalidStateError") {
      toast("This device already has a passkey for your account");
      return;
    }
    throw err;
  }
}

residentKey: "required" makes it a discoverable credential: the authenticator remembers which account it belongs to, so sign-in needs no username at all. NotAllowedError usually means the person closed the prompt; treat it as a cancel, not an error.

The JSON helpers (parseCreationOptionsFromJSON, toJSON) are recent additions to WebAuthn, shipped in Chrome 129, Firefox 119 and Safari 18.4. Feature-detect them and fall back to a small library such as SimpleWebAuthn that converts base64url strings to ArrayBuffers for you.

Signing in with passkey autofill

The naive passkey sign-in is a "Sign in with a passkey" button. People without one press it and get a confusing browser dialog about security keys and QR codes. Conditional UI fixes this: on page load, the app starts a passkey request with mediation: "conditional", and nothing appears yet.

When the person focuses the email field marked autocomplete="username webauthn", the browser lists their passkeys for our site in the normal autofill menu, next to saved passwords. Picking one finishes sign-in. People without a passkey see an ordinary email field.

const abort = new AbortController();

async function canUsePasskeyAutofill(): Promise<boolean> {
  if (typeof PublicKeyCredential === "undefined") return false;
  if (PublicKeyCredential.getClientCapabilities) {
    const caps = await PublicKeyCredential.getClientCapabilities();
    return caps.conditionalGet === true;
  }
  return (await PublicKeyCredential.isConditionalMediationAvailable?.()) ?? false;
}

async function startPasskeyAutofill() {
  if (!(await canUsePasskeyAutofill())) return;
  const json = await api.post("/api/auth/passkeys/challenge");
  const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(json);
  try {
    const cred = await navigator.credentials.get({
      publicKey, mediation: "conditional", signal: abort.signal,
    });
    const next = await api.post("/api/auth/passkeys/verify", (cred as PublicKeyCredential).toJSON());
    router.finishSignIn(next); // a full session, or the next step
  } catch (err) {
    if ((err as DOMException).name !== "AbortError") showGenericError();
  }
}

// Before any other WebAuthn call (for example a security-key MFA step):
// abort.abort();

Only one WebAuthn request can run at a time, so abort the conditional request before starting another one, such as a modal passkey prompt or a security-key MFA step. Keep the challenge short-lived (about 5 minutes) and refresh it if the page stays open longer.

The feature check prefers PublicKeyCredential.getClientCapabilities(), which reports what the browser supports in one call (Chrome 133, Firefox 135, Safari 17.4), and falls back to the older isConditionalMediationAvailable().

Fallback paths

• No passkey on this device, but one on a phone. The browser's own dialog offers a QR code; the phone signs over a Bluetooth proximity check. We do nothing extra, but we should not hide the email path behind it.
• Passkey deleted on the server but still on the device, for example removed from another device's settings. The person picks it from autofill and the server rejects it. Show the generic error and the email path, and where supported (Chrome and Safari, not yet Firefox) call PublicKeyCredential.signalUnknownCredential so the password manager hides it. In settings, list passkeys with the device name and last-used date so people can clean up.
• Lost every device. Recovery goes through the email flow plus whatever the account requires. Passkeys do not remove the need for account recovery; they move it.
• Old browser or OS. PublicKeyCredential is missing or conditional mediation is unavailable. The page is a normal email form; no error shown.

MFA, step-up and remembered devices

Multi-factor authentication asks for a second proof of a different kind: something you have (a phone app, a security key) on top of something you know (a password). Passkeys already combine both (the device plus a fingerprint or PIN), so accounts that sign in with a passkey usually skip this step. For everyone else, some workspaces require it.

The naive design treats MFA as a modal on top of the signed-in app: create the session, then ask for the code. That is backwards. If the session exists before the second factor, an attacker with only the password already has a cookie that works on some endpoints.

The server must issue a pending state after the first factor, a short-lived token that can only call the MFA endpoints, and the full session only after the second. The frontend just follows the steps the server returns, which is why we model sign-in as a state machine.

Entering codes without friction

Use one input, not six boxes. A single field with autocomplete="one-time-code", inputmode="numeric" and maxlength="6" gets autofill from Messages on iOS and macOS, paste of the whole code, and one clear label for screen readers. Six separate boxes need custom code for paste, backspace, autofill and focus, and each box announces as a separate unlabelled field unless built with great care (the otp-input problem covers that design). Submit automatically when the sixth digit arrives, but keep a visible Verify button.

In Chromium browsers, the WebOTP API can read the code from an SMS for the person: Chrome on Android reads it on the phone, and desktop Chrome can receive it from the same person's Android phone. The text must end with a line naming our origin, like @app.example.com #482913, and the page calls navigator.credentials.get({ otp: { transport: ["sms"] } }) after asking for the SMS.

Chrome shows a consent sheet, then returns the code. Safari and Firefox do not support it, so feature-detect with "OTPCredential" in window and keep the normal field.

Step-up for sensitive actions

A session that is 13 days old should not be enough to change the account email, add a passkey, export all data or delete a workspace. Those actions need a fresh authentication, for example within the last 10 minutes. The server records when each factor was last proved.

When a request needs freshness it does not have, the server answers 401 with { "error": "reauth_required", "maxAge": 600 }. The frontend opens a re-auth dialog (passkey, password, or code), then retries the original request. The person stays on the page, and the form they were filling keeps its values.

Remember this device

Asking for a code on every sign-in from the same laptop trains people to approve codes without thinking. A "Remember this device for 30 days" checkbox sets a separate long-lived, HttpOnly device cookie holding a random ID the server links to the account. When it is present and valid, the server skips the second factor (never the first). The device appears in security settings with its browser, rough location and last use, and is revoked when the password changes, when MFA is reset, or on "sign out everywhere".

Errors, enumeration and abuse

Error messages on most pages should be as specific as possible. On sign-in pages, specific errors help attackers. Account enumeration means learning which emails have accounts.

It sounds harmless, but a list of confirmed accounts makes credential stuffing and targeted phishing much cheaper ("Your Example account has a problem, click here"). The goal is that every screen gives the same answer for an existing and a missing account, in text, status code, body shape and timing. The OWASP Authentication Cheat Sheet gives the same advice, with the same kind of generic messages.

Timing leaks too. If the server returns early for an unknown email but runs a 250 ms Argon2id check for a real one, a script can tell them apart. The server should run the same hash work in both paths, and send email from a background queue so "email sent" and "no account" take the same time. The frontend's part: never branch the UI on anything the server did not deliberately send.

Rate limits shown humanely

The server limits attempts per account, per IP and per device, and NIST SP 800-63B caps consecutive failed attempts with one authenticator on one account at 100. A hard lockout after 5 failures sounds safe, but it lets anyone lock the CEO out by typing their email wrong five times. Prefer growing delays (for example 1, 2, 4, 8 seconds, then 15 minutes) plus a challenge when signals look risky, and email the owner about repeated failures.

The frontend's job is to make limits understandable. A 429 Too Many Requests with Retry-After: 300 becomes "Too many attempts. You can try again in 5 minutes, or reset your password now." with a live countdown, the button disabled until it ends, and the reset link still active. Never show a raw 429 or a spinner that never ends. Disable the submit button while a request is in flight, so double clicks do not burn two attempts.

CAPTCHA only when risky

A CAPTCHA on every sign-in costs every real person time and fails many disabled people, and modern solving services beat image puzzles for a fraction of a cent each. Show a challenge only when the server's risk score says so: many failures, a known-bad IP range, a new device for a high-value account. Prefer low-friction checks such as Cloudflare Turnstile or reCAPTCHA v3, which usually need no puzzle.

Load the challenge script only when a challenge is needed, so the sign-in page stays fast and works when the vendor is down. WCAG 3.3.8 allows object recognition tests ("pick the photos with a bus") at level AA, but transcribing distorted text is a cognitive function test, so always keep an accessible alternative.

Password reset and account recovery

• The reset link carries a single-use token with a short life (30 to 60 minutes). Only a POST from the reset page redeems it, for the same link-scanner reason as magic links.
• Keep the token out of logs and referrers. Send Referrer-Policy: no-referrer on the reset page and remove the token from the URL with history.replaceState once it is read, so a third-party script or a shared screenshot does not leak it.
• After a reset, sign out every other session and revoke remembered devices, then sign this browser in. Tell the person in the UI and by email.
• Resetting a password does not bypass MFA. If the account has a second factor, the reset flow asks for it, or for a recovery code. Losing both goes to a slower, human-reviewed recovery with a waiting period, because that path is what account takeover crews aim at.
• No security questions. "Mother's maiden name" is public on social media, and NIST no longer allows them.

Redirects back and protected routes

Someone opens a link from Slack to app.example.com/projects/42/tasks/7 while signed out. They should land on sign-in and, after it, on task 7, not on the dashboard. The naive way is /sign-in?returnTo= plus whatever URL they came from, and after sign-in location.href = returnTo.

That is an open redirect: a phisher sends app.example.com/sign-in?returnTo=https://examp1e.com/billing, the victim signs in on our real page, and lands on a fake one that asks for their card "again". Since the link started on our domain, people and spam filters trust it.

Validating the return path

Accept only same-origin paths, and check them by parsing, not with string tricks. //evil.test and /\evil.test both start with a slash but browsers treat them as other hosts. The BFF repeats the same check, because it is the one that stores returnTo across the OAuth round trip.

const FALLBACK = "/home";

export function safeReturnTo(raw: string | null): string {
  if (!raw) return FALLBACK;
  try {
    const url = new URL(raw, window.location.origin);
    if (url.origin !== window.location.origin) return FALLBACK;
    if (url.pathname.startsWith("/sign-in")) return FALLBACK; // no loops
    return url.pathname + url.search + url.hash;
  } catch {
    return FALLBACK;
  }
}

Keeping state across the trip

The URL carries where to go. It cannot carry what the person was doing: a half-written comment, filters they set, a cart. Before a full-page redirect to sign-in or to Google, save that draft to sessionStorage (per tab, cleared when the tab closes) or to the app's existing draft store, keyed by route and user ID.

After sign-in, the page restores it. Never save secrets or another user's data there, and drop drafts if a different account signs in than the one that wrote them.

Auth state without flashes

A common SPA bug: the app boots, does not know the session yet, renders the sign-in page for 300 ms, then the /api/session call returns and it swaps to the dashboard. Or the opposite: a protected page flashes its layout before kicking you out. The fix is a third state. Auth is unknown until the session check returns, and while unknown the app shows a neutral shell (the logo and a skeleton), never the sign-in form and never private data.

Better still, avoid the round trip. The BFF already sees the session cookie when it serves the HTML. For app routes it can redirect a signed-out request to /sign-in?returnTo=... with a 302 before any JavaScript runs, and for signed-in requests inline a tiny bootstrap object (user ID, name, workspace) into the page. The client route guard then only handles changes after boot.

When the session ends in the middle of work

Sessions end for many reasons: the 14-day limit passes, an idle timeout fires, the person signs out in another tab, an admin revokes access, or they press "sign out everywhere" on their phone. The naive SPA handles a 401 by sending the whole page to /sign-in. Someone who spent 20 minutes on a long reply loses it. Worse, five requests fail at once and the app redirects five times.

A re-login dialog that keeps the work

Put the handling in one place: the API client. When any request gets 401 with { "error": "session_expired" }, the client pauses new requests, opens a single re-login dialog over the current page, and queues the failed request. After the person signs in again (passkey, password, or code; the BFF sets a new cookie), it replays the queue. If they cancel, or sign in as a different user, it drops the queue and reloads so no data from one account shows under another.

let reauth: Promise<void> | null = null;

export async function apiFetch(input: string, init: RequestInit = {}) {
  const isWrite = (init.method ?? "GET") !== "GET";
  const key = isWrite ? crypto.randomUUID() : null; // one key per logical write
  const send = () => fetch(input, { ...init, credentials: "same-origin",
    headers: { ...(init.headers as Record<string, string>), "X-CSRF": csrfToken(),
      ...(key ? { "Idempotency-Key": key } : {}) } });
  let res = await send();
  if (res.status !== 401) return res;
  const body = await res.clone().json().catch(() => ({}));
  if (body.error === "reauth_required" || body.error === "session_expired") {
    reauth ??= openReloginDialog(body).finally(() => { reauth = null; });
    await reauth;                 // throws if the person cancels
    res = await send();           // same key, so a repeat is not applied twice
  }
  return res;
}

Replaying a POST is only safe if the server can recognize a repeat. Send an Idempotency-Key header with every write, so a request that actually succeeded before the 401 on its reply is not applied twice. The unsaved form itself stays in component state, because nothing unmounted: the dialog sits on top.

Signing out in every tab

Sign out in one tab and the server deletes the session, but the other four tabs still show private data until their next request. Tell them right away with a BroadcastChannel (the cross-tab-sync lesson compares it with storage events). Every tab listens on a channel named auth.

On signed-out, a tab clears its query cache and in-memory stores and shows the signed-out screen. On signed-in with a different user ID, it reloads. Messages carry no secrets, only the event and the user ID.

Sign out, and sign out everywhere

1. POST /api/auth/sign-out (a POST with the CSRF check, so a hidden image tag cannot sign people out). The BFF deletes the session server-side and clears the cookie with Max-Age=0.
2. The client clears every place user data lives: the query cache, stores, sessionStorage drafts, IndexedDB databases, and service worker caches with personal responses.
3. It broadcasts signed-out to other tabs and navigates with location.replace("/sign-in"), so Back does not show the old page. Private pages are served with Cache-Control: no-store so they stay out of the HTTP cache, and a pageshow listener re-checks the session when event.persisted says the page came back from the back-forward cache.
4. Sign out everywhere in settings revokes every session and remembered device for the account, except optionally the current one. Other devices learn at their next request (a 401), or at once if the app holds a WebSocket, where the server can push a session_revoked event.

Architecture, data model and API

With the decisions made, the pieces fall into three layers. The auth pages are a small, separate bundle: sign-in, sign-up, reset, MFA, and the OAuth landing pages. They load fast and import nothing from the main app.

The app shell holds the session state, the API client with the re-login logic, and the tab channel. The BFF on the same origin owns every secret: it sets cookies, talks to Google, verifies WebAuthn, and proxies the API.

Why keep the auth pages out of the main bundle? Two reasons. A signed-out visitor should not download the whole app (often several hundred KB) to see a form with two fields. And the sign-in page is where a malicious script does the most harm, since it sees passwords as they are typed.

The fewer scripts the sign-in page loads, the fewer can be compromised. That is also why it gets the strictest Content Security Policy in the product: only our own scripts, plus the identity provider's origin for the Google button.

What the browser holds

The most important line in the data model is a negative one: no secret is a client entity. The browser never holds a password after submit, a refresh token, a provider token or a session ID it can read. What it holds is a description of the session and of where the person is in the sign-in flow.

type Session =
  | { status: "unknown" }
  | { status: "signed-out"; reason?: "expired" | "revoked" | "signed-out" }
  | { status: "signed-in"; user: { id: string; name: string; avatarUrl?: string };
      workspaceId: string; authLevel: "single" | "mfa"; authTime: number };

type SignInStep =
  | { step: "identifier" }
  | { step: "password" | "email-code"; email: string; pending: string }
  | { step: "mfa"; methods: ("webauthn" | "totp" | "sms" | "recovery")[]; pending: string }
  | { step: "sso"; redirectUrl: string }
  | { step: "done"; returnTo: string };

type DeviceSession = {              // security settings list
  id: string; current: boolean; browser: string; os: string;
  approxLocation?: string; lastSeenAt: string; rememberedForMfa: boolean;
};

The pending token deserves a word. After a correct password on an MFA account, the server returns a token that proves "first factor done for this account, 10 minutes ago" and nothing more. It lives only in memory. If the person reloads mid-MFA they start again, which is the right trade: storing it would turn a half sign-in into something an XSS bug could steal.

The API between the pages and the BFF

POST /api/auth/lookup           { email }            -> SignInStep
POST /api/auth/password         { pending, password } -> SignInStep
POST /api/auth/email-code       { pending, code }    -> SignInStep
POST /api/auth/mfa              { pending, method, response } -> SignInStep
POST /api/auth/passkeys/challenge                   -> request options JSON
POST /api/auth/passkeys/verify  { credential }       -> SignInStep
POST /api/auth/passkeys/options                     -> creation options JSON
POST /api/auth/passkeys         { credential }       -> 201, needs fresh auth
GET  /api/auth/google/start?returnTo=/projects/42    -> 302 to Google
GET  /api/auth/google/callback?code&state            -> 302 to returnTo
POST /api/auth/reset/request    { email }            -> 202 always
POST /api/auth/reset/confirm    { token, password }  -> SignInStep
POST /api/auth/sign-out                              -> 204
POST /api/auth/sessions/revoke-all                   -> 204
GET  /api/session                                    -> Session

401 { "error": "invalid_credentials" }          same for unknown email
401 { "error": "session_expired" }
401 { "error": "reauth_required", "maxAge": 600 }
429 { "error": "rate_limited" }  Retry-After: 300

Errors use a short list of stable codes, and the frontend maps each code to text. Never show the server's free-text message: it is a common source of accidental leaks ("user ana@example.com not found") and it cannot be translated. The reset request always answers 202 Accepted, whatever the email.

Accessibility, speed and monitoring

A sign-in page that a screen reader user cannot finish locks them out of the whole product, so accessibility here is not polish, it is availability. The good news is that the choices made so far (real forms, one code field, passkeys, password manager support) already do most of the work.

Accessible authentication

• Visible labels, not placeholders. Placeholders vanish when typing and are often too low in contrast. Each field has a label; hints sit under it and link with aria-describedby.
• Errors are announced and linked. On a failed submit, set aria-invalid="true" on the field, link the message with aria-describedby, and move focus to the first invalid field, or to an error summary at the top for a form-level error like "Email or password is incorrect". The screen-readers lesson covers how live regions and focus moves are read.
• Each step moves focus to its heading. When the identifier screen becomes the password screen, focus the new h1 ("Enter your password") so screen reader users hear that the page changed.
• WCAG 2.2 success criterion 3.3.8 (level AA) says no step may need a cognitive function test, such as remembering a password or transcribing a code, unless there is an alternative method or a mechanism that helps. Allowing paste and password managers, offering passkeys, and using autocomplete="one-time-code" are exactly those mechanisms. Level AA also exempts tests that ask people to recognize common objects or content they gave the site themselves, such as their own photo. Blocking paste on a code field, with no other method offered, fails it.
• Time limits are generous and recoverable. A code that expires in 10 minutes has a visible Resend link; a countdown is not announced every second.

Speed

The sign-in page is a landing page: people arrive from email, bookmarks and ads. Server-render it, keep its JavaScript under 80 KB gzipped, and keep the LCP element (usually the heading) as plain server-rendered text so it paints in under 1.5 seconds on a mid-range phone. Load the Google button script with async and reserve its space so it does not shift the layout. The moment the person submits a credential, prefetch the app shell bundle, so the page after sign-in is already in the cache when the session cookie arrives.

Monitoring without leaking

Track the funnel per step and per method: identifier shown, method chosen, MFA shown, signed in, with drop-off and time for each. If the passkey path converts better than the password path, that number is the argument for prompting more people to add a passkey. Watch error codes over time: a jump in invalid_credentials or 429 from many IPs is a credential stuffing wave, often before any other alert.

And scrub aggressively. Error trackers and real-user monitoring (RUM) tools record URLs, so strip code, state and reset token parameters before they are sent, and never log form values on auth pages.

Running it in the interview

Auth is a feature question where interviewers listen for judgment, not for every RFC. In 45 minutes you cannot cover everything in this guide. Pick the spine (methods, session, errors, session end) and show depth on one or two flows the interviewer cares about.

Say the trade-offs out loud. "I'll keep the session in an HttpOnly cookie. That means I need CSRF protection, so here is how." "The error text will be generic, which costs some honest users a moment, so I'll put the reset link right there." Interviewers remember candidates who name what their choice costs.

• "How do you protect against credential stuffing?" Rate limits per account, IP and device; breached-password checks; risk-based challenges; MFA and passkeys; alerts on error-code spikes.
• "How does sign out everywhere reach a laptop that is asleep?" The server revokes the sessions; the laptop's next request gets 401, and a WebSocket push covers open tabs immediately.
• "What changes for a mobile web view?" Google blocks OAuth sign-in in embedded web views, so open the system browser or an in-app browser tab, and keep the redirect flow.