Previewing a signed-in page on localhost

When sign-in cannot finish on http://localhost, sign the session cookie yourself with the app's own secret and set it for that origin: it is a preview of the signed-in page, not a sign-in. The shortcut skips the provider, so it proves nothing about the real login flow; test that on an address the provider accepts.

Why sign-in stops on localhost

A provider that requires an https redirect URI has nowhere to send a local http app back to. OAuth 2.0 tells authorization servers that "The redirection endpoint SHOULD require the use of TLS" (RFC 6749, §3.1.2.1, checked 2026-11-11), and a provider may enforce that by refusing to register or use an http:// address. The request is refused before your app ever sees a code.

Some providers follow the OAuth 2.0 profile for native apps, which makes loopback an exception: "Loopback redirect URIs use the "http" scheme" and "The authorization server MUST allow any port to be specified at the time of the request for loopback IP redirect URIs" (RFC 8252, §7.3, checked 2026-11-11). Check the provider's own documentation first: if it accepts http://127.0.0.1:PORT as a redirect, register that exact address and sign in normally. A temporary https tunnel in front of the local port is the other option; it needs a registration change and a public name, and it lasts only as long as the tunnel.

The shortcut needs three things from the server code: the cookie name it reads, the payload shape it verifies, and the secret it verifies with. Look for the function that reads the session cookie and the code that sets it after a successful sign-in. If the app keeps sessions in a database or an in-memory map keyed by an opaque id, there is no signed cookie to mint; use a development sign-in hook or a seeded test user instead.

Build the payload the server expects, sign it with HMAC-SHA256 using the same secret, and set name=payload.signature for the local origin. The script below is an example, not a drop-in: keep the claim names, the cookie name and the signing order your server uses, and read the secret from the same environment variable the server does.

// Local preview only. Signs the same session cookie the app would set,
// with the same secret. Never run this against a deployed server.
import crypto from 'node:crypto';

const secret = process.env.SESSION_SECRET; // the value the dev server started with
const payload = Buffer.from(JSON.stringify({
  sub: 'local-dev',
  email: 'you@example.com',
  name: 'Local Dev',
  exp: Math.floor(Date.now() / 1000) + 8 * 3600, // 8 hours
})).toString('base64url');
const signature = crypto.createHmac('sha256', secret).update(payload).digest('base64url');
console.log(`session=${payload}.${signature}`);

Start the local server with a secret made for development, then add the printed value under that cookie name in the browser's cookie store for localhost — DevTools → Application → Cookies — and reload. The cookie panel can store a cookie the server marks HttpOnly, which "Forbids JavaScript from accessing the cookie" (MDN, Set-Cookie, checked 2026-11-11); a document.cookie assignment is the quicker route only while the browser holds no HttpOnly cookie of that name yet.

A proxy bound to 127.0.0.1 that adds the Cookie header on every request lets you open the preview like any other URL. Forward each request to the app, replace the Cookie header with the minted value, and keep the listener on loopback: "Clients should listen on the loopback network interface only, in order to avoid interference by other network actors" (RFC 8252, §8.3, checked 2026-11-11).

// proxy.mjs — forward to the dev server and inject the session cookie.
import http from 'node:http';

const cookie = process.argv[2]; // name=payload.signature
http.createServer((req, res) => {
  const upstream = http.request({
    host: '127.0.0.1', port: 3000, path: req.url, method: req.method,
    headers: { ...req.headers, host: '127.0.0.1:3000', cookie },
  }, (up) => { res.writeHead(up.statusCode, up.headers); up.pipe(res); });
  upstream.on('error', (error) => { res.writeHead(502); res.end(error.message); });
  req.pipe(upstream);
}).listen(4000, '127.0.0.1');

Start the app with its public origin set to the proxy's address (for example http://localhost:4000), run node proxy.mjs 'session=…', and open http://localhost:4000. The proxy holds a credential: do not bind it to 0.0.0.0, and never deploy it.

What the preview does not test

The shortcut proves the signed-in page renders; it does not test authentication. These still need an address the provider accepts, usually a staging deploy or an https tunnel:

Treat a broken real sign-in as a separate problem; the pages on login loops and redirect URIs behind a proxy cover the common causes.

Keep the shortcut local

See also

Glossary terms used on this page: Deploy, Environment variable, Provider, Secret, Token.

Sources

All checked on 2026-11-11.


First version written with AI assistance and checked against the sources on 2026-11-11. Found a mistake? Fix it or open an issue. Text licensed under CC BY 4.0.